Only show these results:

Account Sync Status

There are several ways to check account status.

Dashboard Sync States

Accounts in the dashboard will have 1 of the following states.

Running

This means every mail for every folder, contact, and calendar data is all syncing quickly and reliably.

Stopped

An account will stop syncing if it repeatedly encounters the same error or is unable to access the email server. In most cases our sync engine will retry syncing the account for some time, but if the account continuously fails to sync we stop syncing mail until further action is taken. Accounts can also stop if we encounter a non-recoverable error.

An account will also be stopped if it was stopped intentionally.

In cases where an account has stopped, you can try to restart it using the downgrade and upgrade endpoints. Here is a guide that will show you how to do this. If the account repeatedly continues to fall into a stopped sync state, please reach out support.

Stopped accounts are still considered [paid accounts](# billing), as you can still retrieve all historical mail through the Nylas API, but new mail won't sync until the specific cause of the account stoppage is investigated.

Partial

Partial states are typically temporary, and accounts in this state are still running. One or more folders in the account might not be fully synced currently or might not be syncing mail at all, but accounts typically recover and return to a full-running state.

Some reasons an account may be in a partial state:

  • It is a new account, and it hasn't finished its initial synch.
  • The account was recently re-authenticated.
  • The user deletes, changes, adds, or restricts folders
  • Slow network connections.
  • Low bandwidth on the email server.
  • A backlog within the Nylas platform.
  • A large number of folders in the user's mailbox.
  • Syncing historical data

In general, partial statuses usually indicate a temporary issue with the mail server, and accounts typically recover after some time, switching back into a full-running state.

Microsoft accounts that have a large number of folders (>100) sometimes enter partial states more frequently. To improve an Exchange account's performance and have it synchronize faster, we recommend using Exchanges Archive feature on any of the folders that do not need to be synced with Nylas. The email administrator should have more details about how their version of Exchange handles archiving.

Historical Data Sync

If you are syncing historical data, the account can stay in a partial state for up to a week. The time depends on the amount of data being synced. You should see data during this time. If there is no data, then contact support.

Diagnosing Partial Status

If an account has a partial status, we recommend that your support team checks any of the previous reasons first. A newly authenticated account can be partial for a few hours up to a few days while it completes its initial synchronization.

Otherwise, partial states are generally transient. If an existing account persists in this state for more than 24 hours and your user has expressed an issue, contact Nylas support. Be sure to include the following details so that we can troubleshoot as quickly as possible:

  • Account_ID
    • Message_ID (if applicable)
    • Timestamps (if applicable)
    • Any errors you are seeing
    • Any errors your user is seeing
    • Any issue your user is experiencing
    • Include any code (if applicable)
    • Any troubleshooting you've done so far

/account

The /account endpoint returns a sync_state.

Running

This means every mail for every folder, contact, and calendar data are all syncing quickly and reliably.

Invalid

You can only continue to use an account with our API as long as the access_token is valid. Sometimes, this token is invalidated by the provider when connection settings are changed or by the end-user when their password is changed. When this happens, you will need to re-authenticate the account and generate a new access_token for the account. You can follow this guide to re-authenticate accounts.

Stopped

An account will stop syncing if it repeatedly encounters the same error or is unable to access the email server. In most cases our sync engine will retry syncing the account for some time, but if the account continuously fails to sync we stop syncing mail until further action is taken. Accounts can also stop if we encounter a non-recoverable error.

An account will also be stopped if it was stopped intentionally.

In cases where an account has stopped, you can try to restart it using the downgrade and upgrade endpoints. Here is a guide that will show you how to do this. If the account repeatedly continues to fall into a stopped sync state, please reach out to support.

Stopped accounts are still considered paid accounts, as you can still retrieve all historical mail through the Nylas API, but new mail won't sync until the specific cause of the account stoppage is investigated.

/a/client_id/accounts/id

The /a/client_id/accounts/id endpoint returns a sync_state.

  • initializing
  • downloading
  • running
  • invalid_credentials
  • exception
  • sync_error
  • stopped

Initializing

This state indicates that the account has been authenticated on the Nylas platform and is in the process of connecting to all the account's folders.

Downloading

This state indicates that all folders are connected and the account is in the process of syncing all historical messages on the account. Depending on the size of the account and the speed of the connection between Nylas and the email server, this can take up to 24 hours or more to complete. During this time, the account is usable for sending messages and receiving new email messages.

Running

This means every mail for every folder, contact, and calendar data are all syncing quickly and reliably.

Invalid Credentials

You can only continue to use an account with our API as long as the access_token is valid. Sometimes, this token is invalidated by the provider when connection settings are changed or by the end-user when their password is changed. When this happens, you will need to re-authenticate the account and generate a new access_token for the account. You can follow this guide to re-authenticate accounts.

Exception

This can occur if an upstream provider returns an error that our sync engine does not yet understand. Please contact us for accounts in this state.

Sync Error

This means an unexpected error was raised while syncing an account. Please contact us for accounts in this state.

Stopped

An account will stop syncing if it repeatedly encounters the same error or is unable to access the email server. In cases where an account has stopped, you can try to restart it using the downgrade and upgrade endpoints. Review our Account Reauthentications guide to learn more. If the account repeatedly continues to fall into a stopped sync state, please reach out to our support team.

Webhooks

You can subscribe to the following webhook triggers to know when an account status has changed.

  • account.running - The account is running.
  • account.stopped - The account has stopped.
  • account.invalid - The account credentials are invalid.
  • account.connected - The account is connected.

Account Lifecycle

The diagram shows how an account can change states.

Account Lifecycle

What's Next?