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:
message.created
message.updated
message.send_success
message.send_failed
- (Gmail and Microsoft Graph only)
message.bounce_detected
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
}
}
}
Link Clicked notifications
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
}
}]
}