# Reducing payload size with compression

Source: https://developer.nylas.com/docs/dev-guide/best-practices/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.

> **Success:** 
> **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:

```bash
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`:

```bash
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:

```bash
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"
```

> **Info:** 
> **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.

> **Warn:** 
> **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](/docs/v3/notifications/#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](/docs/v3/notifications/pubsub-channel/#compressed-pubsub-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.

> **Success:** 
> **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](/docs/v3/notifications/sns-channel/#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](/docs/v3/notifications/#specify-fields-for-webhook-notifications).

## Related resources

- [Compressed webhook notifications](/docs/v3/notifications/#compressed-webhook-notifications)
- [Compressed Pub/Sub notifications](/docs/v3/notifications/pubsub-channel/#compressed-pubsub-notifications)
- [Compressed SNS notifications](/docs/v3/notifications/sns-channel/#compressed-sns-notifications)
- [Specify fields for webhook notifications](/docs/v3/notifications/#specify-fields-for-webhook-notifications)
- [Truncated webhook notifications](/docs/v3/notifications/#truncated-webhook-notifications)
- [Best practices for webhooks](/docs/dev-guide/best-practices/webhook-best-practices/)