Notification schemas
This page provides schema references for the notifications that Nylas v3 sends.
Keep in mind
- Nylas guarantees "at least once" delivery of webhooks. You might receive duplicate webhook notifications because of the provider's behavior (for example, when Google and Microsoft Graph send upserts).
- You can send a request to the Webhook Mock Payload endpoint to get sample notification payloads on demand.
Grant notifications
Grant Created notifications
Nylas sends a grant.created notification when a user successfully authenticates with your Nylas application for the first time.
{
"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 because 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 users to act 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
Calendar Created notifications
Nylas sends a calendar.created notification when a 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": "calendar@group.calendar.google.com",
"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 the name, description, location or timezone of a calendar changes.
{
"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": "calendar@group.calendar.google.com",
"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 a 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": "calendar@group.calendar.google.com",
"is_primary": false,
"name": "Mock Calendar",
"object": "calendar",
"read_only": false,
"timezone": "America/Los_Angeles",
"is_owned_by_user": false
}
}
} Event notifications
Event Created notifications
Nylas sends an event.created notification when an event is created on a user's calendar.
{
"specversion": "1.0",
"type": "event.created",
"source": "/google/events/realtime",
"id": "mock_id",
"time": 1695415185,
"webhook_delivery_attempt": 1,
"data": {
"application_id": "<NYLAS_APPLICATION_ID>",
"object": {
"account_id": "<NYLAS_V2_ACCOUNT_ID>",
"busy": true,
"calendar_id": "<CALENDAR_ID>",
"conferencing": {
"details": {
"meeting_code": "<MEETING_CODE>",
"phone": ["<MEETING_PHONE_NUMBER>"],
"pin": "<MEETING_PIN>",
"url": "<MEETING_URL>"
},
"provider": "<PROVIDER>"
},
"created_at": 1545355476,
"creator": {
"email": "leyah@example.com",
"name": "Leyah Miller"
},
"description": "<p>Example meeting description</p>",
"grant_id": "<NYLAS_GRANT_ID>",
"hide_participants": true,
"html_link": "<EVENT_LINK>",
"ical_uid": "<ICAL_UID>",
"id": "<EVENT_ID>",
"object": "event",
"occurrences": ["<OCCURRENCE_ID>"],
"organizer": {
"email": "leyah@example.com",
"name": "Leyah Miller"
},
"participants":
[{
"email": "nyla@example.com",
"status": "yes"
}],
"read_only": true,
"recurrence": ["RRULE:FREQ=WEEKLY;WKST=SU;UNTIL=20230420T065959Z;INTERVAL=2"],
"reminders": {
"overrides": [],
"use_default": true
},
"resources": [],
"sequence": 17,
"status": "confirmed",
"title": "Test Meeting",
"updated_at": 1724359724,
"visibility": "default",
"when": {
"end_time": 1680800100,
"end_timezone": "America/Los_Angeles",
"object": "timespan",
"start_time": 1680796800,
"start_timezone": "America/Los_Angeles"
}
}
}
} 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.
If the event is a single occurrence of a recurring event, Nylas includes the master_event_id field, as in the example below.
{
"specversion": "1.0",
"type": "event.updated",
"source": "/microsoft/events/realtime",
"id": "id",
"time": 1732575192,
"webhook_delivery_attempt": 1,
"data": {
"application_id": "<NYLAS_APPLICATION_ID>",
"object": {
"account_id": "id",
"busy": true,
"calendar_id": "<CALENDAR_ID>",
"cancelled_occurrences": [
"<CANCELLED_OCCURRENCE_ID>"
],
"conferencing": {
"details": {
"url": "<URL>"
},
"provider": "Microsoft Teams"
},
"created_at": 1732573232,
"description": "description",
"grant_id": "<NYLAS_GRANT_ID>",
"hide_participants": false,
"html_link": "<LINK_TO_EVENT>",
"ical_uid": "<UID>",
"id": "<ID>",
"location": "Microsoft Teams Meeting",
"object": "event",
"occurrences": [
"<OCCURRENCE_ID>",
],
"organizer": {
"email": "nyla@example.com",
"name": "Nyla"
},
"participants": [
{
"email": "jane.doe@example.com",
"name": "Jane Doe",
"status": "noreply"
}
],
"read_only": false,
"recurrence": [
"RRULE:FREQ=WEEKLY;UNTIL=20241219T000000Z;BYDAY=TH"
],
"reminders": {
"overrides": [],
"use_default": true
},
"resources": [],
"status": "confirmed",
"title": "test-rec",
"updated_at": 1732575179,
"visibility": "public",
"when": {
"end_time": 1732811400,
"end_timezone": "EST5EDT",
"object": "timespan",
"start_time": 1732809600,
"start_timezone": "EST5EDT"
}
}
}
} Event Deleted notifications
Nylas sends an event.deleted notification when an event is deleted from a 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"
}
}
} Scheduler notifications
Booking Created notifications
Nylas sends a booking.created notification when a guest creates a booking.
{
"specversion": "1.0",
"type": "booking.created",
"source": "/nylas/passthru",
"id": "mock-id",
"time": 1725895310,
"data": {
"application_id":"NYLAS_APPLICATION_ID",
"grant_id":"NYLAS_GRANT_ID",
"object":{
"booking_id":"NYLAS_BOOKING_ID",
"booking_info":{
"event_id":"NYLAS_EVENT_ID",
"start_time":1719842400,
"end_time":1719846000,
"participants":[
{
"email":"mock_participant_1@example.com",
"name":"Mock Participant 1"
},
{
"email":"mock_participant_2@example.com",
"name":"Mock Participant 2"
}
],
"additional_fields":{},
"hide_cancellation_options":false,
"hide_rescheduling_options":false,
"title":"My test event",
"duration":60,
"location":"Mock Location",
"organizer_timezone":"America/Toronto",
"guest_timezone":"America/New_York"
},
"configuration_id":"NYLAS_CONFIGURATION_ID",
"booking_ref":"uq935BNHTnK35Y4TFXisQIOucgjjQE6rkCH177-IvsI=",
"object": "booking"
}
}
} Booking Pending notifications
Nylas sends a booking.pending notification when a guest schedules a pending booking that requires confirmation.
{
"specversion": "1.0",
"type": "booking.pending",
"source": "/nylas/passthru",
"id": "mock-id",
"data": {
"application_id":"NYLAS_APPLICATION_ID",
"grant_id":"NYLAS_GRANT_ID",
"object":{
"configuration_id":"NYLAS_CONFIGURATION_ID",
"booking_id":"NYLAS_BOOKING_ID",
"booking_ref":"uq935BNHTnK35Y4TFXisQIOucgjjQE6rkCH177-IvsI=",
"booking_type":"organizer-confirmation",
"booking_info":{
"event_id":"NYLAS_EVENT_ID",
"start_time":1719842400,
"end_time":1719846000,
"participants":[
{
"email":"mock_participant_1@example.com",
"name":"Mock Participant 1"
},
{
"email":"mock_participant_2@example.com",
"name":"Mock Participant 2"
}
],
"additional_fields":null,
"hide_cancellation_options":false,
"hide_rescheduling_options":false,
"title":"[PENDING] My test event",
"duration":60,
"location":"Mock Location",
"organizer_timezone":"America/Toronto",
"guest_timezone":"America/New_York"
}
}
}
} Booking Rescheduled notifications
Nylas sends a booking.rescheduled notification when a guest reschedules a booking.
{
"specversion": "1.0",
"type": "booking.rescheduled",
"source": "/nylas/passthru",
"id": "mock-id",
"time": 1725895310,
"data": {
"application_id":"NYLAS_APPLICATION_ID",
"grant_id":"NYLAS_GRANT_ID",
"object":{
"booking_id":"NYLAS_BOOKING_ID",
"booking_info":{
"event_id":"NYLAS_EVENT_ID",
"start_time":1719842400,
"end_time":1719846000,
"participants":[
{
"email":"mock_participant_1@example.com",
"name":"Mock Participant 1"
},
{
"email":"mock_participant_2@example.com",
"name":"Mock Participant 2"
}
],
"additional_fields":{},
"hide_cancellation_options":false,
"hide_rescheduling_options":false,
"title":"My test event",
"duration":60,
"location":"Mock Location",
"organizer_timezone":"America/Toronto",
"guest_timezone":"America/New_York",
"old_end_time": 1725906600,
"old_start_time": 1725904800
},
"configuration_id":"NYLAS_CONFIGURATION_ID",
"booking_ref":"uq935BNHTnK35Y4TFXisQIOucgjjQE6rkCH177-IvsI=",
"object": "booking"
}
}
}
Booking Deleted notifications
Nylas sends a booking.cancelled notification when a guest cancels a booking.
{
"specversion": "1.0",
"type": "booking.cancelled",
"source": "/nylas/passthru",
"id": "mock-id",
"time": 1725895310,
"data": {
"application_id":"NYLAS_APPLICATION_ID",
"grant_id":"NYLAS_GRANT_ID",
"object":{
"booking_id":"NYLAS_BOOKING_ID",
"booking_info":{
"event_id":"NYLAS_EVENT_ID",
"start_time":1719842400,
"end_time":1719846000,
"cancellation_reason": "CANCELLATION_REASON",
"participants":[
{
"email":"mock_participant_1@example.com",
"name":"Mock Participant 1"
},
{
"email":"mock_participant_2@example.com",
"name":"Mock Participant 2"
}
],
"additional_fields":{},
"hide_cancellation_options":false,
"hide_rescheduling_options":false,
"title":"My test event",
"duration":60,
"location":"Mock Location",
"organizer_timezone":"America/Toronto",
"guest_timezone":"America/New_York"
},
"configuration_id":"NYLAS_CONFIGURATION_ID",
"booking_ref":"uq935BNHTnK35Y4TFXisQIOucgjjQE6rkCH177-IvsI=",
"object": "booking"
}
}
}
Booking reminder notifications
Nylas sends a booking.reminder notification at the scheduled reminder time.
{
"specversion": "1.0",
"id": "975b4de9-41df-45b8-8827-82395ea41176",
"time": 1724850847,
"type": "booking.reminder",
"source": "/nylas/passthru",
"data": {
"application_id": "default-application",
"object": {
"configuration_id": "config-id",
"booking_id": "booking-id",
"booking_info": {
"event_id": "event-id",
"start_time": 1725026400,
"end_time": 1725030000,
"participants": [
{
"email": "host@example.com",
"name": "Host"
},
{
"email": "guest@example2.com",
"name": "Guest"
}
],
"additional_fields": null,
"hide_cancellation_options": false,
"hide_rescheduling_options": false,
"title": "Nylas Event",
"duration": 60,
"location": "Office",
"organizer_timezone": "America/Toronto",
"guest_timezone": "",
"organizer_email": "host@example.com",
"provider": "google"
}
}
}
} Message notifications
message.createdmessage.updatedmessage.send_success(Scheduled messages only.)message.send_failed(Scheduled messages only.)message.bounce_detected(Available for Google, Microsoft Graph, iCloud, and Yahoo.)
Message Created notifications
Nylas sends a message.created notification when a user creates a message.
{
"specversion": "1.0",
"type": "message.created",
"source": "/google/emails/realtime",
"id": "1",
"time": 1723821985,
"webhook_delivery_attempt": 1,
"data": {
"application_id": "<NYLAS_APPLICATION_ID>",
"object": {
"attachments": [{
"content_disposition": "attachment; filename=\"image.jpg\"",
"content_id": "<CID>",
"content_type": "image/jpeg; name=\"image.jpg\"",
"filename": "image.jpg",
"grant_id": "<NYLAS_GRANT_ID>",
"id": "<ATTACHMENT_ID>",
"is_inline": false,
"size": 4860136
}],
"bcc": [{
"email": "leyah@example.com"
}],
"body": "<div dir=\"ltr\">Test with attachments</div>\r\n",
"cc": [{
"email": "kaveh@example.com"
}],
"date": 1723821981,
"folders": [
"SENT"
],
"from": [{
"email": "swag@example.com",
"name": "Nylas Swag"
}],
"grant_id": "<NYLAS_GRANT_ID>",
"id": "<MESSAGE_ID>",
"object": "message",
"reply_to": [],
"snippet": "This message has an attachment.",
"starred": false,
"subject": "Let's send an attachment",
"thread_id": "1915bcb2d83c20bd",
"to": [{
"email": "nyla@example.com"
}],
"unread": false
}
}
} Message Updated notifications
Nylas sends a message.updated notification when a user modifies or updates a message.
{
"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": "cc@example.com",
"name": "mock-cc-name"
},
{
"email": "cc@example.com",
"name": "mock-cc-name-2"
}
],
"date": 1234567890,
"folders": [
"INBOX"
],
"from": [{
"email": "from@example.com",
"name": "mock-from"
}],
"grant_id": "NYLAS_GRANT_ID",
"id": "mock-id",
"object": "message",
"reply_to_message_id": "<reply_to_message_id@example.com>",
"snippet": "mock-snippet",
"starred": false,
"subject": "mock-subject",
"thread_id": "mock-thread-id",
"to": [{
"email": "to@example.com",
"name": "mock-to-name"
}],
"unread": true
}
}
} Message Send Success notifications
Nylas sends a message.send_success notification when a scheduled message is sent and delivered successfully. You need to set the send_at parameter in a 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": "mock-bcc@example.com",
"name": "Mock bcc name "
}],
"body": "mock-body",
"cc": [{
"email": "mock-cc@example.com",
"name": "Mock cc name"
}],
"from": [{
"email": "mock-from@example.com"
}],
"id": "mock-id",
"reply_to": [{
"email": "mock-reply-to@example.com",
"name": "Mock reply to name "
}],
"schedule_id": "mock-schedule-id",
"send_at": 1234567880,
"subject": "Mock Subject",
"to": [{
"email": "mock-to@example.com",
"name": "Mock Name"
}],
"use_draft": false
}
}
} Message Send Failed notifications
Nylas sends a message.send_failed notification when a scheduled message is sent, but not delivered. You need to set the send_at parameter in a 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": "mock-bcc@example.com",
"name": "Mock bcc name "
}],
"body": "mock-body",
"cc": [{
"email": "mock-cc@example.com",
"name": "Mock cc name"
}],
"from": [{
"email": "mock-from@example.com"
}],
"id": "mock-id",
"reply_to": [{
"email": "mock-reply-to@example.com",
"name": "Mock reply to name "
}],
"schedule_id": "mock-schedule-id",
"send_at": 1234567880,
"subject": "Mock Subject",
"to": [{
"email": "mock-to@example.com",
"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 a message bounces or isn't delivered. You can subscribe to the trigger so you can notify users when a message bounces.
This trigger is currently available for Google, Microsoft Graph, iCloud, and Yahoo.
{
"specversion": "1.0",
"type": "message.bounce_detected",
"source": "/nylas/send",
"id": "mock-id",
"time": 1234567890,
"webhook_delivery_attempt" : 1,
"data": {
"application_id": "example NYLAS_APPLICATION_ID",
"grant_id": "example NYLAS_GRANT_ID",
"object": {
"bounce_reason": "An example message describing the reason for the bounce.",
"bounce_date": "Wed, 25 Jan 2023 10:18:39 -0800",
"bounced_addresses": "this.address.bounced@example.com",
"type": "mailbox_unavailable",
"code": 550,
"grant_id": "mock-grant-id",
"origin": {
"to": [
"jdoe@example.com"
],
"from": ["mock-from@example.com"],
"cc": ["mock-cc@example.com"],
"bcc": ["mock-bcc@example.com"],
"subject": "example-subject",
"mime_id": "SJ0PR16MB40611C92DE872E6FC5916859D4603@SJ0PR16MB4062.namprd16.prod.outlook.com",
"id": "AAkALgAAAAAAHYQDEapmEc2byACqAC-EWg0AVKoCBvx5pk2OWnx9GWNeIAABogwSJQAB",
"original_send_at": "Mon, 16 Sep 2024 16:15:49 +0000"
}
}
}
} Message tracking notifications
You can subscribe to the following triggers to get notifications when tracking trigger criteria are met on messages with tracking enabled:
Tracking migration
For migration purposes, you can subscribe to the following .legacy triggers to receive tracking data initiated by the v2 Email API:
The deltas array in the .legacy notifications contains v2 schema tracking data.
To use the .legacy triggers, you must:
- Migrate the user's v2 account to a v3 grant.
- Set up the v3 webhook endpoints with the corresponding tracking webhook triggers.
- Make sure that the v2 account remains active. The v2 webhook endpoints must also be active with the corresponding tracking webhook triggers.
- Contact Nylas Support to enable the feature.
You should use v3 message tracking after you finish migrating your application.
Message Opened notifications
Nylas sends a message.opened notification when a participant first opens a tracked 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 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
}
}
} Message Opened legacy notifications
{
"specversion": "1.0",
"type": "message.opened.legacy",
"source": "/com/nylas/v2/webhooks",
"id": "webhook_id",
"time": 1733261181,
"webhook_delivery_attempt": 1,
"data": {
"application_id": "<V3_NYLAS_APPLICATION_ID>",
"grant_id": "<V3_NYLAS_GRANT_ID>",
"object": {
"deltas": [
{
"date": 1733261154,
"object": "metadata",
"object_data": {
"account_id": "<V2_NYLAS_ACCOUNT_ID>",
"id": "<V2_WEBHOOK_ID>",
"metadata": {
"count": 1,
"message_id": "<V2_MESSAGE_ID>",
"payload": "Hello world",
"recents": [
{
"id": 0,
"ip": "ip_address",
"timestamp": 1733163186,
"user_agent": "Mozilla/5.0 (Windows NT 5.1; rv:11.0) Gecko Firefox/11.0 (via ggpht.com GoogleImageProxy)"
},
],
"timestamp": 1733261154
},
"namespace_id": "<V2_NAMESPACE_ID>",
"object": "metadata"
},
"type": "message.opened"
}
],
"grant_id": "<V3_NYLAS_GRANT_ID>",
"object": "message"
}
}
} Link Clicked Legacy notifications
{
"specversion": "1.0",
"type": "message.link_clicked.legacy",
"source": "/com/nylas/v2/webhooks",
"id": "webhook_id",
"time": 1733261173,
"webhook_delivery_attempt": 1,
"data": {
"application_id": "<V3_NYLAS_APPLICATION_ID>",
"grant_id": "<V3_NYLAS_GRANT_ID>",
"object": {
"deltas": [
{
"date": 1733261158,
"object": "metadata",
"object_data": {
"account_id": "<V2_NYLAS_ACCOUNT_ID>",
"id": "<V2_WEBHOOK_ID>",
"metadata": {
"link_data": [
{
"count": 8,
"url": "client_url"
}
],
"message_id": "<V2_MESSAGE_ID>",
"payload": "Hello world",
"recents": [
{
"id": 0,
"ip": "ip_address",
"link_index": 0,
"timestamp": 1733163188,
"user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/131.0.0.0 Safari/537.36"
}
],
"timestamp": 1733163166
},
"namespace_id": "<V2_NAMESPACE_ID>",
"object": "metadata"
},
"type": "message.link_clicked"
}
],
"grant_id": "<V3_NYLAS_GRANT_ID>",
"object": "message"
}
}
} Thread Replied Legacy notifications
{
"specversion": "1.0",
"type": "thread.replied.legacy",
"source": "/com/nylas/v2/webhooks",
"id": "v3_webhook_id",
"time": 1733180746,
"webhook_delivery_attempt": 1,
"data": {
"application_id": "<V3_NYLAS_APPLICATION_ID>",
"grant_id": "<V3_NYLAS_GRANT_ID>",
"object": {
"deltas": [
{
"date": 1733180719,
"object": "message",
"object_data": {
"account_id": "<V2_NYLAS_ACCOUNT_ID>",
"id": "<V2_WEBHOOK_ID>",
"metadata": {
"from_self": true,
"message_id": "<V2_MESSAGE_ID>",
"payload": "Hello world",
"reply_to_message_id": "<V2_REPLY_TO_MESSAGE_ID>",
"thread_id": "<V2_THREAD_ID>",
"timestamp": 1733180490
},
"namespace_id": "<V2_NAMESPACE_ID>",
"object": "message"
},
"type": "thread.replied"
}
],
"grant_id": "<V3_NYLAS_GRANT_ID>",
"object": "thread"
}
}
} ExtractAI notifications
Order notifications
Nylas sends a message.intelligence.order notification when a user receives an message that has information about an e-commerce order.
{
"specversion": "1.0",
"type": "message.intelligence.order",
"source": "/google/emails/historic",
"id": "TV6RF5Vq0h41th3r31337h4x0r",
"time": 1716913463,
"webhook_delivery_attempt": 1,
"data": {
"application_id": "<NYLAS_APPLICATION_ID>",
"object": {
"confidence_score": 1,
"email_category": "order_in_transit",
"email_timestamp": 1632877388,
"error": null,
"fetched_email_id": "18f9d4c513cbd00d",
"grant_id": "<NYLAS_GRANT_ID>",
"merchant": {
"domain": "example.com",
"name": "Nyla's Natural Bath Products"
},
"metadata": {
"language": "en",
"market": "US",
"sender_domain": "store.example.com"
},
"object": "message",
"order_status": "order_in_transit",
"orders": [{
"coupon": null,
"currency": "USD",
"discount": null,
"gift_card": null,
"line_items": [{
"color": null,
"name": "So Sensitive Soap - Unscented Soap Bar For Sensitive Skin - 4 oz.",
"product_id": null,
"product_image_uri": "https://imgcdn.example.com/img/1925bf51-82a3-49be-bfdb-01e0633195f8.jpeg",
"quantity": 1,
"size": null,
"unit_price": 197,
"url": null
}],
"order_date": "1632726000",
"order_number": "<MERCHANT_ORDER_NUMBER>",
"shipping_total": null,
"total_amount": 812,
"total_tax_amount": 16
}],
"status": "SUCCESS"
}
}
} Order Tracking notifications
Nylas sends a message.intelligence.tracking notification when a user receives a message that has tracking information for an e-commerce order.
{
"specversion": "1.0",
"type": "message.intelligence.tracking",
"source": "/google/emails/historic",
"id": "AWtuXhdwHdUAyx4nwpbe9h8937",
"time": 1716558937,
"webhook_delivery_attempt": 1,
"data": {
"application_id": "<NYLAS_APPLICATION_ID>",
"object": {
"confidence_score": 1,
"email_category": "order_in_transit",
"email_timestamp": 1714136753,
"error": null,
"fetched_email_id": "18f1a83273ee32e9",
"grant_id": "<NYLAS_GRANT_ID>",
"merchant": {
"domain": "example.com",
"name": null
},
"metadata": {
"language": "en",
"market": "US",
"sender_domain": "example.com"
},
"object": "message",
"order_status": "order_in_transit",
"shippings": [{
"carrier": "Nyla Global Express Inc.",
"decoded_link": null,
"order_number": "<CARRIER_ORDER_NUMBER>",
"tracking_link": "<CARRIER_TRACKING_LINK>",
"tracking_number": "<CARRIER_TRACKING_NUMBERx>"
}],
"status": "SUCCESS"
}
}
} Order Return notifications
Nylas sends a message.intelligence.return notification when a user receives a message that has return information for an e-commerce order.
{
"specversion": "1.0",
"type": "message.intelligence.return",
"source": "/google/emails/incremental",
"id": "SuwjxNj4ZFCBvj3j7wYcBn0841",
"time": 1734370841,
"webhook_delivery_attempt": 1,
"data": {
"application_id": "<NYLAS_APPLICATION_ID>",
"object": {
"confidence_score": 1,
"email_category": "other",
"email_timestamp": 1734370631,
"fetched_email_id": "<MESSAGE_ID>",
"grant_id": "<NYLAS_GRANT_ID>",
"merchant": {
"domain": "example.com",
"name": "Nyla's Natural Bath Products"
},
"metadata": {
"language": "en",
"market": "US",
"sender_domain": "example.com"
},
"object":"message",
"order_status":"other",
"returns": [{
"order_number": null,
"refund_total": null,
"returns_date": 1734370631
}],
"status": "SUCCESS"
}
}
} Folder notifications
Folder Created notifications
Nylas sends a folder.created notification when a 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 a 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 a 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
Contact Updated notifications
Nylas sends a contact.updated notification when a user creates or updates a contact.
🔍 Most providers don't differentiate between creating and updating contacts in their APIs. 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":"john.schmidt@example.com",
"type":"work"
},
{
"email":"johnisacoolguy@example.com",
"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":"94107",
"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 a user deletes a contact.
{
"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":"john.schmidt@example.com",
"type":"work"
},
{
"email":"johnisacoolguy@example.com",
"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":"94107",
"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"
}
]
}
}
}