Version:
Only show these results:

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.

ℹ️ Historical sync policy is available for v2 Entry, Core, and Plus plans. Entry plans can sync account data up to 30 days prior to authentication. Core can sync 90 days, and custom plans are available for Plus customers.

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:

  1. Log in to the Nylas dashboard, and choose the application that you want configure.
  2. From the navigation menu, click App Settings.
  3. 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.

The Nylas Dashboard "App settings" page. The "Advanced settings" tab is selected, and the "Sync Policy" and "Webhook Policy" settings are shown.

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 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.

What's next?