Only show these results:

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

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