Version:
Only show these results:

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

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": "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 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": "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

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/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 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"
    }
  }
}

Scheduler notifications

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

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

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

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": "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 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": "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 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": "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 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": "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 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. 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 be notified when a tracking trigger is fulfilled on email 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.

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 email message.

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

Nylas sends a message.link_clicked 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
    }
  }
}

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"
    }
  }
}   
{
  "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

You can subscribe to the following Order Consolidation triggers to be notified when an end user receives an email message with order or tracking information:

Order notifications

Nylas sends a message.intelligence.order notification when an end user receives an email message that contains 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 an end user receives an email message that contains 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"
    }
  }
}

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.updated
  • contact.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":"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 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":"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"
        }
      ]
    }
  }
}