Version:
Only show these results:

Deltas in Nylas v2

In Nylas v2, the Nylas Sync Engine builds a transaction log that records each change as it synchronizes your users' mailboxes. We store those changes for the most current 14-day rolling window. Your application can use these changes, exposed through the Delta endpoint, to build email applications that process new data quickly without fetching an index of the user's mailbox or performing a large number of API calls.

Your application needs to maintain a sync cursor, a record of the last change you successfully processed. Each time you perform a sync, you process the API's deltas and update your stored cursor.

Webhooks and Deltas

For most of our customers, Webhooks are the best option to stay up to date with all email, contact and calendar changes. If you're interested in using deltas, please contact us before starting your integration.

Data sync

Deltas sync create, update, and delete data for:

  • Contacts
  • Event
  • Files
  • Messages
  • Drafts
  • Threads
  • Folders
  • Labels

Delta events

Part of the response will include an event, for example "event": "modify",. The events are:

  • Create
  • Modify
  • Delete

Sync Large Number of Accounts

If you need to sync a large number of accounts, you should use webhooks or long-polling delta endpoint. There aren't any mechanisms to throttle incoming data from the streaming endpoint; a large number of accounts could produce an amount of data that is too intensive to process. Delta streaming is also not suitable for client-based JavaScript applications.

Authentication

Deltas return data on an account level basis. Use the access_token in your requests. Deltas accept basic or bearer authentication.

How to use delta cursors

The Deltas endpoint has several options for getting delta information.

Get a delta cursor

https://api.nylas.com/delta/latest_cursor

Getting a delta cursor is the first step. You will use this cursor in other API requests to return deltas (changes).

curl --location --request POST 'https://api.nylas.com/delta/latest_cursor' \
    --header 'Authorization: Basic <base64 encoded access_token>'   
{
   "cursor": "aqb0llc2ioo0***"
}

Request deltas

https://api.nylas.com/delta?cursor=aqb0llc2ioo0***

This endpoint returns the most recent set of deltas. Use the data cursor as a query parameter to return deltas. This endpoint does not stream or poll for data. If this is your first time getting data, this could return nothing. Try making a change then requesting a delta. In rare cases, it also means that if an account has had no actual changes in the past two weeks, there may be no transactions, and you'll be given the special start cursor of '0'.

Long Polling deltas

https://api.nylas.com/delta/longpoll?cursor=aqb0llc2ioo0***

Long Polling deltas will instruct the server to keep the connection open until a change comes through or it times out. You can use this behavior on platforms that do not support partial response parsing, such as web browsers.

Timeout

Long polling deltas time out after 120 seconds.

Streaming deltas

https://api.nylas.com/delta/streaming?cursor=aqb0llc2ioo0***

Streaming deltas process real-time updates. The server connection closes after 30 minutes. You can use this for server-side applications that can parse data in real-time.

Process data

Each time your application syncs with Nylas, you provide the cursor indicating your position in the user's email history.

After processing these deltas, your application should update its stored cursor to the cursor_end value in the response. The update will make the previous cursor_end the new cursor_start in the next response. The deltas endpoint often only returns a subset of deltas available, so it's important to continue requesting deltas until your application receives a response with a value for cursor_end identical to the cursor_start, the cursor you supplied. The identical cursor_start indicates that you have requested all delta events up to the current time, and there are no other changes to process for the moment.

Historical data

During the initial sync, you will start to receive deltas for the account's entire history.

Delta Query Parameters

Deltas return a lot of data. A way to parse the data you want is to use the include_types and exclude_types. You can filter by:

  • Contacts
  • Event
  • Files
  • Messages
  • Drafts
  • Threads
  • Folders
  • Labels

Adding view=expanded to the request expands thread and message objects in the response to include additional information.

Thread objects are expanded to contain message and draft sub-objects and will remove message_ids and draft_ids. The message and draft sub-objects do not include a body parameter.

Message objects are expanded to include several additional RFC2822 headers. For more details see the Expanded Message View.

Delta Filtering

Specifying both exclude_types and include_types will result in an error.

Example: Deltas response

The following are examples of the JSON delta information that is returned for message, events, and contacts. Deltas will stream data from multiple changes.

{
  "cursor_end": "4ekj8ktel67njbaw1c0nlvbdi",
  "cursor_start": "9fboxh6t9b3ar4fwocxpwrcss",
  "deltas": [
    {
      "attributes": {
        "account_id": "aaz875kwuvxik6ku7pwkqp3ah",
        "bcc": [],
        "body": "<div dir=\"ltr\">Hi<br clear=\"all\"><div><div dir=\"ltr\" class=\"gmail_signature\" data-smartmail=\"gmail_signature\"><div dir=\"ltr\"><span><br><div dir=\"ltr\" style=\"margin-left:0pt\" align=\"left\"><table style=\"border:none;border-collapse:collapse\"><colgroup><col width=\"84\"><col width=\"540\"></colgroup><tbody><tr style=\"height:79pt\"><td style=\"vertical-align:top;padding:5pt 5pt 5pt 5pt;overflow:hidden\"><p dir=\"ltr\" style=\"line-height:1.2;margin-top:0pt;margin-bottom:0pt\"><a href=\"https://www.nylas.com/\" target=\"_blank\"><span style=\"font-size:11pt;font-family:Arial;color:rgb(17,85,204);background-color:transparent;vertical-align:baseline;white-space:pre-wrap\"><span style=\"border:none;display:inline-block;overflow:hidden;width:70px;height:70px\"><img src=\"https://lh6.googleusercontent.com/zJp7cuIKWhNYHc6KsuHUsfrhyCp9DKxg243bjSLP9JKi9SEX-uMtTAr5qy54Kdlr3RNkTwAEvIDHKBCjodqu8uVLLbReY47_-KtRilUatWsZRRfO2LH9ZTCykLEVBOj8iJ7XmNeX\" width=\"70\" height=\"70\" style=\"margin-left:0px;margin-top:0px\"></span></span></a></p></td><td style=\"vertical-align:top;padding:5pt 5pt 5pt 5pt;overflow:hidden\"><p dir=\"ltr\" style=\"line-height:1.7999999999999998;margin-top:0pt;margin-bottom:0pt\"><span style=\"font-size:10pt;font-family:&quot;Source Sans Pro&quot;,sans-serif;color:rgb(0,0,0);background-color:transparent;font-weight:700;vertical-align:baseline;white-space:pre-wrap\">Katherine Perry</span></p><p dir=\"ltr\" style=\"line-height:1.38;margin-top:0pt;margin-bottom:0pt\"><span style=\"font-size:8pt;font-family:&quot;Source Sans Pro&quot;,sans-serif;color:rgb(0,0,0);background-color:transparent;vertical-align:baseline;white-space:pre-wrap\">Lead Technical Writer, </span><a href=\"https://www.nylas.com/\" target=\"_blank\"><span style=\"font-size:8pt;font-family:&quot;Source Sans Pro&quot;,sans-serif;color:rgb(0,0,0);background-color:transparent;vertical-align:baseline;white-space:pre-wrap\">Nylas</span></a></p><p dir=\"ltr\" style=\"line-height:1.38;margin-top:0pt;margin-bottom:0pt\"><span style=\"font-size:8pt;font-family:&quot;Source Sans Pro&quot;,sans-serif;color:rgb(0,0,0);background-color:transparent;vertical-align:baseline;white-space:pre-wrap\">email@example.com</span></p></td></tr><tr style=\"height:63pt\"><td colspan=\"2\" style=\"vertical-align:top;padding:5pt 5pt 5pt 5pt;overflow:hidden\"><p dir=\"ltr\" style=\"line-height:1.2;margin-top:0pt;margin-bottom:0pt\"><a href=\"https://www.nylas.com/resources/savings-calculator-integrations/\" target=\"_blank\"><span style=\"font-size:11pt;font-family:Arial;color:rgb(17,85,204);background-color:transparent;vertical-align:baseline;white-space:pre-wrap\"><span style=\"border:none;display:inline-block;overflow:hidden;width:306px;height:45px\"><img src=\"https://lh3.googleusercontent.com/bTFwY25C4D9lD4GJHxsVEWr8--YG25chLhjDJb3rWpmXPw5RngwZHUWhbDracmaXL7n6mtt5JPM9egiGaFwU2bNKMrvMcctgvrHFOI7YxIzze7CTKKVJRqD8kq2hNUE2IJiPWFmL\" width=\"306\" height=\"45\" style=\"margin-left:0px;margin-top:0px\"></span></span></a></p></td></tr></tbody></table></div></span></div></div></div></div>",
        "cc": [],
        "date": 1602001027,
        "events": [],
        "files": [],
        "from": [{
          "email": "email@example.com",
          "name": "Katherine Perry"
        }],
        "id": "52m5un5v1m7rjigna5agc7y35",
        "labels": [{
          "display_name": "Sent Mail",
          "id": "ertg5obp5nvn43xtqe2e55en0",
          "name": "sent"
        }],
        "object": "message",
        "reply_to": [],
        "snippet": "Hi Katherine PerryLead Technical Writer, Nylasemail@example.com",
        "starred": false,
        "subject": "New Message",
        "thread_id": "chvd75bowkhg3gfpgeeygcxbb",
        "to": [{
          "email": "swag@example.com",
          "name": "Katherine Personal"
        }],
        "unread": false
      },
      "cursor": "8hhvivgus0fbo4qengko8c38x",
      "event": "create",
      "id": "52m5un5v1m7rjigna5agc7y35",
      "object": "message"
    },
    {
      "attributes": {
        "account_id": "aaz875kwuvxik6ku7pwkqp3ah",
        "draft_ids": [],
        "first_message_timestamp": 1602001027,
        "has_attachments": false,
        "id": "chvd75bowkhg3gfpgeeygcxbb",
        "labels": [{
          "display_name": "Sent Mail",
          "id": "ertg5obp5nvn43xtqe2e55en0",
          "name": "sent"
        }],
        "last_message_received_timestamp": null,
        "last_message_sent_timestamp": 1602001027,
        "last_message_timestamp": 1602001027,
        "message_ids": [
          "52m5un5v1m7rjigna5agc7y35"
        ],
        "object": "thread",
        "participants": [
          {
            "email": "swag@example.com",
            "name": "Katherine Personal"
          },
          {
            "email": "email@example.com",
            "name": "Katherine Perry"
          }
        ],
        "snippet": "Hi Katherine PerryLead Technical Writer, Nylasemail@example.com",
        "starred": false,
        "subject": "New Message",
        "unread": false,
        "version": 0
      },
      "cursor": "4ekj8ktel67njbaw1c0nlvbdi",
      "event": "create",
      "id": "chvd75bowkhg3gfpgeeygcxbb",
      "object": "thread"
    }
  ]
}   
{
  "cursor_end": "96aqkq87sx03rlubs7asypxc6",
  "cursor_start": "1bi2z30d3j1gc8hn2i0hnwnj9",
  "deltas": [
    {
      "attributes": {
        "account_id": "aaz875kwuvxik6ku7pwkqp3ah",
        "birthday": null,
        "company_name": null,
        "emails": [{
          "email": "swag@example.com",
          "type": "personal"
        }],
        "given_name": null,
        "groups": [],
        "id": "ce6t2ao34czmxwc4g6s9a5abj",
        "im_addresses": [],
        "job_title": null,
        "manager_name": null,
        "middle_name": null,
        "nickname": null,
        "notes": null,
        "object": "contact",
        "office_location": null,
        "phone_numbers": [],
        "physical_addresses": [],
        "picture_url": null,
        "source": "address_book",
        "suffix": null,
        "surname": null,
        "web_pages": []
      },
      "cursor": "96aqkq87sx03rlubs7asypxc6",
      "event": "create",
      "id": "ce6t2ao34czmxwc4g6s9a5abj",
      "object": "contact"
    }
  ]
}   
{
  "cursor_end": "eriw84u83to84glfjq1c5inai",
  "cursor_start": "dwf7qqy44e5mfc7tgoi7ldp56",
  "deltas": [
    {
      "attributes": {
        "account_id": "aaz875kwuvxik6ku7pwkqp3ah",
        "busy": true,
        "calendar_id": "947kpa7ih22bfkeujpkfqn5bg",
        "description": null,
        "ical_uid": "32ie0kqu5h37330k7tqij1l89d@google.com",
        "id": "6sm4dnqkrra0icirvz8tclzpv",
        "location": null,
        "message_id": null,
        "object": "event",
        "owner": " <email@example.com>",
        "participants": [],
        "read_only": false,
        "status": "cancelled",
        "title": "Coffee",
        "when": {
          "end_time": 1602183600,
          "object": "timespan",
          "start_time": 1602181800
        }
      },
      "cursor": "7wgy2rlv573p6ju96zvuiddee",
      "event": "create",
      "id": "6sm4dnqkrra0icirvz8tclzpv",
      "object": "event"
    },
    {
      "attributes": {
        "account_id": "aaz875kwuvxik6ku7pwkqp3ah",
        "busy": true,
        "calendar_id": "947kpa7ih22bfkeujpkfqn5bg",
        "description": null,
        "ical_uid": "4mdrhtl00turfmurpltgfm3fqn@google.com",
        "id": "9i5v1i2ojnspg8wombldk1lgc",
        "location": null,
        "message_id": null,
        "object": "event",
        "owner": " <email@example.com>",
        "participants": [],
        "read_only": false,
        "status": "cancelled",
        "title": "Coffee",
        "when": {
          "end_time": 1602187200,
          "object": "timespan",
          "start_time": 1602185400
        }
      },
      "cursor": "48rpp2dfyye6i9ahqjality5f",
      "event": "create",
      "id": "9i5v1i2ojnspg8wombldk1lgc",
      "object": "event"
    },
    {
      "attributes": {
        "account_id": "aaz875kwuvxik6ku7pwkqp3ah",
        "busy": true,
        "calendar_id": "947kpa7ih22bfkeujpkfqn5bg",
        "description": null,
        "ical_uid": "2nnlnmcehr12180v19jp26r4kn@google.com",
        "id": "cdnaohh65u2ro4d2vwl828w46",
        "location": null,
        "message_id": null,
        "object": "event",
        "owner": " <email@example.com>",
        "participants": [],
        "read_only": false,
        "status": "confirmed",
        "title": "hi",
        "when": {
          "end_time": 1602196200,
          "object": "timespan",
          "start_time": 1602194400
        }
      },
      "cursor": "eriw84u83to84glfjq1c5inai",
      "event": "create",
      "id": "cdnaohh65u2ro4d2vwl828w46",
      "object": "event"
    }
  ]
}