Webhook and Sync Policy
Nylas lets you control how much data to sync and what data you get webhooks for. Control messages, threads, calendar events, and contacts.
When an account is connected to Nylas, you can decide when Nylas should start syncing the data. For example, you connected your account on December 1, 2022, but you want Nylas to start syncing any data created starting November 1, 2022, and not just data from the account connected date.
Data sync is set at the application level. This means for any accounts you connect to your application, Nylas will sync data based on this setting.
The data synced includes:
New Customers Sync Policy
The default is set to sync the past 30 days from when the account was connected to Nylas. Review Webhook and Sync Objects to learn how Nylas determines when to sync data.
Existing Customers Sync Policy
If you created a Nylas application before December 30, 2020, then these changes do not affect you. The field is left blank and all historical data will continue to be synced. If you do make any changes, it will only affect those accounts added after you updated the settings. Review Webhook and Data Sync Objects to learn how Nylas determines when to sync data.
If you create a new application, then the default settings of the past 30 days of data will sync.
If you are a new user on the Basics plan, you can sync data for up to 90 days before adding the account to Nylas. The default is the previous 30 days.
If you are a new user on the Essentials plan you can sync data for up to 365 days before adding the account to Nylas. The default is the previous 30 days. Please reach out to our support team to enable this functionality.
If you are a new user on the Enterprise plan, you can sync data any time in the past. The default is the previous 30 days. Please reach out to our support team to enable this functionality.
Only data that has been synced will return via API. Set your data sync policy carefully.
After configuring your sync policy, you can decide if you want to receive webhooks for the synced data. For example, if you connect an account on December 1, 2020, but only want to get webhooks starting January 1, 2021.
Webhooks are sent and controlled at the application level. This means any accounts you connect to your application will send webhooks. By default, when you connect an account, Nylas will send webhooks 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:
New Customers Webhook Policy
New users will receive webhooks starting with the Nylas account connection date. For example, if you connect your account on February 10, 2021, any data starting on that date and forward will send webhooks.
Existing Customers Webhook Policy
If you already have an account set up with webhooks as of November 10, 2020, the behavior will not change. You will still continue to receive 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 to set up webhooks for.
- From the navigation menu, click App Settings.
- On the App Settings page, click the Advanced Settings tab.
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
- 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.|
Only data that we have synced will be returned using the proxied provider search.
Keep in Mind
- Webhooks can only be sent for data that is synced, which 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 outside of the webhook sync date.
- Only data that has been synced will return via API. Set your data sync policy carefully.
- For webhooks, If you don't make any changes, the default setting is 0. Any newly connected accounts will only send data after the account connected.
- 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.
- 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.