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.
Diagnosing Stopped Status
Try the steps in the following order:
- Try to restart the account by clicking Retry Sync on the account page.
- 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.
- 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
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 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.
initializingdownloadingrunninginvalid-credentialsexceptionsync-errorstopped
New Nylas Core Architecture
If you have upgraded to the new Nylas core architecture, if an account status is initializing or downloading, you can consider the account status to be running.
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. Accounts that use email.send as the only scope, will always be in an initializing state. We use folders to determine sync status. Email.send does not fetch 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.
Keep in Mind
Accounts with limited scopes may experience recurring sync_state issues. Review the required Nylas Scopes for your accounts during authentication.
Monitoring Sync Status
Use the following techniques to know which state your accounts are in.
Webhooks
New Nylas Core Architecture
If you have upgraded to the new Nylas core architecture, account.connected is the same as account.running.
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 Endpoint
Add the account endpoint in your application to monitor your sync status.
Account Lifecycle
The diagram shows how an account can change states.
