Only show these results:

Webhook schemas

This page provides schema references for the webhook notifications that Nylas sends.

Keep in mind

You can send a request to the Mock Payload endpoint to get sample webhook notifications on demand.

Grant webhook notifications

You can subscribe to the following Grant webhook triggers to be notified when changes are made:

Grant Created notifications

Nylas sends a grant.created webhook notification when a grant is authenticated with your Nylas application.

{
"specversion": "1.0",
"type": "grant.created",
"source": "/nylas/system",
"id": "mock-id",
"time": 1234567890,
"data": {
"application_id": "NYLAS_APPLICATION_ID",
"object": {
"code": 25012,
"grant_id": "NYLAS_GRANT_ID",
"integration_id": "NYLAS_INTEGRATION_ID",
"login_id": "mock-login-id",
"provider": "google"
}
}
}

Grant Updated notifications

Nylas sends a grant.updated webhook notification when a grant is modified, updated, or re-authenticated.

{
"specversion": "1.0",
"type": "grant.updated",
"source": "/nylas/system",
"id": "mock-id",
"time": 123456789,
"data": {
"application_id": "NYLAS_APPLICATION_ID",
"object": {
"code": 25014,
"grant_id": "NYLAS_GRANT_ID",
"integration_id": "NYLAS_INTEGRATION_ID",
"provider": "microsoft",
"reauthentication_flag" : false
}
}
}

Grant Deleted notifications

Nylas sends a grant.deleted webhook notification when a grant is deleted as a result of the end user making a Delete Grant request.

{
"specversion": "1.0",
"type": "grant.deleted",
"source": "/nylas/system",
"id": "mock-id",
"time": 1234567890,
"data": {
"application_id": "NYLAS_APPLICATION_ID",
"object": {
"code": 25013,
"grant_id": "NYLAS_GRANT_ID",
"integration_id": "NYLAS_INTEGRATION_ID",
"provider": "google"
}
}
}

Grant Expired notifications

Nylas sends a grant.expired webhook notification when a grant's credentials have expired.

💡 Tip: You can subscribe to the grant.expired webhook trigger to automatically notify administrators or end users to take action when a grant expires.

{
"specversion": "1.0",
"type": "grant.expired",
"source": "/nylas/system",
"id": "mock-id",
"time": 1234567890,
"data": {
"application_id": "NYLAS_APPLICATION_ID",
"object": {
"code": 25009,
"grant_id": "NYLAS_GRANT_ID",
"integration_id": "NYLAS_INTEGRATION_ID",
"login_id": "mock-login-id",
"provider": "google"
}
}
}

Calendar webhook notifications

You can subscribe to the following Calendar webhook triggers to be notified when changes are made:

The following JSON snippet is an example of a Calendar webhook notification.

{
"deltas": [{
"object": "calendar",
"type": "calendar.updated",
"source": "/google/events/realtime",
"id": "FUuYVEHL5gJxB85oKoNxt74890",
"time": 1602623196,
"object_data": {
"namespace_id": "aaz875kwuvxik6ku7pwkqp3ah",
"account_id": "aaz875kwuvxik6ku7pwkqp3ah",
"object": "calendar",
"attributes": null,
"id": "2x6fbv82cctfjqtzex0aqll96",
"metadata": null
}
}]
}

Calendar Created notifications

Nylas sends a calendar.created webhook notification when an end user creates a calendar.

{
"specversion": "1.0",
"type": "calendar.created",
"source": "/google/events/realtime",
"id": "mock-id",
"data": {
"application_id": "NYLAS_APPLICATION_ID",
"object": {
"grant_id": "NYLAS_GRANT_ID",
"description": "Mock Description",
"id": "[email protected]",
"is_primary": false,
"location": "Mock Location",
"name": "Mock Calendar",
"object": "calendar",
"read_only": false,
"timezone": "America/New_York",
"is_owned_by_user": false
}
}
}

Calendar Updated notifications

Nylas sends a calendar.updated webhook notification when an end user updates a calendar.

{
"specversion": "1.0",
"type": "calendar.updated",
"source": "/google/events/realtime",
"id": "mock-id",
"data": {
"application_id": "NYLAS_APPLICATION_ID",
"object": {
"grant_id": "NYLAS_GRANT_ID",
"description": "Mock Description",
"id": "[email protected]",
"is_primary": false,
"location": "Mock Location",
"name": "Mock Calendar",
"object": "calendar",
"read_only": false,
"timezone": "America/New_York",
"is_owned_by_user": false
}
}
}

Calendar Deleted notifications

Nylas sends a calendar.deleted webhook notification when an end user deletes a calendar.

{
"specversion": "1.0",
"type": "calendar.deleted",
"source": "/google/events/incremental",
"id": "mock-id",
"data": {
"application_id": "NYLAS_APPLICATION_ID",
"object": {
"grant_id": "NYLAS_GRANT_ID",
"id": "[email protected]",
"is_primary": false,
"name": "Mock Calendar",
"object": "calendar",
"read_only": false,
"timezone": "America/Los_Angeles",
"is_owned_by_user": false
}
}
}

Event webhook notifications

You can subscribe to the following Event webhook triggers to be notified when changes are made:

The following JSON snippet is an example of an Event webhook notification.

{
"deltas": [{
"object": "event",
"type": "event.created",
"source": "/google/events/incremental",
"id": "hcy2Qzs7yLKhBabtqGEfrX0658",
"time": 1602623196,
"object_data": {
"namespace_id": "d52ehgbft5x3pevzgnmhwumbs",
"account_id": "d52ehgbft5x3pevzgnmhwumbs",
"object": "event",
"attributes": null,
"id": "bvpgob33f3hvebfuvfndv2cvg",
"metadata": null
}
}]
}

Event Created notifications

Nylas sends an event.created webhook notification when an event is created on an end user's calendar.

{
"specversion": "1.0",
"type": "event.created",
"source": "/google/events/incremental",
"id": "mock-id",
"data": {
"application_id": "NYLAS_APPLICATION_ID",
"object": {
"grant_id": "NYLAS_GRANT_ID",
"busy": true,
"calendar_id": "calendar%40nylas.com",
"created_at": 1234567890,
"description": "mock description",
"hide_participants": false,
"ical_uid": "[email protected]",
"id": "mock-data-id",
"object": "event",
"owner": "Mock Owner <[email protected]>",
"organizer": {
"name": "mock organizer name",
"email": "[email protected]"
},
"participants": [
{
"email": "[email protected]",
"name": "mockParticipantsA",
"status": "yes"
},
{
"email": "[email protected]",
"name": "mockParticipantsB",
"status": "noreply"
}
],
"read_only": false,
"reminders": null,
"status": "confirmed",
"title": "mock_title",
"updated_at": 1234567890,
"when": {
"start_time": 1234567890,
"start_timezone": "America/Edmonton",
"end_time": 1234567890,
"end_timezone": "America/Edmonton",
"object": "timespan"
}
}
}
}

Event Updated notifications

In v3, Nylas sends an event.updated webhook notification when an event is modified or updated. When a single occurrence of a recurring Google event is updated, Nylas adds the occurrences parameter to the notification.

{
"specversion": "1.0",
"type": "event.updated",
"source": "/google/events/incremental",
"id": "mock-id",
"data": {
"application_id": "NYLAS_APPLICATION_ID",
"object": {
"busy": true,
"calendar_id": "",
"description": "mock description",
"grant_id": "NYLAS_GRANT_ID",
"hide_participants": false,
"ical_uid": "[email protected]",
"id": "mock-data-id",
"message_id": "mock-message-id",
"occurrences": [
"mock-occurence-id"
],
"object": "event",
"organizer": {
"email": "[email protected]",
"name": "Mock Organizer Name"
},
"owner": "Mock Organizer Name <[email protected]>",
"participants": [
{
"email": "[email protected]",
"name": "mockParticipantsA",
"status": "yes"
},
{
"email": "[email protected]",
"name": "mockParticipantsB",
"status": "noreply"
}
],
"read_only": true,
"recurrence": {
"rrule": [
"RRULE:FREQ=MONTHLY;BYDAY=3TH"
],
"timezone": "America/Toronto"
},
"reminders": null,
"status": "confirmed",
"title": "Engineering All Hands & Demo Day",
"updated_at": 1234567890,
"when": {
"end_time": 1234567991,
"end_timezone": "America/Toronto",
"object": "timespan",
"start_time": 1234567890,
"start_timezone": "America/Toronto"
}
}
}
}

Event Deleted notifications

In v3, Nylas sends an event.deleted webhook notification when an event is deleted from an end user's calendar.

{
"specversion": "1.0",
"type": "event.deleted",
"source": "/google/events/incremental",
"id": "mock-id",
"data": {
"application_id": "NYLAS_APPLICATION_ID",
"object": {
"grant_id": "NYLAS_GRANT_ID",
"calendar_id": "NYLAS_CALENDAR_ID",
"id": "mock-data-id",
"master_event_id": "mock-recurring-event-master-event-id",
"object": "event"
}
}
}

Message webhook notifications

You can subscribe to the following Message webhook triggers to be notified when changes are made:

The following JSON snippet is an example of a Message webhook notification.

{
"deltas": [{
"object": "message",
"type": "message.created",
"source": "/google/emails/incremental",
"id": "sJ9YV94hiMxrC3jUKZY6v83621",
"time": 1602623196,
"object_data": {
"namespace_id": "aaz875kwuvxik6ku7pwkqp3ah",
"account_id": "aaz875kwuvxik6ku7pwkqp3ah",
"object": "message",
"attributes": {
"thread_id": "2u152dt4tnq9j61j8seg26ni6",
"received_date": 1602623166
},
"id": "93mgpjynqqu5fohl2dvv6ray7",
"metadata": null
}
}]
}

Message Created notifications

Nylas sends a message.created webhook notification when an email message is created.

{
"specversion": "1.0",
"type": "message.created",
"source": "/google/emails/realtime",
"id": "mock-id",
"time": 0,
"data": {
"application_id": "NYLAS_APPLICATION_ID",
"object": {
"body": "<p>mock body</p>",
"cc": [
{
"email": "[email protected]",
"name": "mock-cc-name"
},
{
"email": "[email protected]",
"name": "mock-cc-name-2"
}
],
"date": 1234567890,
"folders": [
"INBOX"
],
"from": [
{
"email": "[email protected]",
"name": "mock-from"
}
],
"grant_id": "NYLAS_GRANT_ID",
"id": "mock-id",
"object": "message",
"reply_to_message_id": "<[email protected]>",
"snippet": "mock-snippet",
"starred": false,
"subject": "mock-subject",
"thread_id": "mock-thread-id",
"to": [{
"email": "[email protected]",
"name": "mock-to-name"
}],
"unread": true
}
}
}

Message Updated notifications

In v3, Nylas sends a message.updated webhook notification when an email message is modified or updated.

{
"specversion": "1.0",
"type": "message.updated",
"source": "/google/emails/realtime",
"id": "mock-id",
"time": 0,
"data": {
"application_id": "NYLAS_APPLICATION_ID",
"object": {
"body": "<p>mock body</p>",
"cc": [
{
"email": "[email protected]",
"name": "mock-cc-name"
},
{
"email": "[email protected]",
"name": "mock-cc-name-2"
}
],
"date": 1234567890,
"folders": [
"INBOX"
],
"from": [{
"email": "[email protected]",
"name": "mock-from"
}],
"grant_id": "NYLAS_GRANT_ID",
"id": "mock-id",
"object": "message",
"reply_to_message_id": "<[email protected]>",
"snippet": "mock-snippet",
"starred": false,
"subject": "mock-subject",
"thread_id": "mock-thread-id",
"to": [{
"email": "[email protected]",
"name": "mock-to-name"
}],
"unread": true
}
}
}

Message Send Success notifications

Nylas sends a message.send_success webhook notification when an email message is sent and delivered successfully. You must set the send_at parameter in an email message to use this webhook trigger.

{
"specversion": "1.0",
"type": "message.send_success",
"source": "/nylas/send",
"id": "mock-id",
"time": 1234567890,
"data": {
"application_id": "NYLAS_APPLICATION_ID",
"grant_id": "NYLAS_GRANT_ID",
"object": {
"attachments": [{
"content": "HASKDJhiuahsdjlkhKJAsd=",
"content_type": "text/plain",
"filename": "myfile.txt",
"id": "mock-attachment-id",
"size": 16
}],
"bcc": [{
"email": "[email protected]",
"name": "Mock bcc name "
}],
"body": "mock-body",
"cc": [{
"email": "[email protected]",
"name": "Mock cc name"
}],
"from": [{
"email": "[email protected]"
}],
"id": "mock-id",
"reply_to": [{
"email": "[email protected]",
"name": "Mock reply to name "
}],
"schedule_id": "mock-schedule-id",
"send_at": 1234567880,
"subject": "Mock Subject",
"to": [{
"email": "[email protected]",
"name": "Mock Name"
}],
"use_draft": false
}
}
}

Message Send Failed notifications

Nylas sends a message.send_failed webhook notification when an email message is sent, but not delivered. You must set the send_at parameter in an email message to use this webhook trigger.

{
"specversion": "1.0",
"type": "message.send_failed",
"source": "/nylas/send",
"id": "mock-id",
"time": 1234567890,
"data": {
"application_id": "NYLAS_APPLICATION_ID",
"grant_id": "NYLAS_GRANT_ID",
"object": {
"attachments": [{
"content": "HASKDJhiuahsdjlkhKJAsd=",
"content_type": "text/plain",
"filename": "myfile.txt",
"id": "mock-attachment-id",
"size": 16
}],
"bcc": [{
"email": "[email protected]",
"name": "Mock bcc name "
}],
"body": "mock-body",
"cc": [{
"email": "[email protected]",
"name": "Mock cc name"
}],
"from": [{
"email": "[email protected]"
}],
"id": "mock-id",
"reply_to": [{
"email": "[email protected]",
"name": "Mock reply to name "
}],
"schedule_id": "mock-schedule-id",
"send_at": 1234567880,
"subject": "Mock Subject",
"to": [{
"email": "[email protected]",
"name": "Mock Name"
}],
"use_draft": false
}
}
}

Message Bounce Detected notifications

📝 Note: The Bounce Detected webhook trigger is available for Gmail and Microsoft Graph only.

Nylas sends a message.bounce_detected webhook notification when an email message bounces or is not delivered. You can subscribe to the webhook trigger to automatically notify end users when an email message bounces, and automatically take appropriate action.

{
"specversion": "1.0",
"type": "message.bounce_detected",
"source": "/nylas/send",
"id": "mock-id",
"time": 1234567890,
"data": {
"application_id": "NYLAS_APPLICATION_ID",
"grant_id": "NYLAS_GRANT_ID",
"object": {
"bounce_reason": "mock bounce reason message",
"bounce_date": "Wed, 25 Jan 2023 10:18:39 -0800",
"bounced_address": "[email protected]",
"type": "mailbox_unavailable",
"code": 550,
"origin": {
"to": ["[email protected]"],
"from": "[email protected]",
"cc": ["[email protected]"],
"bcc": ["[email protected]"],
"subject" : "mock-subject",
"mimeId" : "mock-mime-id",
"id": "mock-provider-id"
}
}
}
}

Message tracking webhook notifications

You can subscribe to the following webhook triggers to be notified when a tracking trigger is fulfilled on email messages with tracking enabled:

See the message tracking documentation for more information.

Message Opened notifications

Nylas sends a message.opened webhook notification when a participant first opens a tracked email message.

{
"specversion": "1.0",
"type": "message.opened",
"source": "/com/nylas/tracking",
"id": "b1e59587-0f85-4dd6-9ab9-d174b97bbdc9",
"time": 1695480567,
"data": {
"application_id": "NYLAS_APPLICATION_ID",
"grant_id": "NYLAS_GRANT_ID",
"object": {
"message_data": {
"count": 1,
"timestamp": 1695480410
},
"message_id": "18ac281f237c934b",
"label": "Testing Nylas Messaged Opened Tracking",
"recents": [
{
"ip": "<IP ADDR>",
"opened_id": 0,
"timestamp": 1695480567,
"user_agent": "Mozilla/5.0"
},
{
"ip": "<IP ADDR>",
"opened_id": 1,
"timestamp": 1695480567,
"user_agent": "Mozilla/5.0"
},
{
"ip": "<IP ADDR>",
"opened_id": 2,
"timestamp": 1695480567,
"user_agent": "Mozilla/5.0"
}
],
"sender_app_id": "<app id>",
"timestamp": 1695480410
}
}
}

Nylas sends a message.link_clicked webhook notification when a participant clicks a link in a tracked email message.

{
"specversion": "1.0",
"type": "message.link_clicked",
"source": "/com/nylas/tracking",
"id": "4eabe42e-50e4-42ce-9014-0d602ed8e2ba",
"time": 1695480423,
"data": {
"application_id": "NYLAS_APPLICATION_ID",
"grant_id": "NYLAS_GRANT_ID",
"object": {
"link_data": [{
"count": 1,
"url": "https://www.example.com"
}],
"message_id": "18ac281f237c934b",
"label": "Hey, just testing",
"recents": [
{
"click_id": "0",
"ip": "<IP ADDR>",
"link_index": "0",
"timestamp": 1695480422,
"user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/117.0.0.0 Safari/537.36"
},
{
"click_id": "1",
"ip": "<IP ADDR>",
"link_index": "0",
"timestamp": 1695480422,
"user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/117.0.0.0 Safari/537.36"
},
{
"click_id": "2",
"ip": "<IP ADDR>",
"link_index": "0",
"timestamp": 1695480422,
"user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/117.0.0.0 Safari/537.36"
}
],
"sender_app_id": "<app id>",
"timestamp": 1695480422
}
}
}

Thread Replied notifications

Nylas sends a thread.replied webhook notification when a participant replies to a tracked email thread.

{
"specversion": "1.0",
"type": "thread.replied",
"source": "/com/nylas/tracking",
"id": "d67b0806-b263-4fca-b297-c62478a66e01",
"time": 1696007157,
"data": {
"application_id": "NYLAS_APPLICATION_ID",
"grant_id": "NYLAS_GRANT_ID",
"object": {
"message_id": "<message-id-of-reply>",
"root_message_id": "<message-id-of-original-tracked-message>",
"label": "some-client-label",
"reply_data": {
"count": 1
},
"sender_app_id": "<app-id>",
"thread_id": "<thread-id-of-sent-message>",
"timestamp": 1696007157
}
}
}

Contact webhook notifications

You can subscribe to the following Contact webhook triggers to be notified when changes are made:

  • contact.updated
  • contact.deleted

The following JSON snippet is an example of a Contact webhook notification.

{
"deltas": [{
"date": 1601667544,
"object": "contact",
"type": "contact.updated",
"object_data": {
"namespace_id": "aaz875kwuvxik6ku7pwkqp3ah",
"account_id": "aaz875kwuvxik6ku7pwkqp3ah",
"object": "contact",
"attributes": null,
"id": "1iacfgi0qcm28734iusgzo20o",
"metadata": null
}
}]
}