Receive notifications with Amazon SNS

You run on AWS, and standing up a public HTTPS endpoint just to catch Nylas webhooks adds infrastructure you’d rather not own. If your services already consume from SNS and SQS, it’s cleaner to drop events onto a topic and fan them out from there.

Nylas can deliver notifications to an Amazon SNS topic as an alternative to an HTTP webhook. You subscribe to the same triggers, but each event is published to your SNS topic instead of posted to a URL you host. For how Nylas assumes your IAM role and publishes to the topic, see the SNS delivery diagram.

How Nylas delivers to an SNS channel

Your AWS account

Create an SNS topic

A standard topic. Nylas rejects FIFO topics.

Your AWS account

Create a role for Nylas

Trust Nylas's Google identity and allow sns:Publish on the topic.

Your app

Create the channel

In the Dashboard (Notifications, then Create SNS Channel) or with POST /v3/channels/sns. Set topic, role_arn, and trigger types.

Nylas

Send a test message

Assumes your role and publishes a connector.verification event to the topic.

Role or publish fails

Channel not created

Nylas returns 400 with the reason.

When subscribed data changes

Nylas

Publish notifications

An SNS Notification with the CloudEvents payload as a string in Message.

Optional parameters

• compressed_delivery: gzip-compresses and base64-encodes the payload first, with a content_encoding: gzip+base64 attribute. Without it, Message is plain JSON.

Still over 256,000 bytes

Truncate the payload

Blanks body and description, and adds .truncated to the type.

Too large even after truncating

Not delivered

Nylas drops this notification.

Your subscriber

Parse the message

Route on the trigger_type attribute, then parse Message as JSON.

Type ends in .truncated

Fetch the object

Request it from the Nylas API by its ID.

Nylas assumes an IAM role in your AWS account and publishes to your SNS topic. It tests the role when you create the channel, and truncates only payloads that are still too large after any compression.

Diagram as text

• Your AWS account: Create an SNS topic: A standard topic. Nylas rejects FIFO topics.
• Your AWS account: Create a role for Nylas: Trust Nylas's Google identity and allow sns:Publish on the topic.
• Your app: Create the channel: In the Dashboard (Notifications, then Create SNS Channel) or with POST /v3/channels/sns. Set topic, role_arn, and trigger types.
• Nylas: Send a test message: Assumes your role and publishes a connector.verification event to the topic.
  • Role or publish fails → Channel not created: Nylas returns 400 with the reason.
• Nylas: Publish notifications: An SNS Notification with the CloudEvents payload as a string in Message. (When subscribed data changes)
  • Optional parameter compressed_delivery: gzip-compresses and base64-encodes the payload first, with a content_encoding: gzip+base64 attribute. Without it, Message is plain JSON.
  • Still over 256,000 bytes → Truncate the payload: Blanks body and description, and adds .truncated to the type.
  • Too large even after truncating → Not delivered: Nylas drops this notification.
• Your subscriber: Parse the message: Route on the trigger_type attribute, then parse Message as JSON.
  • Type ends in .truncated → Fetch the object: Request it from the Nylas API by its ID.

How do I send notifications to an SNS topic?

Create an SNS channel with a POST /v3/channels/sns request. You pass the SNS topic ARN, a role_arn for the IAM role Nylas assumes to publish, a list of trigger_types, and optional notification_email_addresses for downtime alerts. It then publishes 1 message to the topic per matching event, and your SNS subscribers take it from there.

The request below creates an SNS channel subscribed to one trigger.

Request

curl --request POST \
  --url 'https://api.us.nylas.com/v3/channels/sns' \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer <NYLAS_API_KEY>' \
  --data-raw '{
    "description": "SNS Test",
    "trigger_types": ["message.send_success"],
    "topic": "arn:aws:sns:us-east-1:123456789012:my-topic",
    "role_arn": "arn:aws:iam::123456789012:role/nylas-sns-role",
    "notification_email_addresses": ["[email protected]"]
  }'

When should I use SNS instead of webhooks?

SNS fits when you’re on AWS and want native fan-out: one topic can push the same event to SQS queues, Lambda functions, and HTTP subscribers at once, with retries handled by AWS. That decoupling matters during a burst, such as the up to 72 hours of events replayed when a grant recovers. Both channels carry the same notification payloads.

Reach for a standard HTTPS webhook instead when you aren’t on AWS or want the simplest setup, since a webhook needs only 1 reachable URL.

Things to know about SNS channels

A couple of AWS-specific details matter. Nylas publishes using the IAM role you name in role_arn, so that role must grant sns:Publish on the topic, and the topic must be the full ARN. The channel subscribes to the same trigger_types as an HTTP webhook, so every event becomes 1 message on the topic with an identical payload; only the delivery target changes.

If you’re on Google Cloud instead of AWS, use a Pub/Sub channel, which works the same way against a Google Cloud topic. See SNS notification channels for the IAM setup.

What’s next

• SNS notification channels for the full IAM and topic setup
• Receive notifications with Pub/Sub for the Google Cloud equivalent
• Get real-time updates with webhooks for the HTTPS webhook alternative
• Webhook notification schemas for every trigger’s payload