Nylas Docs

The Nylas Developer Hub

Welcome to the Nylas developer hub. You'll find comprehensive guides and documentation to help you start working with Nylas as quickly as possible, as well as support if you get stuck. Let's jump right in!

Developer Guide

Available Webhooks

Webhook objects and examples available on Nylas.

Webhook Object

AttributeTypeDescription
idstringA globally unique object identifier.
application_idstringA reference to the parent application object.
callback_urlstringThe URL where notifications are posted.
statestringThe state of the webhook. See the table below for possible values.
triggersarrayAn array containing a set of triggers, describing the notifications this webhook should receive. See the triggers table for possible values.
versionstringA string describing the 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.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"
        }
    ]

Webhook States

StateDescription
activeWe are sending data for this webhook and receiving 200 responses.
inactiveThe webhook has been disabled from the developer console, and we are not sending data for this webhook.
failingWebhooks 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
failedWebhooks 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 cancelled, you might expect to receive an event.deleted trigger. These types of events come through as event.updated. We only send event.deleted triggers when the object is deleted from Nylas' database.

AttributeTypeDescription
deltasarrayAn array consisting of a single delta object.
dateunix timestampA timestamp indicating when the change occurred.
objectstringThe changed object type. Possible values are event.created, event.updated or event.deleted.
typestringThe trigger for this notification.
object_dataobjectThis object contains the changed object's object type, account_id, object id and an attributes sub-object.
namespace_idstringDeprecated field. Refer to the account ID.
account_idstringID of the connected email account.
objectstringThe changed object type. Will return event.
attributesnullOnly applicable for message webhooks.
idstringID of the event.
metadatanullOnly 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
AttributeTypeDescription
deltasarrayAn array consisting of a single delta object.
dateunix timestampA timestamp indicating when the change occurred.
objectstringThe changed object type. Possible values are calendar.created,
calendar.updated or calendar.deleted.
typestringThe trigger for this notification.
object_dataobjectThis object contains the changed object's object type, account_id, object id and an attributes sub-object.
namespace_idstringDeprecated field. Refer to the account ID.
account_idstringID of the connected email account.
objectstringThe changed object type. Will return calendar.
attributesnullOnly applicable for message webhooks.
idstringID of the calendar.
metadatanullOnly 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
AttributeTypeDescription
deltasarrayAn array consisting of a single delta object.
dateunix timestampA timestamp indicating when the change occurred.
objectstringThe changed object type. Possible values are account.running, account.stopped, account.invalid, account.connected.
typestringThe trigger for this notification.
object_dataobjectThis object contains the changed object's object type, account_id, object id and an attributes sub-object.
namespace_idstringDeprecated field. Refer to the account ID.
account_idstringID of the connected email account.
objectstringThe changed object type. Will return account.
attributesnullOnly applicable for message webhooks.
idstringID of the webhook.
metadatanullOnly 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
AttributeTypeDescription
deltasarrayAn array consisting of a single delta object.
dateunix timestampA timestamp indicating when the change occurred.
objectstringThe changed object type. Possible values are contact.created, contact.updated, contact.deleted.
typestringThe trigger for this notification.
object_dataobjectThis object contains the changed object's object type, account_id, object id and an attributes sub-object.
namespace_idstringDeprecated field. Refer to the account ID.
account_idstringID of the connected email account.
objectstringThe changed object type. Will return contact.
attributesnullOnly applicable for message webhooks.
idstringID of the contact.
metadatanullOnly 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
AttributeTypeDescription
deltasarrayAn array consisting of a single delta object.
dateunix timestampA timestamp when the object was changed.
objectstringThe changed object type. The value is message.created.
typestringThe trigger for this notification.
object_dataobjectThis object contains the changed object's object type, account_id, object id and an attributes sub-object.
namespace_idstringDeprecated field. Refer to the account ID.
account_idstringID of the connected email account.
objectstringThe changed object type. Possible values are message or metadata. Metadata will return when message tracking is enabled.
attributesobjectAttributes of the message.
thread_idstringID of the message thread.
received_dateUnix timestampDate the message was received. Nylas uses the email headers to determine this time.
idstringID of the message.
metadatanullMessage 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 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.

AttributeTypeDescription
metadataobjectContains metadata for message tracking
countintegerNumber 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_idintegerDeprecated field.
timestampunix timestampIndicates the time of the most recent change such as links clicked, message was opened or thread was replied to.
recentsarrayAn 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.
ipstringIP address of the email that opened the message.
idintegerRelated 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.
timestampunix timestampWhen the IP address opened the message.
user_agentstringInformation about the application, operating system and browser if available.
payloadstringA string you can supply as part of the message tracking payload.
message_idstringID 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.

AttributeTypeDescription
metadataobjectContains metadata for message tracking
sender_app_idintegerID of your application in the Nylas database.
link_dataarrayArray 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.
urlstringThe URL.
countintegerNumber of times the link was clicked.
timestampunix timestamp
recentsarrayAn 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.
ipstringIP address of the email that opened the message.
link_indexintegerLink 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.
idintegerRelated 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_agentstringInformation about the application, operating system and browser if available.
timestamp
payloadstringA string you can supply as part of the message tracking payload.
message_idstringID 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

📘

Message ID

When link tracking is enabled, the object_data id is the message_id.

AttributeTypeDescription
metadataobjectContains metadata for message tracking
sender_app_idintegerID of your application in the Nylas database.
timestampunix timestampTime the thread was changed.
from_selfbooleanIf the message sent is from the owner of the Nylas account.
payloadstringA string you can supply as part of the message tracking payload.
thread_idstringID of the message thread.
reply_to_message_idID of the message the thread is replying to.
message_idstringID 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"
                    }
                }
            }
        ]
    }

Updated 3 months ago


Available Webhooks


Webhook objects and examples available on Nylas.

Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.