Only show these results:

Account Sync Status

There are several ways to check account status.

Dashboard Sync States

Accounts in the Dashboard have one of the following states.

Running

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

Stopped

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.

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. If the account repeatedly continues to fall into a stopped sync state, reach out to support.

Stopped accounts are still considered [paid accounts](# billing, 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

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.

Any email created on the user’s email server before the account is connected to Nylas syncs via historical sync. When an account is connected initially, historical sync is triggered and the account begins in a downloading state.

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 to 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

Account Endpoint

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 when the end-user changes their password. When this happens, you need to reauthenticate the account and generate a new <ACCESS_TOKEN> for the account. You can follow the Account Reauthentication guide for more on the process.

Stopped

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, 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 also stops if it was stopped intentionally.

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.. 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. However, new mail won't sync until the specific cause of the account stoppage is investigated.

Account Management

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 reauthenticate the account and generate a new <ACCESS_TOKEN> for the account. You can follow the Account Reauthentication guide to reauthenticate 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 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. 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?