# Notification reference

Source: https://developer.nylas.com/docs/reference/notifications/

Schema reference for all Nylas webhook notification payloads. Each notification uses the CloudEvents envelope format with a trigger-specific `data.object` payload.

## Notification types

### [Grants](https://developer.nylas.com/docs/reference/notifications/grants/)

Notifications about grant lifecycle events including creation, updates, expiration, and deletion.

- `grant.created` - Sent when a user successfully authenticates with your Nylas application for the first time.
- `grant.updated` - Sent when a grant is modified, updated, or re-authenticated.
- `grant.deleted` - Sent when a grant is deleted because of a Delete Grant request.
- `grant.expired` - Sent when a grant's credentials expire, typically due to a change in the user's password on the provider, OAuth token expiration without successful refresh, the provider revoking access, or an admin revoking app permissions.
- `grant.imap_sync_completed` - Sent when a grant is created for an IMAP account and the initial historic sync completes.

### [Messages](https://developer.nylas.com/docs/reference/notifications/messages/)

Notifications about email message events — new messages, updates, send results, bounces, and tracking.

- `message.created` - Sent when a new message arrives or is synced for a user.
- `message.created.cleaned` - Sent when a new message is synced and the [Clean Conversations](/docs/v3/email/parse-messages/) feature is enabled for the application. The message `body` contains cleaned markdown content instead of the original HTML.
- `message.updated` - Sent when a user modifies or updates a message.
- `message.deleted` - Sent when a message is deleted.
- `message.send_success` - Sent when a scheduled message is sent and delivered successfully. Requires the `send_at` parameter.
- `message.send_failed` - Sent when a scheduled message fails to deliver. Requires the `send_at` parameter.
- `message.bounce_detected` - Sent when Nylas detects a Non-Delivery Report (NDR) in the sender's inbox for a message sent via Nylas. Requires the provider to generate an NDR. Available for Google, Microsoft Graph, iCloud, and Yahoo.

### [Message Tracking](https://developer.nylas.com/docs/reference/notifications/message-tracking/)

Notifications for tracked message opens, link clicks, and replies.

- `message.opened` - Sent when a participant opens a tracked message.
- `message.link_clicked` - Sent when a participant clicks a link in a tracked message.
- `thread.replied` - Sent when a participant replies to a tracked email thread.
- `message.opened.legacy` - Legacy format for message opened tracking notifications.
- `message.link_clicked.legacy` - Legacy format for link clicked tracking notifications.
- `thread.replied.legacy` - Legacy format for thread replied tracking notifications.

### [Message Metadata](https://developer.nylas.com/docs/reference/notifications/message-metadata/)

Limited notifications for Google accounts using the gmail.metadata scope.

- `message.created.metadata` - Sent for Google grants using the `/gmail.metadata` scope. Does not include `body`, `snippet`, or `attachment` fields.
- `message.updated.metadata` - Sent for Google grants using the `/gmail.metadata` scope when a message is updated. Limited field set.

### [Folders and Labels](https://developer.nylas.com/docs/reference/notifications/folders/)

Notifications about email folder and label events.

- `folder.created` - Sent when a user creates a folder.
- `folder.updated` - Sent when a user updates a folder.
- `folder.deleted` - Sent when a user deletes a folder.

### [Calendar](https://developer.nylas.com/docs/reference/notifications/calendar/)

Notifications about calendar creation, modification, and deletion.

- `calendar.created` - Sent when a user creates a calendar.
- `calendar.updated` - Sent when the name, description, location, or timezone of a calendar changes.
- `calendar.deleted` - Sent when a user deletes a calendar.

### [Events](https://developer.nylas.com/docs/reference/notifications/events/)

Notifications about calendar event creation, modification, and deletion.

- `event.created` - Sent when an event is created on a user's calendar.
- `event.updated` - Sent when an event is modified or updated. Includes the `occurrences` parameter if the updated event is a single occurrence of a recurring Google event.
- `event.deleted` - Sent when an event is deleted from a user's calendar.

### [Contacts](https://developer.nylas.com/docs/reference/notifications/contacts/)

Notifications about contact creation, modification, and deletion.

- `contact.updated` - Sent when a user creates or updates a contact. Most providers don't differentiate between creating and updating contacts.
- `contact.deleted` - Sent when a user deletes a contact.

### [Scheduler](https://developer.nylas.com/docs/reference/notifications/scheduler/)

Notifications about booking events from Nylas Scheduler.

- `booking.created` - Sent when a guest creates a booking.
- `booking.pending` - Sent when a guest schedules a pending booking that requires confirmation.
- `booking.rescheduled` - Sent when a guest reschedules a booking.
- `booking.cancelled` - Sent when a guest cancels a booking.
- `booking.reminder` - Sent at the scheduled reminder time before a booking.

### [Notetaker](https://developer.nylas.com/docs/reference/notifications/notetaker/)

Notifications about Notetaker bot lifecycle, meeting states, and media processing.

- `notetaker.created` - Sent when you create or schedule a Notetaker bot. For ad-hoc meetings, `join_time`, `event.ical_uid`, and `event.event_id` are omitted.
- `notetaker.updated` - Sent when you update a scheduled Notetaker bot's settings or join time. Only fires while in `scheduled` state.
- `notetaker.deleted` - Sent when a Notetaker bot is deleted, its associated event is cancelled, or its settings are set to null.
- `notetaker.meeting_state` - Sent when the Notetaker bot transitions between meeting lifecycle states. The notification includes both a `state` field (the lifecycle phase) and a `meeting_state` field (the specific reason for the transition).
- `notetaker.media` - Sent when a recording or transcription is processing, available, or deleted.

### [Transactional Email](https://developer.nylas.com/docs/reference/notifications/transactional-email/)

Delivery status notifications for transactional emails.

- `message.transactional.bounced` - Sent when a transactional email was not delivered due to a hard bounce.
- `message.transactional.complaint` - Sent when a transactional email was delivered but the recipient marked it as spam.
- `message.transactional.delivered` - Sent when a transactional email was successfully delivered to the recipient's mail server.
- `message.transactional.rejected` - Sent when a transactional email was rejected because one or more attachments contained a virus.

### [Agent Accounts](https://developer.nylas.com/docs/reference/notifications/agent-accounts/)

Delivery status notifications for email sent from Agent Accounts.

- `message.bounced` - Sent when an email was not delivered due to a hard bounce.
- `message.complaint` - Sent when an email was delivered but the recipient marked it as spam.
- `message.delivered` - Sent when an email was successfully delivered to the recipient's mail server.
- `message.rejected` - Sent when an email was rejected because one or more attachments contained a virus.