Nylas Pub/Sub Notifications API
Nylas offers two ways to get notifications of what's happening on the provider. You can either subscribe to webhook notifications, or you can set up a notification channel. Nylas offers Pub/Sub and Amazon SNS notification channels. These can be used in place of, or in addition to, normal webhook notifications. To use Pub/Sub notifications, you first need to set up a Pub/Sub queue on Google Cloud Platform. For detailed set up instructions see the [Pub/Sub notifications documentation](/docs/v3/notifications/pubsub-channel/). To use Amazon SNS notifications, you need to set up an SNS topic and IAM role in your AWS account. For detailed set up instructions see the [Amazon SNS notifications documentation](/docs/v3/notifications/sns-channel/). Nylas notification channels use the same notification [trigger types and schemas](/docs/reference/notifications/) as webhook notifications, and require the same [provider scopes](/docs/dev-guide/scopes/). ## Payload compression Both Pub/Sub and SNS channels accept a `compressed_delivery` boolean that gzip-compresses each notification payload before delivery. Nylas adds a `content_encoding` message attribute (`gzip` for Pub/Sub, `gzip+base64` for SNS) so your subscriber knows which messages to decompress. We strongly recommend enabling it on SNS channels, where the 256 KB message limit makes compression the simplest way to avoid payload truncation. For setup and decode patterns, see [Reducing payload size with compression](/docs/dev-guide/best-practices/compression/). ## Monitor grant status The most important notifications to subscribe to are those related to grant status: `grant.created`, `grant.updated`, `grant.deleted`, and `grant.expired`. They allow you to automate important grant lifecycle processes, like onboarding messages, data refreshes, and backend deletions. The `grant.expired` trigger notifies you when a user needs to re-authenticate their account. When you receive a `grant.expired` notification, you can take appropriate action (for example, notifying the user or starting a background re-authentication process). 📝 When a grant becomes invalid, Nylas cannot access the user's data and does not send you notifications about it. When you re-authenticate a grant, Nylas looks at when the grant last authenticated successfully. If it was less than 72 hours ago, Nylas looks for any changes that happened since the time of the last successful sync, and sends you notifications about them. This can be a lot of notifications. If the grant has been out of service for more than 72 hours, Nylas does _not_ send backfill notifications. In this case, look for the `grant.expired` and `grant.updated` notifications, and query the Nylas API for objects that changed between those timestamps.
POST
/v3/webhooks/mock-payload
Get mock notification payload
#
POST
/v3/channels/pubsub
Create a Pub/Sub channel
#
GET
/v3/channels/pubsub
Get Pub/Sub channels for an application
#
GET
/v3/channels/pubsub/{id}
Get a specific Pub/Sub channel
#
PUT
/v3/channels/pubsub/{id}
Update a Pub/Sub channel
#
DELETE
/v3/channels/pubsub/{id}
Delete a specific Pub/Sub channel
#
Documentation
Specifications
Other Resources
Every API here is available over the APIs.io API and to AI agents over MCP.
MCP server
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
Tools for apis
7 MCP tools reach this
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.
All 92 tools →
Call it yourself
curl for this page
This API
curl "https://apis.io/api/v1/apis/nylas-pub-sub-notifications-api"
All apis
curl "https://apis.io/api/v1/apis?limit=25"
Discovery needs no key. Ratings and market analysis are Pro.
Get an API key
Free tier, no form to fill in. Signing in shares your email address with us — we
store it to create your key and to recognise you if you sign in with another
provider. See our Privacy Policy and
Terms.
A second provider on the same verified email joins the account you already have.
openapi: 3.2.0
info:
title: Nylas Pub/Sub Notifications API
version: v3
summary: The complete Nylas v3 API — Email, Calendar, Contacts, Notetaker, Scheduling, Administration, and Migration.
description: The Nylas API is designed using the REST ideology to provide simple and predictable URIs to access and modify objects.
contact:
url: https://www.nylas.com/
x-provenance:
method: harvested
first_party: true
publisher: Nylas
source: https://developer.nylas.com/_spec-files/nylas-api.yaml
harvested: '2026-08-21'
sha256: 7ff001d571e163b1ffe22178741b59f813d8208ec878157a839a33dc2c13fd35
bytes: 1666223
note: 'Published by Nylas as the unified contract for the Nylas v3 API and stored verbatim; API Evangelist added only this provenance block. Submitted by the provider in api-evangelist/nylas#1 and verified against the live URL before harvest: OpenAPI 3.1.0, 118 paths, 208 operations, 174 component schemas, 100% of operations carrying summary, description, tag and a unique operationId, x-code-samples on 208 of 208. This document REPLACES a 22-operation scaffold API Evangelist derived from reading the documentation, now quarantined under openapi/_scaffold/.'
x-evidence:
- url: https://developer.nylas.com/_spec-files/nylas-api.yaml
what: the published unified contract, harvested verbatim 2026-08-21 (200, text/yaml, 1,666,223 bytes)
- url: https://developer.nylas.com/.well-known/api-catalog
what: RFC 9727 linkset advertising that URL as service-desc for api.us.nylas.com and api.eu.nylas.com (200, application/linkset+json)
servers:
- url: https://api.us.nylas.com
description: U.S.
- url: https://api.eu.nylas.com
description: E.U.
security:
- ACCESS_TOKEN: []
- NYLAS_API_KEY: []
tags:
- name: Pub/Sub Notifications
description: Nylas offers two ways to get notifications of what's happening on the provider.
paths:
/v3/webhooks/mock-payload:
post:
operationId: get_mock_webhook_payload
tags:
- Pub/Sub Notifications
summary: Get mock notification payload
description: 'Use this endpoint to see example notification payloads for the different Nylas events you specify,
to the webhook URL you specify.'
x-code-samples:
- lang: bash
label: cURL
source: "curl --request POST \\\n --url 'https://api.us.nylas.com/v3/webhooks/mock-payload' \\\n --header 'Content-Type: application/json' \\\n --header 'Accept: application/json' \\\n --header 'Authorization: Bearer <NYLAS_API_KEY>' \\\n --data '{\n \"trigger_type\": \"calendar.created\",\n \"webhook_url\": \"<WEBHOOK_URL>\"\n }'"
security:
- NYLAS_API_KEY: []
responses:
'200':
$ref: '#/components/responses/get_mock_payload_200'
description: Returns the mock payload for corresponding trigger type.
'400':
$ref: '#/components/responses/400'
requestBody:
required: true
description: Destination definition
content:
application/json:
schema:
$ref: '#/components/schemas/get_mock_payload_input'
/v3/channels/pubsub:
post:
summary: Create a Pub/Sub channel
tags:
- Pub/Sub Notifications
operationId: create-pubsub-channel
description: Create a Pub/Sub channel in the specified application.
security:
- NYLAS_API_KEY: []
responses:
'200':
$ref: '#/components/responses/create_pubsub_200'
description: Returns the new Destination
'400':
$ref: '#/components/responses/create_pubsub_400'
description: Returns the new Destination
requestBody:
required: true
description: Destination definition
content:
application/json:
schema:
$ref: '#/components/schemas/pubsub_input_payload'
x-code-samples:
- lang: bash
label: cURL
source: "curl --request POST \\\n --url 'https://api.us.nylas.com/v3/channels/pubsub' \\\n --header 'Content-Type: application/json' \\\n --header 'Accept: application/json' \\\n --header 'Authorization: Bearer <NYLAS_API_KEY>' \\\n --data-raw '{\n \"description\": \"PubSub Test\",\n \"trigger_types\": [\"message.send_success\"],\n \"encryption_key\": \"\",\n \"topic\": \"projects/<YOUR_PROJECT_ID>/topics/<YOUR_TOPIC_ID>\",\n \"notification_email_addresses\": [\"leyah@example.com\"]\n }'"
get:
summary: Get Pub/Sub channels for an application
tags:
- Pub/Sub Notifications
operationId: get-pubsub-channels
description: Get the Pub/Sub channels for an application.
security:
- NYLAS_API_KEY: []
responses:
'200':
$ref: '#/components/responses/get_pubsub_200'
description: List of destinations for an application.
'400':
$ref: '#/components/responses/get_pubsub_400'
description: List of destinations for an application.
x-code-samples:
- lang: bash
label: cURL
source: "curl --request GET \\\n --url 'https://api.us.nylas.com/v3/channels/pubsub/' \\\n --header 'Accept: application/json' \\\n --header 'Authorization: Bearer <NYLAS_API_KEY>' \\"
/v3/channels/pubsub/{id}:
get:
operationId: get-pubsub-by-id
tags:
- Pub/Sub Notifications
summary: Get a specific Pub/Sub channel
description: Get a specific Pub/Sub channel from a specific Nylas application.
security:
- NYLAS_API_KEY: []
parameters:
- name: id
in: path
description: The ID of the Pub/Sub channel to retrieve.
required: true
schema:
type: string
x-code-samples:
- lang: bash
label: cURL
source: "curl --request GET \\\n --url 'https://api.us.nylas.com/v3/channels/pubsub/<PUBSUB_ID>' \\\n --header 'Accept: application/json' \\\n --header 'Authorization: Bearer <NYLAS_API_KEY>' \\"
responses:
'200':
$ref: '#/components/responses/get_pubsub_by_id_200'
description: The destinations matching the query
'400':
$ref: '#/components/responses/get_pubsub_400'
put:
operationId: put-pubsub-by-id
tags:
- Pub/Sub Notifications
summary: Update a Pub/Sub channel
description: 'Updates the specified Pub/Sub channel.
When you make a `PUT` request, Nylas replaces all data in the nested object with the information
included in your request. For more information, see
Updating objects.'
security:
- NYLAS_API_KEY: []
parameters:
- name: id
in: path
description: The ID of the Pub/Sub channel to retrieve.
required: true
schema:
type: string
requestBody:
required: true
description: The Pub/Sub channel properties to update.
content:
application/json:
schema:
type: object
properties:
description:
type: string
description: A human-readable description of the Pub/Sub channel.
example: Prod account status notifications PubSub
trigger_types:
$ref: '#/components/schemas/trigger_types'
topic:
type: string
description: The Google Pub/Sub topic that Nylas sends notifications to.
example: projects/your-project-id/topics/your-topic-id
status:
type: string
description: The new status of the channel. Use this to restart a channel that you manually paused, or that was automatically paused due to deliverability issues.
enum:
- active
- pause
notification_email_addresses:
type: array
items:
type: string
description: The email addresses that Nylas notifies if there are errors or deliverability problems. See the [rate limit documentation](/docs/dev-guide/best-practices/rate-limits/) for details.
example:
- sysadmin@example.com
- sre_pager@example.com
compressed_delivery:
type: boolean
description: 'If `true`, Nylas compresses notification payloads using gzip before delivering them. Nylas adds a `content_encoding: gzip` message attribute to the Pub/Sub message.'
example: true
x-code-samples:
- lang: bash
label: cURL
source: "curl --request PUT \\\n --url 'https://api.us.nylas.com/v3/channels/pubsub/<PUBSUB_ID>' \\\n --header 'Content-Type: application/json' \\\n --header 'Accept: application/json' \\\n --header 'Authorization: Bearer <NYLAS_API_KEY>' \\\n --data-raw '{\n \"description\": \"PubSub Update Test\",\n \"trigger_types\": [\"message.updated\"],\n \"encryption_key\": \"\",\n \"topic\": \"projects/<YOUR_PROJECT_NAME>/topics/<YOUR_TOPIC_NAME>\",\n \"notification_email_addresses\": [\"leyah@example.com\"]\n }'"
responses:
'200':
$ref: '#/components/responses/update_pubsub_200'
'400':
$ref: '#/components/responses/update_pubsub_400'
delete:
operationId: delete-pubsub-by-id
tags:
- Pub/Sub Notifications
summary: Delete a specific Pub/Sub channel
description: Delete a specific Pub/Sub channel from a specific Nylas application.
security:
- NYLAS_API_KEY: []
parameters:
- name: id
in: path
description: The ID of the Pub/Sub channel to retrieve.
required: true
schema:
type: string
x-code-samples:
- lang: bash
label: cURL
source: "curl --request DELETE \\\n --url 'https://api.us.nylas.com/v3/channels/pubsub/<PUBSUB_ID>' \\\n --header 'Accept: application/json' \\\n --header 'Authorization: Bearer <NYLAS_API_KEY>' \\"
responses:
'200':
$ref: '#/components/responses/delete_200'
description: Returns a success message.
'400':
$ref: '#/components/responses/delete_400'
description: Returns an error message.
components:
responses:
get_mock_payload_200:
description: Webhook Payload Returned
content:
application/json:
schema:
type: object
properties:
data:
type: object
properties:
data:
type: object
description: This object is an example payload that Nylas sends to your webhook destination
request_id:
type: string
description: The ID for each request.
delete_400:
description: Notification channel not deleted
content:
application/json:
schema:
type: object
properties:
error:
type: object
properties:
type:
type: string
description: An alphanumeric code that represents the error type.
example: '70000'
message:
type: string
description: A human readable message with details about the error.
example: 'destination.id.not.found : record not found'
request_id:
type: string
description: The unique ID of the request that generated this response.
delete_200:
description: Destination Deleted
content:
application/json:
schema:
type: object
properties:
data:
type: object
properties:
status:
type: string
enum:
- success
request_id:
type: string
description: The ID for each request.
update_pubsub_400:
description: Pub/Sub channel not updated
content:
application/json:
schema:
type: object
properties:
error:
type: object
properties:
type:
type: string
description: An alphanumeric code that represents the error type.
example: '70000'
message:
type: string
description: A human readable message with details about the error.
example: 'invalid.input.format : topic is required"'
request_id:
type: string
description: The unique ID of the request that generated this response.
create_pubsub_400:
description: Unable to create Pub/Sub channel
content:
application/json:
schema:
type: object
properties:
error:
type: object
properties:
type:
type: string
description: An alphanumeric code that represents the error type.
example: '70005'
message:
type: string
description: A human-readable message with details about the error.
example: 'invalid.input.format : topic is required'
request_id:
type: string
description: The unique ID of the request that generated this response.
'400':
description: Bad Request
content:
application/json:
schema:
title: error
type: object
properties:
request_id:
type: string
description: The request ID.
error:
type: object
description: The response error object.
properties:
type:
type: string
description: The error type.
message:
type: string
description: The error message.
provider_error:
type: object
description: The error from the provider.
examples:
Bad Request:
value:
request_id: 5fa64c92-e840-4357-86b9-2aa364d35b88
error:
type: invalid_request_error
message: error parsing request body
provider_error:
code: TargetIdShouldNotBeMeOrWhitespace
message: Id is malformed.
Invalid Idempotency-Key:
value:
request_id: 5fa64c92-e840-4357-86b9-2aa364d35b88
error:
type: api.invalid_idempotency_key
message: Idempotency-Key must be 256 characters or fewer.
get_pubsub_by_id_200:
description: Get specific Pub/Sub channel information
content:
application/json:
schema:
type: object
properties:
data:
type: object
properties:
id:
type: string
description: A unique identifier for the Pub/Sub channel.
example: UMWjAjMeWQ4D8gYF2moonK4486
description:
type: string
description: A human-readable description of the Pub/Sub channel.
example: Production Pub/Sub for Event updates
trigger_types:
$ref: '#/components/schemas/trigger_types'
topic:
type: string
description: The Google Pub/Sub topic that Nylas sends notifications to.
example: projects/your-project-id/topics/your-topic-id
status:
type: string
description: The deliverability status of the Pub/Sub channel.
enum:
- active
- pause
- failing
- failed
notification_email_addresses:
type: array
items:
type: string
description: The email addresses that Nylas notifies if delivery to the Pub/Sub channel fails.
example:
- jane@example.com
- joe@example.com
compressed_delivery:
type: boolean
description: If `true`, Nylas compresses notification payloads using gzip before delivering them.
example: false
status_updated_at:
type: integer
description: The time the `status` field was last updated, represented as a Unix timestamp in seconds.
example: 1234567890
created_at:
type: integer
description: The time the Pub/Sub channel was created, represented as a Unix timestamp in seconds.
example: 1234567890
updated_at:
type: integer
description: The time the Pub/Sub channel was last updated, represented as a Unix timestamp in seconds.
example: 1234567890
request_id:
type: string
description: The unique ID of the request that generated this response.
get_pubsub_200:
description: Get Pub/Sub channel information
content:
application/json:
schema:
type: object
properties:
data:
type: array
items:
type: object
properties:
id:
type: string
description: A unique identifier for the Pub/Sub notification channel.
example: UMWjAjMeWQ4D8gYF2moonK4486
description:
type: string
description: A human-readable description of the Pub/Sub notification channel.
example: Production Pub/Sub channel for Email notifications
trigger_types:
$ref: '#/components/schemas/trigger_types'
topic:
type: string
description: The Google Pub/Sub topic that Nylas sends notifications to.
example: projects/your-project-id/topics/your-topic-id
status:
type: string
description: The status of the new destination.
enum:
- active
- paused
- failing
- failed
notification_email_addresses:
type: array
items:
type: string
description: The email addresses that Nylas notifies if delivery to the Pub/Sub channel fails.
example:
- jane@example.com
- joe@example.com
compressed_delivery:
type: boolean
description: If `true`, Nylas compresses notification payloads using gzip before delivering them.
example: false
request_id:
type: string
description: The unique ID of the request that generated this response.
create_pubsub_200:
description: Pub/Sub channel created
content:
application/json:
schema:
type: object
properties:
data:
type: object
properties:
id:
type: string
description: A unique identifier for the Pub/Sub notification channel.
example: UMWjAjMeWQ4D8gYF2moonK4486
description:
type: string
description: A human-readable description of the Pub/Sub notification channel.
example: Production Pub/Sub channel for Grant notifications
trigger_types:
$ref: '#/components/schemas/trigger_types'
topic:
type: string
description: The Google Pub/Sub topic that Nylas sends notifications to.
example: projects/your-project-id/topics/your-topic-id
status:
type: string
description: The status of the Pub/Sub channel. When you first create a new channel, Nylas sets it to "active".
enum:
- active
notification_email_addresses:
type: array
items:
type: string
description: The email addresses that Nylas notifies if delivery to the Pub/Sub channel fails.
example:
- jane@example.com
- joe@example.com
compressed_delivery:
type: boolean
description: If `true`, Nylas compresses notification payloads using gzip before delivering them.
example: false
request_id:
type: string
description: The unique ID of the request that generated this response.
update_pubsub_200:
description: Pub/Sub channel updated
content:
application/json:
schema:
type: object
properties:
data:
type: object
properties:
id:
type: string
description: A unique identifier for the Pub/Sub channel.
example: UMWjAjMeWQ4D8gYF2moonK4486
description:
type: string
description: A human-readable description of the Pub/Sub channel.
example: Production Pub/Sub channel
trigger_types:
$ref: '#/components/schemas/trigger_types'
topic:
type: string
description: The Google Pub/Sub topic that Nylas sends notifications to.
example: projects/your-project-id/topics/your-topic-id
status:
type: string
description: The deliverability status of the Pub/Sub channel.
enum:
- active
- pause
- failing
- failed
notification_email_addresses:
type: array
items:
type: string
description: The email addresses that Nylas notifies if delivery to the Pub/Sub channel fails.
example:
- jane@example.com
- joe@example.com
compressed_delivery:
type: boolean
description: If `true`, Nylas compresses notification payloads using gzip before delivering them.
example: false
status_updated_at:
type: integer
description: The time the `status` field was last updated, represented as a Unix timestamp in seconds.
example: 1234567890
created_at:
type: integer
description: The time the Pub/Sub channel was created, represented as a Unix timestamp in seconds.
example: 1234567890
updated_at:
type: integer
description: The time the Pub/Sub channel was last updated, represented as a Unix timestamp in seconds.
example: 1234567890
request_id:
type: string
description: The unique ID of the request that generated this response.
get_pubsub_400:
description: Unable to get Pub/Sub channel information
content:
application/json:
schema:
type: object
properties:
error:
type: object
properties:
type:
type: string
description: An alphanumeric code that represents the error type.
example: '70001'
message:
type: string
description: A human readable message with details about the error.
example: 'invalid.input.format : topic is required'
request_id:
type: string
description: The unique ID of the request that generated this response.
schemas:
pubsub_input_payload:
title: Destination Payload
required:
- trigger_types
- webhook_url
type: object
properties:
description:
type: string
description: A human-readable description of the Pub/Sub channel.
example: Production Pub/Sub for Events notifications
trigger_types:
$ref: '#/components/schemas/trigger_types'
topic:
type: string
description: The Google Pub/Sub topic that Nylas sends notifications to.
example: projects/your-project-id/topics/your-topic-id
notification_email_addresses:
type: array
items:
type: string
description: The email addresses that Nylas notifies if delivery to the Pub/Sub channel fails.
example:
- jane@example.com
- joe@example.com
compressed_delivery:
type: boolean
description: 'If `true`, Nylas compresses notification payloads using gzip before delivering them. Nylas adds a `content_encoding: gzip` message attribute to the Pub/Sub message. Default is `false`.'
default: false
example: true
get_mock_payload_input:
title: Input Payload
type: object
required:
- trigger_type
- webhook_url
properties:
trigger_type:
type: string
enum:
- calendar.created
- calendar.updated
- calendar.deleted
- event.created
- event.updated
- event.deleted
- grant.created
- grant.updated
- grant.deleted
- grant.expired
- message.send_success
- message.send_failed
- message.bounce_detected
- message.created
- message.created.truncated
- message.created.cleaned
- message.updated
- message.updated.truncated
- contact.updated
- contact.deleted
- folder.created
- folder.updated
- folder.deleted
- message.opened
- message.link_clicked
- thread.replied
description: 'The event that will trigger the mock notification. See the
[notification schemas](/docs/reference/notifications/) for details about each
trigger type.
See the [Grants](/docs/reference/api/manage-grants/), [Calendar](/docs/reference/api/calendar/),
[Events](/docs/reference/api/events/), and [Messages](/docs/reference/api/messages/) references
for information on how to trigger each event type.
You can test `message.created.truncated` and `message.updated.truncated` notifications using this
endpoint. For more information, see
[Truncated webhooks](/docs/v3/notifications/#truncated-webhooks).'
trigger_types:
type: array
items:
type: string
enum:
- calendar.created
- calendar.updated
- calendar.deleted
- event.created
- event.updated
- event.deleted
- grant.created
- grant.updated
- grant.deleted
- grant.expired
- grant.imap_sync_completed
- message.send_success
- message.send_failed
- message.bounce_detected
- message.created
- message.created.cleaned
- message.opened
- message.opened.legacy
- message.updated
- message.link_clicked
- message.link_clicked.legacy
- thread.replied
- thread.replied.legacy
- contact.updated
- contact.deleted
- folder.created
- folder.updated
- folder.deleted
- booking.created
- booking.pending
- booking.rescheduled
- booking.cancelled
- booking.reminder
- message.deleted
- message.transactional.bounced
- message.transactional.complaint
- message.transactional.delivered
- message.transactional.rejected
- message.bounced
- message.complaint
- message.delivered
- message.rejected
- notetaker.created
- notetaker.updated
- notetaker.deleted
- notetaker.meeting_state
- notetaker.media
description: 'The event that triggers the notification. See the
[notification schemas](/docs/reference/notifications/) for details about each trigger
type.
See the [Grants](/docs/reference/api/manage-grants/), [Calendar](/docs/reference/api/calendar/),
[Events](/docs/reference/api/events/), and [Messages](/docs/reference/api/messages/) references
for information on how to trigger each event type.'
securitySchemes:
ACCESS_TOKEN:
scheme: bearer
type: http
bearerFormat: NYLAS_ACCESS_TOKEN
description: 'The Nylas **access token** for a specific grant. Issued as part of OAuth 2.1 flow token
exchange.'
NYLAS_API_KEY:
scheme: bearer
type: http
bearerFormat: NYLAS_API_KEY
description: 'The Nylas **API key** provides application-level access to APIs and all grants. You can
generate these from the Dashboard. Learn more about [authorizing requests](/docs/v3/auth/).'
SCHEDULER_SESSION_TOKEN:
scheme: bearer
type: http
bearerFormat: Session ID
description: The Nylas Scheduler **session ID** that Scheduler UI Components use to authorize API requests.