Only show these results:

Account Sync Status

There are several ways to check account status.

Nylas charges your account if its billing_state was set to paid for any period of time in the previous month, regardless of the account's sync state. Learn more about Billing.

Monitoring sync states in the Nylas Dashboard

Accounts in the Dashboard have one of the following states.


All emails for folders, contacts, and calendars are syncing reliably.


An account stops syncing if it repeatedly encounters the same error or is unable to access the email server. In most cases our sync engine retries syncing the account for some time. However, 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 also stops if it was stopped intentionally.

Diagnosing Stopped Status

Try the steps in the following order:

  1. Try to restart the account by clicking Retry Sync on the account page.
  2. In cases where an account has stopped, you can try to restart it using the downgrade and upgrade endpoints. The Same Server Error guide explains the process more.
  3. Look at the account state using the Account endpoint, if the status is invalid, follow the steps for account invalid status.

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


Partial states are typically temporary and may indicate issues with the mail server. Accounts in this state, however, are still running.

One or more folders in the account may not fully sync currently or not sync mail at all. Typically, accounts recover and return to a full-running state.

Some reasons an account may be in a partial state:

  • It's a new account and hasn't finished its initial sync.
  • The account was recently reauthenticated.
  • 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
  • The user has external integrations that may be slowing down their email server.
  • The user’s email server has connection or network issues.
  • Microsoft accounts with numerous folders.

Keep in Mind

Microsoft accounts with a large number of folders (>100) may enter partial states more frequently.

For Microsoft accounts, consider archiving folders if there are over 500 folders. Use Exchanges Archive feature on any of the folders that don't need to be synced with Nylas. The email administrator should have more details about how their version of Exchange handles archiving.

In general, partial statuses indicate a temporary issue with the mail server, and accounts typically recover after some time. Recovering accounts switch back into a full-running state as soon as possible.

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 and you may see data during this time. If there is no data, then contact support.

During this time, both historical and new emails sync as the account catches up. When the account moves into a running status from a downloading state, you can confirm that historical sync has completed.

Diagnosing Partial Status

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

Partial states are generally transient. If an existing account persists in this state for more than 24 hours and your user has ongoing issues, contact Nylas support. Include as much detail from the following points for troubleshooting as quickly as possible.

  • Account_ID
    • Message_ID (if applicable)
    • Timestamps (if applicable)
    • Errors you are seeing
    • Errors your user is seeing
    • Issue your user is experiencing
    • Code (if applicable)
    • Troubleshooting you've done so far

Monitoring sync states using API requests

GET /a/-client_id-/accounts, GET /a/-client_id-/accounts/id, and GET /account requests return the sync_state of the account. Supported sync_state values vary depending on your account sync type (simplified or detailed).

Accounts with limited scopes may experience recurring sync_state issues. Review the required Nylas Scopes for your accounts during authentication.

Sync state Simplified Detailed Description
valid x All emails for folders, contacts, and calendars are syncing reliably.
invalid x The account has an authorization issue and needs to be re-authenticated. Learn more about Account re-authentication.
downloading x x 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 x All emails for folders, contacts, and calendars are syncing reliably.
partial x See Partial.
invalid-credentials x 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, reauthenticate the account and generate a new <ACCESS_TOKEN> for the account. Learn more about Account re-authentication.
exception x This can occur if an upstream provider returns an error that Nylas's sync engine doesn't yet understand. Please contact us for accounts in this state.
sync-error x An unexpected error was raised while syncing an account. Please contact us for accounts in this state.
stopped x An account stops 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. Learn more about Account re-authentication. If the account continues to fall into a stopped sync state, please contact us.
initializing x The account has been authenticated on the Nylas platform and is in the process of connecting to all the account's folders. Accounts that use email.send as the only scope will always be in an initializing state. Nylas uses folders to determine sync status. email.send doesn't fetch folders.

Monitoring sync states using webhooks

New Nylas Core Architecture

If you have upgraded to the new Nylas core architecture,

  • account.connected is the same as account.running.
  • account.stopped isn't emitted. account.invalid is the same as account.stopped.

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

More resources