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": "<WEBHOOK_ID>", "data": { "application_id": "<NYLAS_APPLICATION_ID>", "object": { "grant_id": "<NYLAS_GRANT_ID>", "description": "Personal calendar", "id": "<CALENDAR_ID>", "metadata": { "key1": "all-meetings", "key2": "on-site" }, "is_primary": false, "location": "New York", "name": "Personal", "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": "<WEBHOOK_ID>", "data": { "application_id": "<NYLAS_APPLICATION_ID>", "object": { "grant_id": "<NYLAS_GRANT_ID>", "description": "Personal calendar", "id": "<CALENDAR_ID>", "metadata": { "key1": "all-meetings", "key2": "on-site" }, "is_primary": false, "location": "New York", "name": "Personal", "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", "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": "<WEBHOOK_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": { "name": "Leyah Miller" }, "description": "<p>Weekly one-on-one.</p>", "grant_id": "<NYLAS_GRANT_ID>", "hide_participants": true, "html_link": "<EVENT_LINK>", "ical_uid": "<ICAL_UID>", "id": "<EVENT_ID>", "location": "Room 103", "metadata": { "key1": "all-meetings", "key2": "on-site" }, "object": "event", "occurrences": ["<EVENT_ID>"], "organizer": { "name": "Leyah Miller" }, "participants": [{ "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": "One-on-one", "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": "/google/events/realtime", "id": "<WEBHOOK_ID>", "time": 1732575192, "webhook_delivery_attempt": 1, "data": { "application_id": "<NYLAS_APPLICATION_ID>", "object": { "account_id": "<NYLAS_V2_ACCOUNT_ID>", "busy": true, "calendar_id": "<CALENDAR_ID>", "cancelled_occurrences": ["<EVENT_ID>"], "conferencing": { "details": { "url": "<MEETING_URL>" }, "provider": "<PROVIDER>" }, "created_at": 1732573232, "description": "Weekly one-on-one.", "grant_id": "<NYLAS_GRANT_ID>", "hide_participants": false, "html_link": "<EVENT_LINK>", "ical_uid": "<ICAL_UID>", "id": "<EVENT_ID>", "location": "Room 103", "object": "event", "metadata": { "key1": "all-meetings", "key2": "on-site" }, "occurrences": ["<EVENT_ID>"], "organizer": { "name": "Nyla" }, "participants": [{ "name": "Leyah Miller", "status": "noreply" }], "read_only": false, "recurrence": ["RRULE:FREQ=WEEKLY;UNTIL=20241219T000000Z;BYDAY=TH"], "reminders": { "overrides": [], "use_default": true }, "resources": [], "status": "confirmed", "title": "One-on-one", "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":[ { "name":"Mock Participant 1" }, { "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":[ { "name":"Mock Participant 1" }, { "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":[ { "name":"Mock Participant 1" }, { "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":[ { "name":"Mock Participant 1" }, { "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": [ { "name": "Host" }, { "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": "", "provider": "google" } } }}Notetaker notifications
You can subscribe to the following Notetaker triggers to be notified when changes are made:
Notetaker Created notifications
Nylas sends a notetaker.created notification when you create or schedule a Notetaker bot. If you create the bot to attend an ad-hoc meeting, Nylas omits the join_time, event.ical_uid, and event.event_id fields from the notification.
{ "specversion": "1.0", "type": "notetaker.created", "source": "/nylas/notetaker", "id": "<WEBHOOK_ID>", "time": 1737500935555, "webhook_delivery_attempt": 0, "data": { "application_id": "<NYLAS_APPLICATION_ID>", "object": { "id": "<NOTETAKER_ID>", "grant_id": "<NYLAS_GRANT_ID>", "meeting_settings": { "video_recording": true, "audio_recording": true, "transcription": true }, "join_time": 1737500936450, "calendar_id": "<CALENDAR_ID>", "event": { "ical_uid": "<ICAL_UID>", "event_id": "<EVENT_ID>", "master_event_id": "<EVENT_ID>" }, "object": "notetaker", "state": "scheduled" } }}Notetaker Updated notifications
Nylas sends a notetaker.updated notification when Notetaker goes through a status change (for example, it joins or leaves a meeting). The status parameter can have any of the following values:
attendingconnectingdisconnectedfailed_entryscheduledwaiting_for_entry
If the bot is attending an ad-hoc meeting, Nylas omits the join_time, event.ical_uid, and event.event_id fields from the notification.
{ "specversion": "1.0", "type": "notetaker.updated", "source": "/nylas/notetaker", "id": "<WEBHOOK_ID>", "time": 1737500935555, "webhook_delivery_attempt": 0, "data": { "application_id": "<NYLAS_APPLICATION_ID>", "object": { "id": "<NOTETAKER_ID>", "grant_id": "<NYLAS_GRANT_ID>", "meeting_settings": { "video_recording": true, "audio_recording": true, "transcription": true }, "join_time": 1737500936450, "calendar_id": "<CALENDAR_ID>", "event": { "ical_uid": "<ICAL_UID>", "event_id": "<EVENT_ID>", "master_event_id": "<MASTER_EVENT_ID>" }, "object": "notetaker", "state": "scheduled" } }}Notetaker Meeting State notifications
Nylas sends a notetaker.meeting_state notification when the status of a Notetaker bot updates while it’s attending a meeting. Nylas starts listening for these events when the Notetaker’s status changes to connecting.
The meeting_state parameter can have any of the following values:
api_request: The Notetaker bot left a meeting because it received a Remove from Meeting request.bad_meeting_code: The meeting isn’t active and can’t be joined.dispatched: The Notetaker bot has loaded the meeting page.entry_denied: The Notetaker bot’s admission request was rejected.internal_error: Notetaker encountered an error.kicked: The Notetaker bot was removed from the meeting by a participant.no_meeting_activity: The Notetaker bot left the meeting because there was no activity from the participants (for example, all participants are silent for a period of time).no_participants: The Notetaker bot left the meeting because it was the last participant in the meeting.no_response: The Notetaker bot’s admission request timed out.recording_active: The Notetaker bot is attending and recording a meeting.waiting_for_entry: The Notetaker bot is waiting to be admitted to the meeting.
{ "specversion": "1.0", "type": "notetaker.meeting_state", "source": "/nylas/notetaker", "id": "<WEBHOOK_ID>", "time": 1737500935555, "webhook_delivery_attempt": 0, "data": { "application_id": "<NYLAS_APPLICATION_ID>", "object": { "id": "<NOTETAKER_ID>", "grant_id": "<NYLAS_GRANT_ID>", "calendar_id": "<CALENDAR_ID>", "event": { "ical_uid": "<ICAL_UID>", "event_id": "<EVENT_ID>", "master_event_id": "<MASTER_EVENT_ID>" }, "object": "notetaker", "state": "connecting", "meeting_state": "dispatched" } }}Notetaker Media notifications
Nylas sends a notetaker.media notification when a recording or transcription is processing, available, or deleted. Nylas starts listening for these events when the Notetaker’s status changes to disconnected.
The status parameter can have any of the following values:
available: A recording or transcription is available to download.deleted: A recording or transcription has been deleted because of an API request or the media retention policy.error: Nylas encountered an error while processing a recording.processing: Nylas is processing and transcribing a recording.
{ "specversion": "1.0", "type": "notetaker.media", "source": "/nylas/notetaker", "id": "<WEBHOOK_ID>", "time": 1737500935555, "webhook_delivery_attempt": 0, "data": { "application_id": "<NYLAS_APPLICATION_ID>", "object": { "id": "<NOTETAKER_ID>", "object": "notetaker", "state": "available", "media": { "recording": "<RECORDING_URL>", "transcript": "<TRANSCRIPT_URL>" } } }}Notetaker Deleted notifications
Nylas sends a notetaker.deleted notification when a Notetaker bot is deleted, an event that included a scheduled Notetaker is cancelled or deleted, or a Notetaker’s settings are null. If the bot was created for an ad-hoc meeting, Nylas omits the event.ical_uid and event.event_id fields from the notification.
{ "specversion": "1.0", "type": "notetaker.deleted", "source": "/nylas/notetaker", "id": "<WEBHOOK_ID>", "time": 1737500935555, "webhook_delivery_attempt": 0, "data": { "application_id": "<NYLAS_APPLICATION_ID>", "object": { "id": "<NOTETAKER_ID>", "grant_id": "<NYLAS_GRANT_ID>", "calendar_id": "<CALENDAR_ID>", "event": { "ical_uid": "<ICAL_UID>", "event_id": "<EVENT_ID>", "master_event_id": "<EVENT_ID>" } } }}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": "<WEBHOOK_ID>", "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": [{ }], "body": "<div dir=\"ltr\">Test with attachments</div>\r\n", "cc": [{ }], "date": 1723821981, "folders": ["SENT"], "from": [{ "name": "Nylas Swag" }], "grant_id": "<NYLAS_GRANT_ID>", "id": "<MESSAGE_ID>", "metadata": { "key1": "all-meetings", "key2": "on-site" }, "object": "message", "reply_to": [], "snippet": "This message has an attachment.", "starred": false, "subject": "Let's send an attachment", "thread_id": "<THREAD_ID>", "to": [{ }], "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": "<WEBHOOK_ID>", "time": 1723821985, "webhook_delivery_attempt": 1, "data": { "application_id": "<NYLAS_APPLICATION_ID>", "object": { "body": "<div dir=\"ltr\">Test with attachments</div>\r\n", "cc": [{ "name": "Nyla" }], "date": 1234567890, "folders": ["INBOX"], "from": [{ "name": "Leyah Miller" }], "grant_id": "<NYLAS_GRANT_ID>", "id": "<MESSAGE_ID>", "metadata": { "key1": "all-meetings", "key2": "on-site" }, "object": "message", "reply_to_message_id": "<MESSAGE_ID>", "snippet": "This message has an attachment.", "starred": false, "subject": "Let's send an attachment", "thread_id": "<THREAD_ID>", "to": [{ }], "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": [{ "name": "Mock bcc name " }], "body": "mock-body", "cc": [{ "name": "Mock cc name" }], "from": [{ }], "id": "mock-id", "reply_to": [{ "name": "Mock reply to name " }], "schedule_id": "mock-schedule-id", "send_at": 1234567880, "subject": "Mock Subject", "to": [{ "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": [{ "name": "Mock bcc name " }], "body": "mock-body", "cc": [{ "name": "Mock cc name" }], "from": [{ }], "id": "mock-id", "reply_to": [{ "name": "Mock reply to name " }], "schedule_id": "mock-schedule-id", "send_at": 1234567880, "subject": "Mock Subject", "to": [{ "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", "type": "mailbox_unavailable", "code": 550, "grant_id": "mock-grant-id", "origin": { "to": [ ], "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":[ { "type":"work" }, { "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":[ { "type":"work" }, { "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" } ] } }}