Deltas
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 reach out to 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>' Delta Cursor Response
{
"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 does not close. 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.
Deltas Response Examples
The following are examples of the delta information that returns 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:"Source Sans Pro",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:"Source Sans Pro",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:"Source Sans Pro",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:"Source Sans Pro",sans-serif;color:rgb(0,0,0);background-color:transparent;vertical-align:baseline;white-space:pre-wrap\">[email protected]</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 protected]",
"name": "Katherine Perry"
}
],
"id": "52m5un5v1m7rjigna5agc7y35",
"labels": [
{
"display_name": "Sent Mail",
"id": "ertg5obp5nvn43xtqe2e55en0",
"name": "sent"
}
],
"object": "message",
"reply_to": [],
"snippet": "Hi Katherine PerryLead Technical Writer, [email protected]",
"starred": false,
"subject": "New Message",
"thread_id": "chvd75bowkhg3gfpgeeygcxbb",
"to": [
{
"email": "[email protected]",
"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": "[email protected]",
"name": "Katherine Personal"
},
{
"email": "[email protected]",
"name": "Katherine Perry"
}
],
"snippet": "Hi Katherine PerryLead Technical Writer, [email protected]",
"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": "[email protected]",
"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": "[email protected]",
"id": "6sm4dnqkrra0icirvz8tclzpv",
"location": null,
"message_id": null,
"object": "event",
"owner": " <[email protected]>",
"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": "[email protected]",
"id": "9i5v1i2ojnspg8wombldk1lgc",
"location": null,
"message_id": null,
"object": "event",
"owner": " <[email protected]>",
"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": "[email protected]",
"id": "cdnaohh65u2ro4d2vwl828w46",
"location": null,
"message_id": null,
"object": "event",
"owner": " <[email protected]>",
"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"
}
]
}