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 ' \\\n --data '{\n \"trigger_type\": \"calendar.created\",\n \"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 ' \\\n --data-raw '{\n \"description\": \"PubSub Test\",\n \"trigger_types\": [\"message.send_success\"],\n \"encryption_key\": \"\",\n \"topic\": \"projects//topics/\",\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 ' \\" /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/' \\\n --header 'Accept: application/json' \\\n --header 'Authorization: Bearer ' \\" 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/' \\\n --header 'Content-Type: application/json' \\\n --header 'Accept: application/json' \\\n --header 'Authorization: Bearer ' \\\n --data-raw '{\n \"description\": \"PubSub Update Test\",\n \"trigger_types\": [\"message.updated\"],\n \"encryption_key\": \"\",\n \"topic\": \"projects//topics/\",\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/' \\\n --header 'Accept: application/json' \\\n --header 'Authorization: Bearer ' \\" responses: '200': $ref: '#/components/responses/delete_200' description: Returns a success message. '400': $ref: '#/components/responses/delete_400' description: Returns an error message. components: 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 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.' 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).' responses: 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. 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. 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. 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. 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. 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. 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. 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. '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. 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. 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. 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.