Available webhooks
This page lists the available webhooks and what they are used for.
Webhook Object
Attribute | Type | Description |
---|---|---|
id |
string | A globally unique object identifier. |
application_id |
string | A reference to the parent application object. |
callback_url |
string | The URL where notifications are posted. |
state |
string | The state of the webhook. See the table below for possible values. |
triggers |
array | An array containing a set of triggers, describing the notifications this webhook should receive. See the triggers table for possible values. |
version |
string | A string describing the webhook version. |
[
{
"application_id": "8eejdhpc5dv04w6ea8lzlxtkt",
"callback_url": "https://your-server.com/webhook",
"id": "7b5y8f25p344jy8yem6v5jir",
"state": "active",
"triggers": [
"account.connected",
"account.running",
"account.stopped",
"account.invalid",
"account.sync_error",
"message.created",
"message.opened",
"message.updated",
"message.link_clicked",
"thread.replied",
"contact.created",
"contact.updated",
"contact.deleted",
"calendar.created",
"calendar.updated",
"calendar.deleted",
"event.created",
"event.updated",
"event.deleted",
"job.successful",
"job.failed"
],
"version": "2.0"
}
]
Minimum Required Scopes
Webhook triggers have corresponding minimum scopes. View the Nylas Scopes for the complete collection and the Authentication Scopes section for specific dependencies.
Webhook States
The state of a webhook displays its current status.
State | Description |
---|---|
active |
We are sending data for this webhook and receiving 200 responses. |
inactive |
The webhook has been turned off from the developer console, and we are not sending data for this webhook. |
failing |
Webhooks are marked as failing when Nylas has received 95% non-200 responses (or non-responses) from the endpoint over a period of 15 minutes. When this happens, we send an email to the customer notifying them of the failing webhook, and change the webhook’s state in our database to failing. Read Failing Webhooks |
failed |
Webhooks are marked as failed when we have received 95% non-200 responses (or non-responses) from the endpoint over a period of 3 days. When this happens, we send an email to the customer notifying them of the failed webhook, and change the webhook’s state in our database to failed. Read Failed Webhooks for more. |
Event Webhooks
event.created
event.updated
event.deleted
Attribute | Type | Description |
---|---|---|
deltas |
array | An array consisting of a single delta object. |
date |
Unix timestamp | A timestamp indicating when the change occurred. |
type |
string | The changed object type. Possible values are event.created , event.updated or event.deleted . |
object |
string | The trigger for this notification. |
object_data |
object | This object contains the changed object's object type, account_id , object id and an attributes sub-object. |
namespace_id |
string | Deprecated field. Refer to the account ID. |
account_id |
string | ID of the connected email account. |
object |
string | The changed object type. Will return event . |
attributes |
null | Only applicable for message webhooks. |
attributes.created_before_account_connection |
null | Indicates if the event was created before the account was connected to Nylas. Only applicable for event.created or event.updated |
id |
string | ID of the event. |
metadata |
null | Event metadata |
{
"deltas":[
{
"date":1667986398,
"object":"event",
"type":"event.created",
"object_data":{
"namespace_id":"d52ehgbft5x3pevzgnmhwumbs",
"account_id":"d52ehgbft5x3pevzgnmhwumbs",
"object":"event",
"attributes":null,
"id":"bvpgob33f3hvebfuvfndv2cvg",
"metadata":null
}
}
]
}
Event Updated Events
When events are canceled or deleted from a calendar, we send an event.updated
webhook. Event deleted webhooks are only sent when a syncback request fails. A failure can take a long time to come through. We recommend you use the event.updated
webhook.
We send an event.updated
webhook when changes are made to the following fields. Review events for more information.
title
description
when
location
owner
participants
busy
recurrence
master_event_id
original_start_time
Calendar Webhooks
- calendar.created
- calendar.updated
- calendar.deleted
Attribute | Type | Description |
---|---|---|
deltas |
array | An array consisting of a single delta object. |
date |
Unix timestamp | A timestamp indicating when the change occurred. |
type |
string | The changed object type. Possible values are calendar.created , calendar.updated or calendar.deleted . |
object |
string | The trigger for this notification. |
object_data |
object | This object contains the changed object's object type, account_id , object id and an attributes sub-object. |
namespace_id |
string | Deprecated field. Refer to the account ID. |
account_id |
string | ID of the connected email account. |
object |
string | The changed object type. Will return calendar . |
attributes |
null | Only applicable for message webhooks. |
id |
string | ID of the calendar. |
metadata |
null | Only applicable for message webhooks. |
{
"deltas": [
{
"date": 1601668428,
"object": "calendar",
"type": "calendar.updated", //can be calendar.created, calendar.updated, or calendar.deleted
"object_data": {
"namespace_id": "aaz875kwuvxik6ku7pwkqp3ah",
"account_id": "aaz875kwuvxik6ku7pwkqp3ah",
"object": "calendar",
"attributes": null,
"id": "2x6fbv82cctfjqtzex0aqll96",
"metadata": null
}
}
]
}
Calendar Updated Events
We send an calendar.updated
webhook when changes are made to the following fields. Review calendar for more information.
description
is_primary
location
name
read_only
timezone
Account Webhooks
- account.running
- account.stopped
- account.invalid
- account.connected
Attribute | Type | Description |
---|---|---|
deltas |
array | An array consisting of a single delta object. |
date |
Unix timestamp | A timestamp indicating when the change occurred. |
type |
string | The changed object type. Possible values are account.running , account.stopped , account.invalid , account.connected . |
object |
string | The trigger for this notification. |
object_data |
object | This object contains the changed object's object type, account_id , object id and an attributes sub-object. |
namespace_id |
string | Deprecated field. Refer to the account ID. |
account_id |
string | ID of the connected email account. |
object |
string | The changed object type. Will return account . |
attributes |
null | Only applicable for message webhooks. |
id |
string | ID of the webhook. |
metadata |
null | Only applicable for message webhooks. |
{
"deltas": [
{
"date": 1601672445,
"object": "account",
"type": "account.running",
"object_data": {
"namespace_id": "cg9razhjs80zqtoz50rox2n6z",
"account_id": "cg9razhjs80zqtoz50rox2n6z",
"object": "account",
"attributes": null,
"id": "cg9razhjs80zqtoz50rox2n6z",
"metadata": null
}
}
]
}
Contact Webhooks
- contact.created
- contact.updated
- contact.deleted
Attribute | Type | Description |
---|---|---|
deltas |
array | An array consisting of a single delta object. |
date |
Unix timestamp | A timestamp indicating when the change occurred. |
type |
string | The changed object type. Possible values are contact.created , contact.updated , contact.deleted . |
object |
string | The trigger for this notification. |
object_data |
object | This object contains the changed object's object type, account_id , object id and an attributes sub-object. |
namespace_id |
string | Deprecated field. Refer to the account ID. |
account_id |
string | ID of the connected email account. |
object |
string | The changed object type. Will return contact . |
attributes |
null | Only applicable for message webhooks. |
id |
string | ID of the contact. |
metadata |
null | Only applicable for message webhooks. |
{
"deltas": [
{
"date": 1601667544,
"object": "contact",
"type": "contact.updated",
"object_data": {
"namespace_id": "aaz875kwuvxik6ku7pwkqp3ah",
"account_id": "aaz875kwuvxik6ku7pwkqp3ah",
"object": "contact",
"attributes": null,
"id": "1iacfgi0qcm28734iusgzo20o",
"metadata": null
}
}
]
}
Contact Updated Events
We send an contact.updated
webhook when changes are made to the following fields. Review contacts for more information.
given_name
middle_name
surname
suffix
nickname
birthday
company_name
job_title
manager_name
office_location
notes
picture_url
emails
im_addresses
physical_addresses
phone_numbers
web_pages
groups
source
Message Webhooks
message.created
message.updated
Message Created
Attribute | Type | Description |
---|---|---|
deltas |
array | An array consisting of a single delta object. |
date |
Unix timestamp | A timestamp when the object was changed. |
object |
string | The changed object type. The value is message . . |
type |
string | The trigger type, message.created . |
object_data |
object | This object contains the changed object's object type, account_id , object id and an attributes sub-object. |
namespace_id |
string | Deprecated field. Refer to the account ID. |
account_id |
string | ID of the connected email account. |
object |
string | The changed object type. Possible values are message or metadata . Metadata will return when message tracking is enabled. |
attributes |
object | Attributes of the message. |
thread_id |
string | ID of the message thread. |
received_date |
Unix timestamp | Date the message was received. Nylas uses the email headers to determine this time. |
id |
string | ID of the message. |
metadata |
null | Message created returns null. Applicable for message tracking. |
{
"deltas": [
{
"date": 1602623196,
"object": "message",
"type": "message.created",
"object_data": {
"namespace_id": "aaz875kwuvxik6ku7pwkqp3ah",
"account_id": "aaz875kwuvxik6ku7pwkqp3ah",
"object": "message",
"attributes": {
"thread_id": "2u152dt4tnq9j61j8seg26ni6",
"received_date": 1602623166
},
"id": "93mgpjynqqu5fohl2dvv6ray7",
"metadata": null
}
}
]
}
Message Updated Events
We send an message.updated
webhook for the following event actions. Learn more about messages.
- A message is starred or un-starred.
- A message is set to read or unread.
- A message is archived.
- The message folder is changed. A message moved to the trash folder will trigger a message updated webhook. This does not mean the message has been deleted.
- The message label is changed. A message with a trash label will trigger a message updated webhook. This does not mean the message has been deleted.
- The following fields are changed:
-thread_id
-subject
-from
-to
-cc
-bcc
-reply_to
-date
-unread
-starred
-snippet
-body
-files
-events
Attribute | Type | Description |
---|---|---|
date |
Unix timestamp | The date and time the message was updated |
object |
string | The changed object. |
type |
string | The notification trigger. The value is message.updated . |
object_data |
object | Contains the changed object's sub-attributes |
namespace_id |
string | Deprecated. Refer to the account ID attribute. |
account_id |
string | The connected email account ID. |
object |
string | The changed object type. The value is message . |
attributes |
object | The attribute object |
attributes.thread_id |
string | The thread ID of the message. Returns null if the email is deleted. |
id |
string | The message ID |
metadata |
string | Returns null. Applicable for message tracking. |
{
"deltas": [
{
"date": 1640795044,
"object": "message",
"type": "message.updated",
"object_data": {
"namespace_id": "5tgncdmczat02216u7d6uypyi",
"account_id": "5tgncdmczat02216u7d6uypyi",
"object": "message",
"attributes": {
"thread_id": "4cixjtbijtxh06ai4413jfa23"
},
"id": "33lqorn5g0rgh0v8k3ge0fuyj",
"metadata": null
}
}
]
}
Message Tracking
message.opened
message.link_clicked
thread.replied
To learn more about message tracking, read Message Tracking .
Message Opened
If you have message tracking enabled, you may get 2 notifications for opened messages.
Thread ID
When link tracking is enabled, the id
value in the object_data
is the thread_id
.
Attribute | Type | Description |
---|---|---|
metadata |
object | Contains metadata for message tracking |
count |
integer | Number of times the message was opened. The count starts at 1 . Each time the message is opened from message.opened this will increase by one . |
sender_app_id |
integer | Deprecated field. |
timestamp |
Unix timestamp | Indicates the time of the most recent change such as links clicked, message was opened or thread was replied to. |
recents |
array | An array of objects containing information about the most recent times the message was opened. Each time the message is opened a new object containing the id is added. |
ip |
string | IP address of the email that opened the message. |
id |
integer | Related to the count. While the count starts at 1 . The ID starts at 0 . Each time the message is opened this will increase by one. |
timestamp |
Unix timestamp | When the IP address opened the message. |
user_agent |
string | Information about the application, operating system and browser if available. |
payload |
string | A string you can supply as part of the message tracking payload. |
message_id |
string | ID of the message. |
{
"deltas": [
{
"date": 1601655922,
"object": "metadata",
"type": "message.opened",
"object_data": {
"namespace_id": "aaz875kwuvxik6ku7pwkqp3ah",
"account_id": "aaz875kwuvxik6ku7pwkqp3ah",
"object": "metadata",
"attributes": null,
"id": "2853jlwgcp70cufxakisb4kyx",
"metadata": {
"count": 2,
"sender_app_id": 64280,
"timestamp": 1601655922,
"recents": [
{
"ip": "46.502.7.144",
"user_agent": "Mozilla/5.0 (Windows NT 5.1; rv:11.0) Gecko Firefox/11.0 (via ggpht.com GoogleImageProxy)",
"timestamp": 1601655919,
"id": 0
},
{
"ip": "66.102.7.140",
"id": 1,
"timestamp": 1601655922,
"user_agent": "Mozilla/5.0 (Windows NT 5.1; rv:11.0) Gecko Firefox/11.0 (via ggpht.com GoogleImageProxy)"
}
],
"message_id": "8ek8y0izenpumiuxs4gpp0dzq",
"payload": "Tracking enabled"
}
}
}
]
}
Message Link Clicked
Thread ID
When link tracking is enabled, the object_data > id is the thread_id
.
Attribute | Type | Description |
---|---|---|
metadata |
object | Contains metadata for message tracking. |
sender_app_id |
integer | ID of your application in the Nylas database. |
link_data |
array | Array of objects with information about any links in the message. Link data and link index are related. The first object has a link_index of 0 . The second object in link_data has a link_index of 1 . |
url |
string | The URL. |
count |
integer | Number of times the link was clicked. |
timestamp |
Unix timestamp | |
recents |
array | An array of objects containing information about the most recent times the message was opened. Each time the message is opened a new object containing the id is added. |
ip |
string | IP address of the email that opened the message. |
link_index |
integer | Link data and link index are related. The first object has a link_index of 0 . The second object in link_data has a link_index of 1 . |
id |
integer | Related to the count. While the count starts at 1 . The ID starts at 0 . Each time the message is opened this will increase by one. message.opened |
user_agent |
string | Information about the application, operating system and browser if available. |
timestamp |
||
payload |
string | A string you can supply as part of the message tracking payload. |
message_id |
string | ID of the message. |
{
"deltas": [
{
"date": 1602623989,
"object": "metadata",
"type": "message.link_clicked",
"object_data": {
"namespace_id": "aaz875kwuvxik6ku7pwkqp3ah",
"account_id": "aaz875kwuvxik6ku7pwkqp3ah",
"object": "metadata",
"attributes": null,
"id": "740ktv6tse85fyfv3u8msazvg",
"metadata": {
"sender_app_id": 64280,
"link_data": [
{
"url": "https://google.com/",
"count": 1
},
{
"url": "https://nylas.com/",
"count": 1
}
],
"timestamp": 1602623966,
"recents": [
{
"ip": "24.243.155.85",
"link_index": 0,
"id": 0,
"user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_6) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/86.0.4240.75 Safari/537.36",
"timestamp": 1602623980
},
{
"ip": "24.243.155.85",
"link_index": 1,
"id": 1,
"timestamp": 1602623989,
"user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_6) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/86.0.4240.75 Safari/537.36"
}
],
"message_id": "4utnziee7bu2ohak56wfxe39p",
"payload": "Tracking enabled"
}
}
}
]
}
Thread Replied
Thread ID
When link tracking is enabled, the object_data > id is the thread_id
.
Attribute | Type | Description |
---|---|---|
metadata |
object | Contains metadata for message tracking |
sender_app_id |
integer | ID of your application in the Nylas database. |
timestamp |
Unix timestamp | Time the thread was changed. |
from_self |
boolean | If the message sent is from the owner of the Nylas account. |
payload |
string | A string you can supply as part of the message tracking payload. |
thread_id |
string | ID of the message thread. |
reply_to_message_id |
ID of the message the thread is replying to. | |
message_id |
string | ID of the message. |
{
"deltas": [
{
"date": 1601656124,
"object": "message",
"type": "thread.replied",
"object_data": {
"namespace_id": "aaz875kwuvxik6ku7pwkqp3ah",
"account_id": "aaz875kwuvxik6ku7pwkqp3ah",
"object": "message",
"attributes": null,
"id": "7sx8258vwi6xbmxljemm40f5c",
"metadata": {
"sender_app_id": 64280,
"timestamp": 1601656110,
"from_self": true,
"payload": "Tracking enabled",
"thread_id": "27dxbayb5z7s4bfpxkibby2c5",
"reply_to_message_id": "eea24ox0libvo0gwljyx8j4ou",
"message_id": "7sx8258vwi6xbmxljemm40f5c"
}
}
}
]
}
Job Status Webhooks
- job.successful
- job.failed
Attribute | Type | Description |
---|---|---|
date |
Unix timestamp | A timestamp indicating when the change occurred. |
object |
string | The trigger for this notification. job_status for job status notifications. |
type |
string | The event status. Supported values are job.successful and job.failed . |
object_data |
object | This object contains the changed object's object information. |
object_data.namespace_id |
string | Deprecated field. Refer to the account ID. |
object_data.account_id |
string | ID of the connected email account. |
object_data.object |
string | The changed object type. Can be messages , calendar , folders , orlabels . |
object_data.attributes |
object | Attributes of the message. |
object_data.attributes.action |
text | Event that triggered the job status webhook. Can be create_calendar , update_calendar , delete_calendar , create_contact , update_contact , delete_contact , create_folder , update_folder , delete_folder , create_label , update_label , create_event , update_event , delete_event , update_message , and save_draft . |
object_data.attributes.message_id |
string | ID of the message associated with the Job. |
object_data.attributes.job_status_id |
string | ID of the job. |
object_data.attributes.extras |
object | If the job_status has a status of cancelled, delayed, or failed then extras returns in the response with more information. |
object_data.attributes.extras.reason |
string | Reason for status |
object_data.attributes.extras.original_send_at |
integer | Unix timestamp assigned from sending a message. This value reflects the initial attempt for sending. |
object_data.attributes.extras.send_at |
integer | Unix timestamp for when the message was sent. |
id |
string | A globally unique object identifier. |
metadata |
null | Message created returns null. Applicable for message tracking. |
{
"deltas": [
{
"date": 1646346704,
"object": "job_status",
"type": "job.failed",
"object_data": {
"namespace_id": "cL1PMVLIa1QXtg2HKKnuHhgxsy",
"account_id": "cL1PMVLIa1QXtg2HKKnuHhgxsy",
"object": "message",
"attributes": {
"action": "update_message",
"thread_id": null,
"extras": {
"reason": "error updating message",
"original_send_at": 1646346692,
"send_at": 1646346692
},
"message_id": null,
"job_status_id": "fKZwgtxkb4mphQSIhOxL8OmS2G"
},
"id": null,
"metadata": null
}
}
]
}