# What is an email API?

Source: https://developer.nylas.com/docs/cookbook/email/what-is-an-email-api/

You want your app to send a confirmation, read the reply, and keep both in the same conversation. The old way means stitching SMTP for outbound, IMAP for inbound, a MIME parser in the middle, and a fresh round of OAuth for every provider you support. That's four moving parts before you write a line of product code, and each one breaks differently.

An email API replaces that stack with HTTPS calls and JSON. You send with one request, read with another, and the same integration works whether the mailbox lives on Gmail, Outlook, or a self-hosted IMAP server. This page defines what an email API is, what it does, how it differs from the raw protocols, and where to go deeper.

## What is an email API and how does it work for sending and receiving email?

An email API is an HTTP interface that sends, reads, parses, and syncs email through JSON requests instead of raw mail protocols. You send a `POST` to deliver a message and a `GET` to list an inbox, both over HTTPS on port 443. The API holds the provider connection, runs OAuth, and returns structured JSON for the full lifecycle.

Internally, the API does the protocol work you'd otherwise own. To send, it routes your `POST /v3/grants/{grant_id}/messages/send` through the connected provider's outbound servers, so deliverability inherits that mailbox's warmed reputation. To read, it syncs the mailbox and exposes messages through `GET /v3/grants/{grant_id}/messages`, already parsed into fields like `subject`, `from`, `body`, and `thread_id`. Real-time changes arrive through webhooks: register an endpoint at `/v3/webhooks`, and a `message.created` event fires when new mail lands, with [payloads capped at 1 MB](/docs/v3/notifications/#truncated-webhook-notifications). That's send, read, parse, and sync behind four HTTPS surfaces instead of three separate protocols.

## How does an email API differ from SMTP and IMAP?

SMTP and IMAP are single-purpose transport protocols: SMTP only sends mail, IMAP only reads it, and neither returns JSON or handles OAuth. An email API sits one layer above both. It wraps sending, reading, and parsing behind HTTPS endpoints, returns structured JSON, and manages authentication, so a single integration covers what SMTP and IMAP do separately.

The protocols themselves are decades old. SMTP, defined in RFC 5321, handles the outbound hop and stops there. IMAP (RFC 3501) is a stateful, socket-level protocol that has read one mailbox at a time since the 1990s. To build a two-way feature with raw protocols, you open TCP connections, parse `FETCH` responses by hand, assemble MIME strings to send, and store per-mailbox credentials. Cloud hosts complicate this further: AWS and Google Compute Engine block outbound port 25 by default to curb spam. An email API runs over HTTPS on 443, which is never blocked, and collapses both protocols into one schema. For the full breakdown, see [SMTP vs a REST email API](/docs/cookbook/email/smtp-vs-rest-api/) and [IMAP vs an email API](/docs/cookbook/email/imap-vs-email-api/).

## SMTP, IMAP, and a unified email API compared

The table below compares raw SMTP and IMAP against a unified email API across the dimensions that decide an integration: direction, transport, auth, and provider coverage. The protocols win on simplicity for one narrow job each. A unified API wins anywhere the app needs structure, two-way mail, or more than one provider.

| Dimension | SMTP | IMAP | **Unified email API** |
| --- | --- | --- | --- |
| **Direction** | Send only | Read only | **Send, read, and sync** |
| **Transport** | TCP 25 / 587 / 465 | TCP 143 / 993 | **HTTPS on 443, never blocked** |
| **Response format** | Numeric reply codes | Untyped `FETCH` data | **Structured JSON** |
| **Auth** | Per-mailbox password | Per-mailbox password | **OAuth through `/v3/connect/auth`** |
| **Real-time updates** | None | `IDLE` polling | **Webhooks at `/v3/webhooks`** |
| **Multi-provider** | Per-host config | Per-host config | **One schema across 6 providers** |

## What does a unified multi-provider email API mean?

A unified email API puts one schema and one OAuth flow in front of every provider, so you write your integration once and reach all of them. Connect a Gmail, Microsoft 365, Yahoo, iCloud, generic IMAP, or Exchange account, and each returns the same JSON shape. You read every mailbox through `GET /v3/grants/{grant_id}/messages` regardless of what's behind it.

The alternative is one integration per provider. Gmail uses the Gmail API with `users.messages.list`; Microsoft uses Graph with `GET /me/messages`. Each has its own OAuth project, ID format, rate limits, and quirks, so supporting two providers means maintaining two unrelated codebases. A unified layer collapses that into a single code path. The connection is represented by a `grant`, an authenticated account you reference by `grant_id` on every call, so adding iCloud or Exchange later costs no new integration. See the [unified inbox guide](/docs/cookbook/email/unified-inbox/) for how a single feed merges multiple accounts.

## What APIs can help me integrate email services into my application?

Three categories of API cover email integration. Transactional APIs (like SendGrid or Postmark) send app-generated mail at volume but don't read inboxes. Provider APIs (Gmail API, Microsoft Graph) give deep single-provider access. A unified email API like the Nylas Email API sends and reads across all 6 providers through one schema, which fits apps that work with users' own mailboxes.

The right pick depends on direction and provider count. If you only blast one-way notifications and never read replies, a transactional sender is enough and lighter to run. If your product lives entirely inside one ecosystem and needs provider-only surfaces like Teams or Drive, the native API is the only option. The moment you read users' mail across more than one provider, the unified model removes the per-provider OAuth, ID mapping, and retry logic. The send call below delivers a message from a connected account through `POST /v3/grants/{grant_id}/messages/send`, routing it through that mailbox's own infrastructure across all 6 supported providers.

```bash
curl --request POST \
  --url 'https://api.us.nylas.com/v3/grants/<NYLAS_GRANT_ID>/messages/send' \
  --header 'Authorization: Bearer <NYLAS_API_KEY>' \
  --header 'Content-Type: application/json' \
  --data '{
    "to": [{ "name": "Leyah Miller", "email": "leyah@example.com" }],
    "subject": "Your account is ready",
    "body": "Welcome aboard. Your workspace is set up and waiting."
  }'
```

## Which email API is best for developers building SaaS applications?

The best email API for a SaaS app depends on whether you touch users' own mailboxes. If your product reads and sends from customer inboxes across Gmail, Outlook, and others, a unified API across all 6 providers fits best because one OAuth flow covers every customer. If you only send app-generated mail one direction, a transactional sender is the right call.

For SaaS that reads customer mail, the operational wins compound. The read call below lists the 20 most recent unread messages from a connected inbox through `GET /v3/grants/{grant_id}/messages`, returning the same JSON whether the mailbox is Google or Exchange. It accepts `subject`, `from`, `unread`, `received_after`, and `thread_id` as query parameters, so you filter without parsing raw headers. To thread a reply into an existing conversation, pass `reply_to_message_id` on the send call, and the API sets the `In-Reply-To` and `References` headers for that provider.

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

The honest tradeoff: if you genuinely send one-way mail to one provider and never read a reply, wiring up a unified API with OAuth grants is more than the job needs. A plain SMTP relay or a transactional sender is the lighter choice there. The unified model earns its place once you read inboxes, support more than one provider, or need webhooks for real-time updates.


> **Info:** 
> **New to Nylas?** Start with the [quickstart guide](/docs/v3/getting-started/) to set up your app and connect a test account before continuing here.


## What's next

- [SMTP vs a REST email API](/docs/cookbook/email/smtp-vs-rest-api/) to compare the sending side protocol by protocol
- [IMAP vs an email API](/docs/cookbook/email/imap-vs-email-api/) to compare the reading side in depth
- [Build a unified inbox](/docs/cookbook/email/unified-inbox/) to merge multiple provider accounts into one feed
- [Getting started with Nylas](/docs/v3/getting-started/) to create a project, connector, and your first grant