# IMAP vs REST email API Source: https://developer.nylas.com/docs/cookbook/email/imap-vs-rest-email-api/ IMAP has moved email since 1986. It's reliable and universal, and it's a poor fit for a modern multi-tenant app: one long-lived connection per mailbox, no built-in webhooks, and a raw MIME payload you parse yourself. A REST email API wraps that complexity behind HTTP. You make a request, you get JSON, and one integration covers every provider. Here's how the two compare for reading messages, and when each one is the right call. > **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. ## How do IMAP and REST email APIs differ? IMAP is a mail-access protocol: your code opens a socket connection to each mailbox over port 993, issues fetch commands, and receives raw MIME messages to parse. A REST email API exposes the same mailboxes over HTTPS and returns parsed JSON. IMAP keeps one connection per account; REST uses stateless requests that fan out across all 5 provider families. The table below maps the practical differences for a team reading email from many users. | Dimension | IMAP (direct) | REST email API | | --- | --- | --- | | Transport | Socket connection on port 993 | HTTPS requests and responses | | Connection model | One persistent session per mailbox | Stateless, pooled requests | | Providers | One IMAP dialect per server | One schema across Gmail, Outlook, Yahoo, iCloud, IMAP | | Message format | Raw MIME you decode | Parsed JSON fields | | Real-time updates | `IDLE` command holds a connection open | Push webhooks | | Auth | Username and password or app password | OAuth handled by the API | Both read the same mailboxes. The difference is how much protocol work lands in your codebase. ## When should you use IMAP directly? Talking IMAP directly makes sense when you integrate one mailbox or a single mail server you control, want zero third-party dependencies, and can handle MIME parsing and connection management yourself. It's also the only path for niche servers that expose nothing but IMAP and no REST layer. The cost is operational. You manage one open socket per account on port 993, handle app-specific passwords for mailboxes with 2-factor authentication, and decode every MIME part by hand. For a single internal inbox that's fine. Across 200 users it becomes a connection pool and a parser you maintain forever, since each of those 200 mailboxes needs its own session. ## When should you use a REST email API? A REST email API fits when you connect mailboxes from many users and providers, want push webhooks instead of polling, and would rather not maintain MIME parsing or OAuth flows. One schema covers 5 provider families, so Gmail labels and Outlook categories surface through the same fields instead of provider-specific code paths. This is the common choice for SaaS products that read customer email at scale. You get parsed messages, server-side search, and OAuth token refresh without writing any of it. To see the exact fields a request returns, read the [read and parse email guide](/docs/cookbook/email/read-parse-incoming-email/), or merge several accounts into a [unified inbox](/docs/cookbook/email/unified-inbox/). ## How does a REST email API read messages? Reading mail over REST is a single GET request. The `/v3/grants/{grant_id}/messages` endpoint returns recent messages as parsed JSON, with no IMAP session or fetch command involved. The call below pulls the 5 most recent messages; the response arrives with `from`, `subject`, and `body` already decoded. ```bash curl --compressed --request GET \ --url "https://api.us.nylas.com/v3/grants//messages?limit=5" \ --header 'Accept: application/json' \ --header 'Authorization: Bearer ' \ --header 'Content-Type: application/json' ``` ```json { "request_id": "d0c951b9-61db-4daa-ab19-cd44afeeabac", "data": [ { "starred": false, "unread": true, "folders": ["UNREAD", "CATEGORY_PERSONAL", "INBOX"], "grant_id": "1", "date": 1706811644, "attachments": [ { "id": "1", "grant_id": "1", "filename": "invite.ics", "size": 2504, "content_type": "text/calendar; charset=\"UTF-8\"; method=REQUEST" }, { "id": "2", "grant_id": "1", "filename": "invite.ics", "size": 2504, "content_type": "application/ics; name=\"invite.ics\"", "is_inline": false, "content_disposition": "attachment; filename=\"invite.ics\"" } ], "from": [ { "name": "Nylas DevRel", "email": "nylasdev@nylas.com" } ], "id": "1", "object": "message", "snippet": "Send Email with Nylas APIs", "subject": "Learn how to Send Email with Nylas APIs", "thread_id": "1", "to": [ { "name": "Nyla", "email": "nyla@nylas.com" } ], "created_at": 1706811644, "body": "Learn how to send emails using the Nylas APIs!" } ], "next_cursor": "123" } ``` For Node.js and Python versions of this request, see the [read and parse email guide](/docs/cookbook/email/read-parse-incoming-email/). The endpoint returns 50 messages by default and up to 200 per page. ## How do you get real-time email updates? IMAP signals new mail with the `IDLE` command, which holds a connection open per mailbox and drops on network hiccups, so you re-establish and re-sync. A REST email API delivers new-message events as webhooks: the provider notifies the API, and the API posts JSON to your endpoint. Webhooks scale to thousands of accounts without persistent connections, which is the practical reason most multi-account apps avoid `IDLE`. You register 1 endpoint, then receive 1 `message.created` event per arriving message, no matter how many mailboxes you watch. The [new email webhook guide](/docs/cookbook/use-cases/build/new-email-webhook/) walks through wiring that up end to end. ## Things to know about IMAP through a REST API When you connect a generic IMAP account through a REST API, several IMAP traits still apply. Accounts with 2-factor authentication need an app-specific password, the server defines folder names rather than standardizing them, and there's an initial sync window before older mail is searchable. The Nylas API caches the most recent 90 days of IMAP mail and reaches older messages on request with `query_imap=true`, which is slower because it queries the server live. The [list IMAP messages guide](/docs/cookbook/email/messages/list-messages-imap/) covers that cache, folder handling, and provider quirks in detail. ## Does a REST email API work with every IMAP server? Most of them, because IMAP is a standard protocol. A REST email API connects to any server that speaks standard IMAP, which covers hosted IMAP providers and self-hosted mail servers alike, then exposes them through the same endpoints as Gmail and Outlook. The connection uses the server host, port 993, and the account credentials. The trade-off is search and history. Behind a REST API, a generic IMAP account syncs a rolling window of 90 days, and older mail is reachable on request. The [list IMAP messages guide](/docs/cookbook/email/messages/list-messages-imap/) covers that window and the `query_imap` flag that reaches the full mailbox when you need older messages. ## How does authentication differ between app passwords and OAuth? IMAP and REST authenticate connected accounts in different ways. Generic IMAP accounts with 2-factor authentication need an app-specific password that the user generates in their account security settings. Gmail and Microsoft accounts instead use OAuth, where the user grants access once and the token refreshes automatically, typically after 3,600 seconds, with no password to store. The difference shows up at onboarding. An OAuth provider gives you a consent screen and revocable access; a generic IMAP server gives you a credential you store and rotate yourself. A REST email API hides both behind one grant, so your app reads mail the same way no matter which authentication a provider uses. ## FAQ ### Is a REST email API slower than direct IMAP? For a single mailbox on a fast connection, raw IMAP can be marginally quicker because nothing sits in the middle. At scale the comparison flips: a REST API reads from a synced cache and parallelizes across accounts, while IMAP serializes commands over 1 connection per mailbox. ### Can I get real-time updates without an open IMAP connection? Yes. A REST email API delivers new-message events as webhooks, so you skip the `IDLE` command and its persistent connection. You register 1 endpoint and receive a `message.created` event when mail arrives, even across thousands of accounts. ### Does the API keep an IMAP connection open for me? The API manages the connection to the IMAP server on your behalf, including reconnects and sync. Your code only makes HTTPS requests, so you never manage a socket, an `IDLE` loop, or a reconnect strategy. ## What's next - [Read and parse incoming email](/docs/cookbook/email/read-parse-incoming-email/) for the full message fields and language samples. - [List IMAP messages](/docs/cookbook/email/messages/list-messages-imap/) to connect a generic IMAP or custom mail server. - [Send a new email webhook](/docs/cookbook/use-cases/build/new-email-webhook/) to replace IMAP polling with push events. - [Messages API reference](/docs/reference/api/messages/) for every query parameter and response field.