Nylas API and Sync Architecture Overview
The Nylas API makes it easy to connect and sync mail, calendar, and contact data from any email service provider. Below is a diagram showing you how your application can use the Nylas API to sync data from providers like GSuite and Microsoft.
🗄 Data storage
When you authenticate an account to Nylas, one of our sync servers will claim the account and automatically start syncing mail, calendar, and contact data into Nylas' sharded MySQL database. We store mail, contact, and calendar data indefinitely in our database until it is deleted by an API request or the account is deleted from our system.
Further, we sync all data for an account, sometimes called "historical mail". This means if you authenticate an account that has 10 years worth of data, we will sync that into our system. There are various filtering mechanisms on our API that allow you to filter out unwanted data when making API requests.
We also cache files, attachments, and copies of the raw RFC-2822 MIME message in an Amazon S3 bucket for 7 days. If you request the raw message within the first seven days, we'll return our cached copy from S3. After that, we'll delete the extra copy of the raw message from S3, and any further requests for the data will be proxied to the original mail server to re-retrieve the original data.
⚡️ Performance
Here are some commonly requested performance stats around our API uptime and sync latencies. You can subscribe to our status page about system wide performance and status incidents.
Note
These are approximations and actual performance may vary per provider. These mainly serve to provide a rough estimate when thinking about designing your application with our API. Please reference your master service agreement for specific guarantees regarding performance.
| Metric | Value | Description |
|---|---|---|
| API Success Rate | 99.9% | Number of requests that return successful HTTP status codes |
| P90(request_time) | 1000ms | P90 of request_time to various API endpoints |
| TT50 | 5 min | During initial sync, the average time it takes to sync the first 50 threads for an account. |
| TT500 | 25 min | During initial sync, the average time it takes to sync the first 500 threads for an account. |
| Historical Sync Time | 1 day | The average time it takes to sync all historical mail for an account. Highly variable depending on how much data the account has and the upstream bandwidth of the mail server |
| Sync Latency | 30s | Time for new messages or changes to data on the mail server to be synced into Nylas database. |
| Syncback Latency | 30s | Time for modifications through the Nylas API to be synced back to the mail provider. |
👩🚀 Account Lifecycle Diagram
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 - An account in this state indicates that all email messages are synced in real time and the account is running as expected.
partial - On occasion, and account can get into a partial state which means that one or more folders of the account are not fully synced at the moment. There are many reasons an account can be in a partial state including slow network connections, errors, or a backlog within the Nylas platform. It's best to check the Nylas status page (https://status.nylas.com) to see if there is an ongoing problem being investigated before reaching out to support about an account in a Partial state. If an account remains in a Partial state for a prolonged period of time and there is no adverse status on the Nylas status page, please reach out to us here.
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.
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. 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 us here.
cancelled - An account can be put into a canceled state by using the downgrade endpoint. An account can be downgraded if, for example, an end user has failed to pay for their account usage within your application. When the account needs to be re-activated, this can be accomplished by similarly using the upgrade endpoint. To learn more about how you can use these endpoints, please see this guide. Please note that an account in a canceled state will still be billed for the month since it was active during the month prior to its cancellation.
deleted - If an account remains in a canceled state for longer than 30 days, it will be marked as deleted. Conversely, if an account is deleted from the dashboard, it will automatically be set to a deleted state. Accounts that are deleted can be subsequently re-enabled by using the upgrade endpoint. The account can also be re-established by re-authentication.