Only show these results:

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://97a5db5e7c59.ngrok.io/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

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

When events are canceled or deleted from a calendar, we send an event.updated webhook. Event deleted webhooks are only sent when a synback request fails. A failure can take a long time to come through. We recommend you use the event.updated webhook.

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.
id string ID of the event.
metadata null Only applicable for message webhooks.
    {
"deltas": [
{
"date": 1601665341,
"object": "event",
"type": "event.created",
"object_data": {
"namespace_id": "aaz875kwuvxik6ku7pwkqp3ah",
"account_id": "aaz875kwuvxik6ku7pwkqp3ah",
"object": "event",
"attributes": null,
"id": "85iy1r26e1x79qtir27fr0nos",
"metadata": null
}
}
]
}

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",
"object_data": {
"namespace_id": "aaz875kwuvxik6ku7pwkqp3ah",
"account_id": "aaz875kwuvxik6ku7pwkqp3ah",
"object": "calendar",
"attributes": null,
"id": "2x6fbv82cctfjqtzex0aqll96",
"metadata": null
}
}
]
}

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
}
}
]
}

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

message.updated will fire when:

  • A message is starred or unstarred
  • 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.
Attribute Type Descrioption
date Unix timestamp 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 This object contains the changed object's. sub-attributes.
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 message.
attributes null or object For message.created only.
id string ID of the message
metadata string Message updates returns null. Applicable for message tracking.
{
"deltas": [
{
"date": 1620256936,
"object": "message",
"type": "message.updated",
"object_data": {
"namespace_id": "5tgncdmczat02216u7d6uypyi",
"account_id": "5tgncdmczat02216u7d6uypyi",
"object": "message",
"attributes": null,
"id": "5v8ryr2i17h55tiufr815xoyl",
"metadata": null
}
}
]
}

Message Tracking

  • message.opened
  • message.link_clicked
  • thread.replied

To learn more about, 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 object_data > id 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 this will increase by one. message.opened`
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"
}
}
}
]
}

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.
object_data object This object contains the changed object"s object type, account_id, object id and an attributes sub-object.
account_id string ID of the connected email account.
attributes object Attributes of the message.
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, save_draft.
job_status_id string ID of the job status webhook.
id string A globally unique object identifier.
metadata null Message created returns null. Applicable for message tracking.
namespace_id string Deprecated field. Refer to the account ID.
object string The changed object type. Can be messages, calendar, folders, orlabels
type string The event type. Possible values are job.successful or job.failed.
    {
"deltas": [
{
"date": 1617379487,
"object": "job_status",
"object_data": {
"account_id": "6aul4carjbk6c37djn8297q",
"attributes": {
"action": "save_draft",
"job_status_id": null
},
"id": "598tydn0le0pdmc83uz3",
"metadata": null,
"namespace_id": "6aul4carjbk6c37djn8297q",
"object": "message"
},
"type": "job.successful"
}
]
}

{
"deltas": [
{
"date": 1617382260,
"object": "job_status",
"object_data": {
"account_id": "6aul4carjbk6c37djn8297q",
"attributes": {
"action": "save_draft",
"job_status_id": null
},
"id": "598tydn0le0pdmc83uz3",
"metadata": null,
"namespace_id": "6aul4carjbk6c37djn8297q",
"object": "message"
},
"type": "job.failed"
}
]
}