# Email API security & compliance

Source: https://developer.nylas.com/docs/cookbook/use-cases/industries/email-api-compliance/

A security review can stall an email integration for weeks. The reviewer wants to know exactly which mailboxes your app can touch, how you prove a webhook came from the API and not an attacker, where the data lives, and how a customer cuts off access the day they offboard. Answer those questions with vague assurances and the deal slips a quarter.

This page maps each of those requirements to a concrete primitive you can point a security team at: scoped OAuth through `/v3/connect/auth`, revocable grants, HMAC-signed webhooks, encryption in transit and at rest, and the data-residency choice between the US and EU regions. Where a compliance posture depends on your own Nylas plan and contract, this says so plainly instead of overpromising.

## What does a secure email API need for enterprise compliance?

A secure email API needs five controls a reviewer will ask about by name: scoped OAuth so the integration requests only the permissions it uses, revocable access so a customer can sever the connection on demand, signed webhooks so forged events can't reach your handler, TLS in transit with encryption at rest, and a documented data-residency region. Each maps to a verifiable endpoint or setting below.

The API handles the provider-side OAuth dance for Google, Microsoft, Yahoo, iCloud, IMAP, and Exchange behind one flow, so you implement these controls once instead of per provider. That matters when a security questionnaire asks the same six questions for every mailbox source. A single connector and one signing model covers all of them, which collapses a multi-week per-provider review into one conversation. The table later in this page lines up each requirement against the primitive that satisfies it.

## How do I ensure email integration security across multiple enterprise customers?

Isolate every customer behind a grant, the per-account credential the API issues after OAuth. Each grant carries its own token to a single mailbox, so one customer's grant can never read another's inbox, and `GET /v3/grants` lists exactly which accounts your application can reach. When a customer offboards, you delete their grant alone and the other connections stay live.

Multi-tenant email integration fails when one leaked token exposes every customer, so the boundary has to sit at the account, not the application. A grant is that boundary: requests run as `/v3/grants/{grant_id}/messages`, and the `grant_id` scopes the call to one mailbox. Store each `grant_id` against your own tenant record, never in client-side code. For the storage pattern, the [store OAuth credentials securely](/docs/cookbook/use-cases/build/store-oauth-credentials/) guide covers encrypting tokens at rest and keeping the `grant_id` out of logs. To fully offboard a customer, delete the grant with `DELETE /v3/grants/{grant_id}`; to invalidate active tokens without removing the connection, `POST /v3/connect/revoke` revokes the access token and all child tokens in one call.

```bash
curl --request GET \
  --url 'https://api.us.nylas.com/v3/grants?limit=50' \
  --header 'Authorization: Bearer <NYLAS_API_KEY>'
```

## What are the best practices for enterprise-grade email authentication?

Enterprise-grade email authentication means OAuth 2.0 with the narrowest scopes the integration needs, no stored passwords, and a clean revocation path. Microsoft deprecated basic authentication for all Exchange Online accounts on October 1, 2022, so OAuth is the only supported path for Microsoft 365 anyway. Request read-only scopes when you only read mail, and add write scopes solely when you send.

The hosted auth flow starts at `GET /v3/connect/auth`, where you pass a `provider`, a `redirect_uri`, and the OAuth scopes the integration requires. Requesting `Mail.Read` instead of full mailbox access is the single change that most often clears a least-privilege review, because the consent screen the customer sees lists only what you asked for. The [hosted OAuth documentation](/docs/v3/auth/hosted-oauth-accesstoken/) details the authorization code flow and optional PKCE for client-side apps. Build the authorization URL, then redirect the user to it.

```bash
curl --request GET \
  --url 'https://api.us.nylas.com/v3/connect/auth?client_id=<NYLAS_CLIENT_ID>&redirect_uri=https%3A%2F%2Fyourapp.com%2Fcallback&response_type=code&provider=google'
```

## Encryption in transit and at rest

Every request to the API travels over TLS, and the base URL `https://api.us.nylas.com` rejects plain HTTP, so credentials and message bodies are never exposed on the wire. Webhook destinations must also use an HTTPS `webhook_url`, which encrypts both the notification body and its signature in transit. At rest, stored mailbox data and tokens are encrypted on the platform side.

Transport encryption only protects data while it moves, so the at-rest side matters just as much for a compliance review. On your end, encrypt the tokens you persist and never write a `grant_id` or access token to application logs, where a 30-day log retention window can quietly extend a token's blast radius. Confirm the current at-rest encryption and key-management details for your plan with your Nylas account team, since the exact guarantees depend on your contract rather than a single fixed setting.

## Audit logging and proving event authenticity

The API signs every webhook with an HMAC-SHA256 digest in the `x-nylas-signature` header, a 64-character hex string computed from the raw request body using a `webhook_secret` only your endpoint and the platform share. Recompute it and compare in constant time, and a forged `message.created` never reaches your business logic. That signature is your tamper-evidence for inbound events.

For an audit trail a reviewer accepts, log the verification result, not the payload, and never the secret. Rotate the secret through `POST /v3/webhooks/rotate-secret/{id}` if it leaks. The full constant-time check, including the gzip-body gotcha that breaks most first attempts, lives in the [verify webhook signatures](/docs/cookbook/use-cases/build/verify-webhook-signatures/) guide. Pair signing with HTTPS and a source-address allowlist for defense in depth, and you can show a clear chain from event received to event trusted.

## Data residency and SOC 2 / HIPAA posture

The API offers two data regions: the US region at `https://api.us.nylas.com` and the EU region at `https://api.eu.nylas.com`. Choosing the EU region keeps connected mailbox data inside the EU, which answers the data-residency question many enterprise and public-sector buyers raise first. You pick the region when you create your application, and the base URL in every request reflects that choice.

SOC 2 and HIPAA posture depends on your specific plan and a signed agreement, so treat any blanket claim with skepticism. The honest answer for a buyer: confirm the current certification scope and request a SOC 2 report or a Business Associate Agreement directly through your account team, then map the controls on this page to your own requirements. The [Nylas Trust Center](https://www.nylas.com/security/) publishes the current security and compliance program. Don't repeat a compliance claim you can't back with a document the customer can read.

## Security primitive to requirement map

This table lines up each enterprise requirement with the verified primitive that satisfies it, so you can hand a reviewer a single reference instead of stitching answers together across six provider integrations. The unified column is the path you implement once and reuse across Google, Microsoft, Yahoo, iCloud, IMAP, and Exchange.

| Requirement | Build it yourself, per provider | **Unified Nylas primitive** |
| --- | --- | --- |
| **Scoped access** | Per-provider OAuth apps and scope mapping | **`/v3/connect/auth` with requested scopes** |
| **Revocable access** | Provider-specific token revocation calls | **`/v3/connect/revoke` and per-grant deletion** |
| **Event authenticity** | Custom signing per webhook source | **HMAC-SHA256 `x-nylas-signature`** |
| **Tenant isolation** | Map tokens to tenants by hand | **One `grant_id` per customer mailbox** |
| **Data residency** | Self-host per region | **US or EU region base URL** |

The build-it-yourself column isn't wrong for every team. If you support one provider and one region and want full control of token storage and key rotation, calling Gmail API or Microsoft Graph directly removes a dependency. The tradeoff shows the moment you add a second provider: you repeat the OAuth app, the scope review, and the signing model from scratch, and your security questionnaire doubles.

## What's next

- [Store OAuth credentials securely](/docs/cookbook/use-cases/build/store-oauth-credentials/) for encrypting tokens and keeping the `grant_id` out of logs
- [List and revoke grants](/docs/cookbook/use-cases/build/list-revoke-grants/) to audit and sever customer access on demand
- [Verify webhook signatures](/docs/cookbook/use-cases/build/verify-webhook-signatures/) for the constant-time HMAC check and the gzip body gotcha
- [Getting started with Nylas](/docs/v3/getting-started/) to create a project, connector, and your first scoped grant