Reducing payload size with compression

Large JSON payloads cost bandwidth, slow your application down, and, when email bodies contain HTML, sometimes get blocked by firewalls and WAFs before they reach your code. Nylas supports gzip compression on API responses, webhooks, and Pub/Sub and SNS notification channels, along with field selection to strip fields you don’t need. We recommend enabling compression on every surface that supports it.

Why compress?

• Smaller payloads, faster transfers. Gzip typically shrinks JSON bodies by 70 to 90%, which directly reduces bandwidth costs and time-to-first-byte for your application.
• Fewer firewall false positives. Some firewalls and WAFs inspect request bodies and block content that contains HTML tags. Email message notifications often include HTML in the message body, which can trigger those rules. Compressed payloads are opaque binary data and pass through without being flagged.
• Avoid SNS truncation. Amazon SNS has a 256 KB message size limit. Compressed delivery keeps large notifications within that limit so your project receives the full object instead of a truncated one.

Nylas recommends enabling compression on every surface that supports it, including API responses, webhooks, and Pub/Sub or SNS channels. The only thing you need to add is decompression logic in your handler. The bandwidth and reliability wins are substantial, especially if your application processes a lot of message.* notifications.

Compress API responses

The Email, Calendar, Contacts, and Scheduler APIs return gzip-compressed responses when your request includes the Accept-Encoding: gzip header. Most HTTP libraries negotiate this automatically and decompress the response for you.

With curl, use --compressed to advertise support and decompress transparently:

curl --compressed \
  -H "Authorization: Bearer <NYLAS_API_KEY>" \
  "https://api.us.nylas.com/v3/grants/<GRANT_ID>/messages?limit=50"

If you want to see the raw compressed bytes, set the header explicitly and pipe to gunzip:

curl -H "Accept-Encoding: gzip" \
     -H "Authorization: Bearer <NYLAS_API_KEY>" \
  "https://api.us.nylas.com/v3/grants/<GRANT_ID>/messages?limit=50" \
  | gunzip

Nylas skips compression for very small responses (under about 200 bytes) because the overhead outweighs the savings. You’ll see this on error responses and single-object endpoints, and it’s expected behavior.

Compression pairs well with query parameters that shrink the payload before it’s compressed. Use limit to cap list sizes and select to return only the fields you need:

curl --compressed \
  -H "Authorization: Bearer <NYLAS_API_KEY>" \
  "https://api.us.nylas.com/v3/grants/<GRANT_ID>/messages?select=id,subject,from,date&limit=100"

Response compression applies to the Email, Calendar, Contacts, and Scheduler APIs. Administration endpoints, including grants, connectors, credentials, API keys, and auth, currently return uncompressed responses regardless of the Accept-Encoding header.

Compress webhook notifications

Set compressed_delivery to true when you create or update a webhook destination, and Nylas gzip-compresses each notification payload before sending the POST request to your endpoint. Nylas adds the Content-Encoding: gzip header so your handler knows to decompress.

The X-Nylas-Signature header is computed over the compressed bytes. Verify the signature against the raw request body before decompressing. If you decompress first and then check the signature, verification fails.

For the full walkthrough, including the request payload and signature validation pattern, see Compressed webhook notifications.

Compress Pub/Sub channel notifications

On Pub/Sub channels, set compressed_delivery to true and Nylas gzip-compresses each notification payload before publishing it to your topic. Nylas adds a content_encoding: gzip message attribute so your subscriber knows which messages to decompress.

See Compressed Pub/Sub notifications for setup details.

Compress SNS channel notifications

SNS has a hard 256 KB limit on message size, and Nylas strips message bodies from any payload that would exceed it. Enabling compressed_delivery on an SNS channel gzip-compresses the payload and then base64-encodes it (SNS messages must be valid UTF-8), and Nylas tags the message with a content_encoding: gzip+base64 attribute.

We strongly recommend enabling compressed delivery on SNS channels. It’s the single biggest lever for keeping large message.* notifications under the 256 KB limit. See Compressed SNS notifications for the decode pattern.

Reduce payload size before compression

Compression shrinks what you send. Field selection controls what goes into the payload in the first place, and the two stack well.

For the message.created, message.updated, event.created, and event.updated webhook triggers, you can configure which fields Nylas includes in notifications from the Customizations section of the Nylas Dashboard. When Nylas sends a customized notification it adds the .transformed suffix to the trigger type (for example, message.updated.transformed), so make sure your handler accepts that type.

The .transformed suffix can also combine with .cleaned and .truncated, producing trigger types like message.created.cleaned.transformed or message.created.transformed.truncated. Your handler should match on prefix rather than exact string.

For the full walkthrough, see Specify fields for webhook notifications.

Related resources

• Compressed webhook notifications
• Compressed Pub/Sub notifications
• Compressed SNS notifications
• Specify fields for webhook notifications
• Truncated webhook notifications
• Best practices for webhooks