Historical sync and webhook settings in Nylas v2
Nylas lets you control how much data to sync from accounts that connect to your Nylas application, and allows you to control what historical data you get webhook notifications for. You can control if you sync and receive webhook notifications for messages, threads, calendar events, and contacts.
You should always configure your webhook settings before you let accounts connect to your application. This can prevent Nylas from syncing data you don't need or won't use, and can prevent you from being flooded with unneeded webhook notifications.
Sync policy
When an end-user connects to your application, Nylas starts syncing their data so that you can query and interact with it, and get notifications about changes. By default, Nylas syncs the last 30 days of end-user data, but paid plans can configure the date in the past where Nylas begins syncing.
The data synced includes:
- Messages
- Threads
- Contacts
- Events
As an example, imagine you have an account that connected on February 1, 2023. You can configure Nylas to sync data no more than two months prior to the account connecting to your application. In the case of your March 1 account, instead of just syncing user data from Feb 1 and later, Nylas can start syncing any data January 1, 2023 and later.
Good to know: You configure your data sync from the Nylas application settings. This means that any accounts that connect to your application get their sync setting from your Nylas application.
API Data
Only data that has been synced can be returned using the Nylas API. Set your data sync policy carefully.
Webhook policy
When you configure your sync policy, you can also decide if you want to receive webhooks for the historical synced data, and not just new data after the account connects. For example, you might connect an account on December 1 2020 and sync back to November 1 2020, but you only want to get webhooks starting January 1, 2021.
Webhooks are sent and controlled at the Nylas application level. This means any end-user accounts that connect to your application will trigger webhook notifications. By default, when you connect an account, Nylas send webhooks only for data from and after the account connection date. Review Webhook and Data Sync Objects to learn how Nylas determines when to sync data.
The webhooks include:
- Messages
- Threads
- Contacts
- Events
New users after November 10, 2020 trigger webhooks starting from the date they connect their account. For example, if you connect your account on February 10, 2021, any data starting on that date and forward will send webhooks. Users connected previous to Nov 10, 2020 trigger all webhooks.
Configure webhook and sync policy
Using the webhook and sync settings, you can set a period to start syncing data and receiving webhooks.
To configure your settings:
- Log in to the Nylas dashboard, and choose the application that you want configure.
- From the navigation menu, click App Settings.
- On the App Settings page, click Advanced Settings.
The page includes Sync Policy and Webhook Policy sections. Each section has the following options:
- Before the account is connected - This setting controls if Nylas syncs data from before the account was connected to Nylas. The setting is number of days before the account connected. For example, to sync data from 30 days before the account was connected, enter
30. - The day the account is connected - This setting syncs objects that were created when the account was added to Nylas.
You can set sync and webhook policies independently. For example, you can start to sync data but not receive webhooks until a later date.
Webhook and data sync objects
To determine when to sync historic data or send historic data webhooks, Nylas compares the date and time the account was connected to the object.
| Object | Sync Policy | Webhook Policy |
|---|---|---|
| Messages | Received date | Received date |
| Thread | Most recent received date. Threads can be incomplete if the sync date is not far enough in the past. Make sure to sync to the start of the threads. | Most recent received date. Threads can be incomplete if the sync date is not far enough in the past. Make sure to sync to the start of the threads. |
| Events | Recurring Events - Final event end time. Non-recurring events use the event end time, if the event end time is not available, uses the event start time. | Recurring Events - Final event end time. Non-recurring events use the event end time, if the event end time is not available, uses the event start time. |
| Contacts | Address book contacts are synced in full. Parsed contacts from emails or messages follow the historical sync date. See the Parsed vs Synced Contacts guide for more. | Contacts that have been automatically created from an email will send webhooks from the message received date. All other contacts have no restrictions for historical webhooks and you will still receive hooks for them, regardless of dashboard settings. |
Search
Only data that Nylas has already synced is returned using the proxied provider search.
Keep in mind
- Nylas only sends webhooks for data that it has synced. This means the date that webhooks start sending has to be on or after the date that objects start syncing. You will not get webhooks for any data earlier than the webhook sync date.
- Only data that has been synced can be returned through the API. If you use the search and other APIs, set your data sync policy carefully so that you can access data needed for your application's functionality.
- The webhook historical sync setting defaults to 0 days prior to the end-user account connection. This means that new end-user accounts that connect only send webhook notifications for changes after they connect to your application.
- You might see incomplete conversations in Threads if the conversation has been going on for longer than your sync date accommodates. Make sure to sync to the start of the threads.
- Webhook policy only applies to new applications. If you are an existing customer as of November 10, 2020, no changes have been made.
- You should configure your webhook settings before adding accounts.
- Webhook settings can be changed, the updates only apply to accounts connected after the settings are changed.
- The amount of data you can sync is limited by your plan.
- It can take up to 24 hours for an account to fully sync.