Account sync states in Nylas v2

You can use a connected account's sync state to determine when it's having problems and the end user needs to re-authenticate. This might happen for a number of reasons. For example, the end user might have changed their password, or Nylas' access might have been revoked by their email server.

Re-authentication is part of the normal lifecycle for connected tools, and you should plan to handle it gracefully. If you don't re-auth when an account stops syncing with your Nylas application, you lose access to the end user's account data and you no longer receive notifications about changes to the account's data.

📝 Nylas bills for all connected accounts unless their billing_state is cancelled or deleted. See the Billing documentation for more information.

Determine an account's sync state

You can determine a connected account's sync state using the sync status information in the Nylas Dashboard, or the Nylas API.

There are three ways you can find an account's sync_state outside of the Nylas Dashboard:

Subscribe to webhook triggers: (Recommended) Subscribe to the account.* webhook triggers to be notified when a connected account changes state. See Monitor sync states using webhooks for more information.
Make poll requests to the /account endpoint: This returns information for a single account, including its sync_state. If the account is in an invalid state, or the Nylas API returns a 401 response, the end user needs to re-authenticate.
Make poll requests to the Application Accounts endpoints: This returns information about connected accounts. If an account's sync_state is invalid-credentials, the end user needs to re-auth.

Monitor sync states from the Nylas Dashboard

Connected accounts can show one of the following states in the Nylas Dashboard:

Running: All email messages, folders, contacts, and calendars are syncing reliably.
Partial: The account is running, but there may be a large volume of data to be processed, or issues with the provider's servers. This state might not be reflected in the Dashboard.
Stopped: The account is not syncing because Nylas cannot access the provider's servers, or because Nylas repeatedly encountered an error.

Diagnose stopped accounts from the Nylas Dashboard

A connected account can be stopped intentionally, or may be moved to the Stopped state because Nylas could not sync the account's data. This might happen when Nylas can't communicate with the provider's servers, or when Nylas repeatedly encounters an error.

📝 Stopped accounts are still considered paid accounts because you can retrieve their historical email messages using the Nylas APIs. New data won't sync until the reason for the account moving to the Stopped state is investigated, however.

When an account moves to the Stopped state, Nylas stops trying to sync its data until further action is taken. You can follow these steps to diagnose a stopped account in the Nylas Dashboard:

From the Nylas Dashboard, navigate to the affected account's Overview page.
Click Retry sync. Nylas tries to sync the account's data with the provider.
If the account doesn't sync, use the downgrade and upgrade endpoints to try and restart it. For instructions, see the Same server error troubleshooting guide.
If downgrading or upgrading the account doesn't restart it, check its state using the /accounts endpoint. If the state is invalid, you must re-authenticate the account.

Monitor sync states using API requests

GET /a/{client_id}/accounts, GET /a/{client_id}/accounts/{id}, and GET /account requests return an account's sync_state. The supported values may vary depending on an account's sync type (simplified or detailed), as described in the table below.

Sync State	Simplified	Detailed	Description
`valid`	☑️		All email messages, folders, contacts, and calendars are syncing reliably.
`invalid`	☑️		The account has an authorization issue and needs to be re-authenticated.
`downloading`	☑️	☑️	All folders are connected and Nylas is running a historical data sync.
`running`		☑️	All email messages, folders, contacts, and calendars are syncing reliably.
`partial`		☑️	The account is encountering a temporary issue. See Partial states for more information.
`invalid-credentials`		☑️	The account's access token is invalidated and the account needs to be re-authenticated.
`exception`		☑️	The provider returned an error that Nylas' sync engine doesn't yet understand. Contact Nylas Support to troubleshoot accounts in this state.
`sync-error`		☑️	Nylas encountered an unexpected error while syncing the account. Contact Nylas Support to troubleshoot accounts in this state.
`stopped`		☑️	Nylas can't access the provider's servers or repeatedly encountered an error. You can diagnose the account in the Nylas Dashboard or re-auth it. If the account continues to fall into a `stopped` sync state, contact Nylas Support to troubleshoot it.
`initializing`		☑️	The account has been authenticated to Nylas, and Nylas is in the process of connecting to the account's folders. Accounts that use only the `email.send` scope will always be in the `initializing` state.

Accounts with limited scopes might experience recurring sync_state issues. To prevent these, be sure to authenticate your connected accounts with the required Nylas scopes.

Monitor sync states using webhooks

✨ If you upgraded to the new Nylas core architecture, some webhooks have been updated: the account.connected webhook is now the same as account.running, the account.stopped webhook is no longer generated, and the account.invalid webhook is now the same as account.stopped.

You can subscribe to the following webhook triggers to be notified when a connected account changes state:

account.running: The account is running.
account.stopped: The account is in the Stopped state.
account.invalid: The account's credentials are invalid.
account.connected: The account is connected.

For more information about account webhooks, see the list of webhook schemas.

Respond to stopped accounts

When you find an account in the stopped state, you re-authenticate it using the same process and APIs that you used for first-time authentication. Be sure to use the keep_access_token query parameter to save the token generated during the re-auth process.

It's a good security practice to revoke old access tokens when you ask an end user to re-auth their account. You can revoke any previous access tokens that you're aware of using the /oauth/revoke endpoint.

If you know that your application has cached invalid tokens, but you no longer have access to them, you can revoke all tokens using a POST /a/{client_id}/accounts/{id}/revoke-all request. Note that revoking access tokens removes access to your Nylas application, but doesn't delete the associated accounts.

Partial states

Generally, partial states indicate a temporary issue with a provider's mail server. Accounts in this state are still running, and usually recover on their own after some time.

An account may be in a partial state for any of the following reasons:

A new account hasn't finished its initial sync.
The account was recently re-authenticated.
Nylas is running a historical sync for the account.
The account has a large number of folders.

⚠️ Microsoft accounts with a large number of folders (more than 100) may enter partial states more often.
The end user deletes, changes, adds, or restricts one or more folders.
The end user has external integrations that may be impacting their email server.
The end user's email server is encountering connection or network issues.
Slow network connections.
Low bandwidth on the provider's server.
A backlog within the Nylas platform.

For Microsoft accounts, Nylas recommends archiving folders for accounts with more than 500 folders. You can use Exchange's Archive feature on any folders that don't need to be synced with Nylas. The email administrator should have more information about how their version of Exchange handles archiving.

One or more of an account's folders may not fully sync when the account is in a partial state. It's also possible that email messages won't sync. Usually, accounts recover and return to a full running state on their own.

Diagnose partial states

If a connected account is in a partial state, Nylas recommends that your Support team uses the list of potential causes to diagnose it.

🔍 Newly authenticated accounts might be in a partial state for up to a week while Nylas completes the initial sync process.

Generally, partial states are transient. If an existing account stays in a partial state for more than 24 hours and your end user experiences ongoing issues, contact Nylas Support. When you create your ticket, include as much of the following information as you can:

The affected account's ID.
If applicable, the message_ID.
If applicable, any timestamps.
Any errors that you're encountering.
Any errors that your end user is encountering.
If applicable, any custom code.
All troubleshooting steps you've taken so far.

Including as much detail as possible helps Nylas' Support team investigate your issue quickly.

Troubleshoot invalid credentials

When an end user's credentials are updated or the settings for their IMAP/SMTP or Exchange server change, their account stops syncing and its sync state changes to invalid-credentials. The affected end user must re-authenticate their account to begin syncing their data with Nylas again.

Account credentials changed

If a connected account's credentials are invalidated because they've been changed (usually when the account's password is updated), the end user must re-authenticate their account to resume syncing their data with Nylas.

⚠️ A password change usually doesn't create a new account when the end user re-authenticates, but it's possible that Nylas might auto-detect a different mail server during the re-auth process. It's important to be aware of any <ACCOUNT_ID> for your end users.

Server settings changed

If the end user changes their IMAP/SMTP or Exchange server endpoint, all of their account's previously synced Nylas API IDs are invalidated. The end user is then associated with a new connected account and a new <ACCOUNT_ID>. When they re-authenticate, their new Nylas API token is linked to the new <ACCOUNT_ID>.

⚠️ Your Nylas application must be able to detect duplicate accounts and invalidate or remove outdated account IDs in your application's cache. Otherwise, your organization will be charged multiple times for a single user.

You can revoke any old access tokens that you're aware of using the /oauth/revoke endpoint. If you know that your Nylas application has cached invalid tokens, but you no longer have access to them, you can revoke all tokens using a POST /a/{client_id}/accounts/{id}/revoke-all request.

If you detect that a user's <ACCOUNT_ID> changes, you must re-sync their data to fetch the account's updated object IDs.

Historical data sync

When you authenticate an account with Nylas, a historical data sync is run to fetch the account's data from the provider. Historical data syncs are also run periodically through a connected account's lifecycle.

When Nylas syncs an account's historical data, the account might stay in a partial state for up to a week. This timeline depends on the amount of data being synced, and you may see the account's data during the sync process. If no data is shown or the account remains in a partial state, contact Nylas Support to troubleshoot it.

As the historical sync process runs, Nylas syncs both historical and new email messages as the account catches up. When the account moves to a running state from a downloading state, you can confirm that the historical sync has completed.

Mail Sync Events

View the logs for Mail Sync status in the Nylas Dashboard under the Mailsync tab.

Events	Description
Failed to parse message.	Unable to parse message due to one or more of the following. No message received date Error parsing RAW message Processing synced messages missing `namespace_id` or `body_string` Message body too long Recipient field too long
Couldn't parse API error response.	JSON object formatting incorrect or incomprehensible.
Invalid credentails response to sync request; aborting sync. User must reauthenticate.	Settings have changed for Credentials or Server Settings. See Troubleshoot invalid credentials.
Max EAS failures reached, terminating folder sync.	Deactivates sync for the account due to folder hierarchy sync failure.
Object not found, resyncing folder hierarchy.	Client fetch or change operation no longer has valid server value for CollectionID (EAS folder ID) or ServerID. Examples include deleted items.
Encountered batch-level sync error; not persisting data for affected folder.	Continues to next batch because of an error while parsing data.
Resynced more than MAX_UID_RESYNCS in a row. Stopping sync.	With IMAP servers that issue continuous UIVALIDITY errors, Nylas tracks consecutive instances and abandons sync at `MAX_UID_RESYNCS` value.
Error authenticating; stopping sync.	Provider gives an authetnication error. Applies to Gmail and Microsoft.
Folder state loading failed due to missing folder.	Unable to find folder for `folder_id` indicating a deleted folder for engine.
Maxed out retries failing to send webhook notification email.	Webhook notification delivery attempted the maximum number of times and failed.
Error sending webhook notification email.	Confirms failed webhook notification delivery after maximum number of attempts.