Notification schemas
This page provides schema references for the notifications that Nylas v3 sends.
Keep in mind
You can send a request to the Webhook Mock Payload endpoint to get sample notification payloads on demand.
Grant notifications
You can subscribe to the following Grant triggers to be notified when changes are made:
Grant Created notifications
Nylas sends a grant.created notification when an end user successfully authenticates with your Nylas application for the first time, creating a user record or "grant".
{
"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 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 notification when a grant is deleted as a result of 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 notification when a grant's credentials expire, usually because of a change in the user's password on the provider.
💡 Tip: You can subscribe to the grant.expired 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 notifications
You can subscribe to the following Calendar triggers to be notified when changes are made:
Calendar Created notifications
Nylas sends a calendar.created 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 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 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 notifications
You can subscribe to the following Event triggers to be notified when changes are made:
Event Created notifications
Nylas sends an event.created 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
Nylas sends an event.updated notification when an event is modified or updated. Nylas adds the occurrences parameter to the notification if the updated event is a single occurrence of a recurring Google event.
{
"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
Nylas sends an event.deleted 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": "CALENDAR_ID",
"id": "mock-data-id",
"master_event_id": "mock-recurring-event-master-event-id",
"object": "event"
}
}
} Message notifications
You can subscribe to the following Message triggers to be notified when changes are made:
message.createdmessage.updatedmessage.send_success(scheduled messages only)message.send_failed(scheduled messages only)- (Gmail and Microsoft Graph only)
message.bounce_detected
Message Created notifications
Nylas sends a message.created 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
Nylas sends a message.updated 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 notification when a scheduled email message is sent and delivered successfully. You must set the send_at parameter in an email message to use this 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 notification when a scheduled email message is sent, but not delivered. You must set the send_at parameter in an email message to use this 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 trigger is available for Gmail and Microsoft Graph only.
Nylas sends a message.bounce_detected notification when an email message bounces or is not delivered. You can subscribe to the trigger so you can notify end users when an email message bounces.
{
"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 notifications
You can subscribe to the following 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 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 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 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
}
}
} Folder notifications
You can subscribe to the following Folder triggers to be notified when changes are made:
Folder Created notifications
Nylas sends a folder.created notification when an end user creates a folder.
{
"specversion": "1.0",
"type": "folder.created",
"source": "/google/emails/incremental",
"id": "mock-id",
"time": 1718210511,
"webhook_delivery_attempt": 1,
"data": {
"application_id": "<NYLAS_APPLICATION_ID>",
"object": {
"grant_id": "<NYLAS_GRANT_ID>",
"id": "<FOLDER_ID>",
"name": "My test folder",
"object": "folder",
"system_folder": false
}
}
} Folder Updated notifications
Nylas sends a folder.updated notification when an end user updates a folder.
{
"specversion": "1.0",
"type": "folder.updated",
"source": "/google/emails/incremental",
"id": "mock_id",
"time": 1718210554,
"webhook_delivery_attempt": 1,
"data": {
"application_id": "<NYLAS_APPLICATION_ID>",
"object": {
"grant_id": "<NYLAS_GRANT_ID>",
"id": "<FOLDER_ID>",
"name": "My updated test folder",
"object": "folder",
"system_folder": false
}
}
} Folder Deleted notifications
Nylas sends a folder.deleted notification when an end user deletes a folder.
{
"specversion": "1.0",
"type": "folder.deleted",
"source": "/google/emails/incremental",
"id": "mock_id",
"time": 1718210588,
"webhook_delivery_attempt": 1,
"data": {
"application_id": "<NYLAS_APPLICATION_ID>",
"object": {
"grant_id": "<NYLAS_GRANT_ID>",
"id": "<FOLDER_ID>",
"name": "My test folder",
"object": "folder",
"system_folder": false
}
}
} Contact notifications
You can subscribe to the following Contact triggers to be notified when changes are made:
contact.updatedcontact.deleted
Contact Updated notifications
Nylas sends a contact.udpated notification when an contact is created or updated.
Most providers do not differentiate between these two actions in their APIs, so Nylas sends a contact.updated notification for both actions.
{
"specversion": "1.0",
"type": "contact.updated",
"source": "/google/contact/realtime",
"id": "mock-id",
"webhook_delivery_attempt" : 1,
"data": {
"application_id": "mock-application-id",
"object": {
"birthday":"1988-12-31",
"company_name":"Nyla Global Express Inc.",
"emails":[
{
"email":"[email protected]",
"type":"work"
},
{
"email":"[email protected]",
"type":"home"
}
],
"given_name":"John",
"grant_id":"mock-grant-id",
"groups":[
{
"id":"friends"
}
],
"id":"mock-id",
"im_addresses":[
{
"type":"jabber",
"im_address":"myjabberaddress"
},
{
"type":"msn",
"im_address":"mymsnaddress"
}
],
"job_title":"Software Engineer",
"manager_name":"Melissa A. Manager",
"middle_name":"Jacob",
"nickname":"JJ",
"notes":"This is where you'd write something about John.",
"office_location":"123 Main Street",
"object":"contact",
"phone_numbers":[
{
"number":"1 123 456 7890",
"type":"work"
}
],
"physical_addresses":[
{
"city":"San Francisco",
"country":"USA",
"postal_code":"10000",
"state":"CA",
"street_address":"123 Main Street",
"type":"work"
}
],
"suffix":"Jr",
"surname":"Jingleheimer-Schmidt",
"source":"address_book",
"web_pages":[
{
"url":"www.myWorkPage.example.com",
"type":"work"
}
]
}
}
} Contact Deleted notifications
Nylas sends a contact.deleted notification when an contact is deleted.
{
"specversion": "1.0",
"type": "contact.updated",
"source": "/google/contact/realtime",
"id": "mock-id",
"webhook_delivery_attempt" : 1,
"data": {
"application_id": "mock-application-id",
"object": {
"birthday":"1960-12-31",
"company_name":"Nyla Global Express Inc.",
"emails":[
{
"email":"[email protected]",
"type":"work"
},
{
"email":"[email protected]",
"type":"home"
}
],
"given_name":"John",
"grant_id":"mock-grant-id",
"groups":[
{
"id":"friends"
}
],
"id":"mock-id",
"im_addresses":[
{
"type":"jabber",
"im_address":"myjabberaddress"
},
{
"type":"msn",
"im_address":"mymsnaddress"
}
],
"job_title":"Software Engineer",
"manager_name":"Melissa A. Manager",
"middle_name":"Jacob",
"nickname":"JJ",
"notes":"This is where you'd write something about John.",
"office_location":"123 Main Street",
"object":"contact",
"phone_numbers":[
{
"number":"1 123 456 7890",
"type":"work"
}
],
"physical_addresses":[
{
"city":"San Francisco",
"country":"USA",
"postal_code":"10000",
"state":"CA",
"street_address":"123 Main Street",
"type":"work"
}
],
"suffix":"Jr",
"surname":"Jingleheimer-Schmidt",
"source":"address_book",
"web_pages":[
{
"url":"www.myWorkPage.example.com",
"type":"work"
}
]
}
}
}