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.