API
Read, organize and send mail from the mailboxes you belong to.
These routes act only on mailboxes the signed-in person is a member of; keys get no mailboxes. See Mail.
Every route below, with its parameters, request and response, errors and samples, is in the API reference.
| Route | What it does |
|---|---|
GET /v1/orgs/:orgId/mail/mailboxes | The mailboxes the caller is a member of, with their aliases and signature. Keys get an empty list. |
GET /v1/orgs/:orgId/mail/preferences | The caller's Mail preferences in the organization: categories (the inbox's category bar on or off) and push per mailbox (all, primary or off; primary unless changed). |
PATCH /v1/orgs/:orgId/mail/preferences | Changes the caller's Mail preferences: categories, and push for any of their mailboxes. |
GET /v1/orgs/:orgId/mail/threads | All Mailboxes: one page of a view (inbox, starred, sent, drafts) across every mailbox the caller reads in the organization, newest first; each row names its mailboxId. In the inbox, category narrows it. With q, search results across those mailboxes (outside Spam and Trash, whatever the view), paged the same way. The cursor holds one position per mailbox, so pages merge without gaps or repeats; a page can be short while cursor is set. |
GET /v1/orgs/:orgId/mail/counts | Unread inbox conversations per category across the caller's mailboxes in the organization (counts) and for each (mailboxes), and badge: unread Primary conversations in the mailboxes they get push for, in every organization they belong to (what the Mail app shows on its icon). |
PATCH /v1/orgs/:orgId/mail/mailboxes/:mailboxId/settings | Sets the mailbox's signature. |
GET /v1/orgs/:orgId/mail/mailboxes/:mailboxId/limits | The organization's sending limits: messages per day, message size and recipients per message. |
GET /v1/orgs/:orgId/mail/mailboxes/:mailboxId/threads | One page of conversations in a view (inbox, starred, sent, drafts, archive, all, spam, trash, or label with label), newest first, optionally matching q. In the inbox, category (primary, transactions, updates, promotions) narrows it to one category. Each row has its category and sender. Pass cursor to continue. |
GET /v1/orgs/:orgId/mail/mailboxes/:mailboxId/counts | Unread conversations in the mailbox's inbox per category; complete is false when the inbox was too large to count whole. |
PUT /v1/orgs/:orgId/mail/mailboxes/:mailboxId/senders/:address/category | Moves a sender's mail to a category: remembered for the mailbox's later mail from them, and applied now to threadId and the sender's other conversations in the inbox. Returns how many moved. |
POST /v1/orgs/:orgId/mail/mailboxes/:mailboxId/threads/actions | Applies one action to up to 100 conversations: archive, move to inbox, trash, spam, not spam, delete (from trash or spam only), read, unread, star, unstar, label or unlabel. |
GET /v1/orgs/:orgId/mail/mailboxes/:mailboxId/threads/:threadId | A conversation and its messages, without bodies. |
GET /v1/orgs/:orgId/mail/mailboxes/:mailboxId/threads/:threadId/messages/:messageId/body | A message's text and HTML, with short-lived links for inline images. Reading a received message marks it read. |
GET /v1/orgs/:orgId/mail/mailboxes/:mailboxId/threads/:threadId/messages/:messageId/attachments/:index | A short-lived download link for an attachment. |
GET /v1/orgs/:orgId/mail/mailboxes/:mailboxId/threads/:threadId/messages/:messageId/raw | A short-lived link to the original message (.eml). |
POST /v1/orgs/:orgId/mail/mailboxes/:mailboxId/threads/:threadId/messages/:messageId/unsubscribe | Leaves the mailing list a message came from: one-click (RFC 8058) when the sender offers it, else an unsubscribe email from this mailbox; otherwise the link for the reader to open. |
GET /v1/orgs/:orgId/mail/mailboxes/:mailboxId/threads/:threadId/messages/:messageId/invitation | The meeting a message carries and the event it became in this mailbox's calendars. |
POST /v1/orgs/:orgId/mail/mailboxes/:mailboxId/uploads | Compose attachments go straight to the bucket; the link only accepts the declared size and type. |
POST /v1/orgs/:orgId/mail/mailboxes/:mailboxId/send | Sends a message from the mailbox and files it in Sent. The domain must be verified. With replyTo, it's threaded as a reply; with draftId, the draft is removed. The response lists recipients that bounced or complained before. |
POST /v1/orgs/:orgId/mail/mailboxes/:mailboxId/recipients/check | Recipients that bounced or complained before, so compose can warn. |
GET /v1/orgs/:orgId/mail/mailboxes/:mailboxId/recipients/suggest | Address suggestions for compose and guest fields: the organization's people (their own mailboxes, by name), then contacts, then recent correspondents. |
POST /v1/orgs/:orgId/mail/mailboxes/:mailboxId/drafts | Saves a new draft. |
GET /v1/orgs/:orgId/mail/mailboxes/:mailboxId/drafts/:draftId | A draft, for editing. |
PUT /v1/orgs/:orgId/mail/mailboxes/:mailboxId/drafts/:draftId | Replaces a draft. |
DELETE /v1/orgs/:orgId/mail/mailboxes/:mailboxId/drafts/:draftId/schedule | Takes a scheduled draft off the schedule (it stays a draft). |
DELETE /v1/orgs/:orgId/mail/mailboxes/:mailboxId/drafts/:draftId | Discards a draft. |
GET /v1/orgs/:orgId/mail/mailboxes/:mailboxId/filters | Inbound filters: conditions on received mail, actions on its conversation. |
POST /v1/orgs/:orgId/mail/mailboxes/:mailboxId/filters | Creates an inbound filter: conditions on received mail (all must match), actions on its conversation. At most 100 per mailbox. |
PUT /v1/orgs/:orgId/mail/mailboxes/:mailboxId/filters/:filterId | Replaces a filter's conditions and actions, or turns it on or off. |
POST /v1/orgs/:orgId/mail/mailboxes/:mailboxId/filters/:filterId/apply | Runs a filter over conversations already in the mailbox (a few seconds here, the rest in the background). |
GET /v1/orgs/:orgId/mail/mailboxes/:mailboxId/forwarding | Forwarding addresses (filter action): added pending, confirmed with the code mailed to them. |
POST /v1/orgs/:orgId/mail/mailboxes/:mailboxId/forwarding | Adds a forwarding address (or sends a new code to a pending one): the address gets a 6-digit code by email, valid 24 hours. Needs the mailbox's domain to be active; counts toward the daily sending limit. |
POST /v1/orgs/:orgId/mail/mailboxes/:mailboxId/forwarding/verify | Confirms a forwarding address with the code it received; filters can then forward to it. Five wrong codes need a new one. |
DELETE /v1/orgs/:orgId/mail/mailboxes/:mailboxId/forwarding/:address | Removes a forwarding address; filters forwarding to it stop forwarding. |
DELETE /v1/orgs/:orgId/mail/mailboxes/:mailboxId/filters/:filterId | Deletes a filter. Mail already filed stays where it is. |
GET /v1/orgs/:orgId/mail/mailboxes/:mailboxId/labels | The mailbox's labels, by name. |
POST /v1/orgs/:orgId/mail/mailboxes/:mailboxId/labels | Creates a label. Names are unique in the mailbox, ignoring case. |
DELETE /v1/orgs/:orgId/mail/mailboxes/:mailboxId/labels/:labelId | Deletes a label. Conversations stop showing it. |
GET /v1/me/mail/mailboxes | The caller's mailboxes in every organization where they read mail, each with its orgId and aliases, and those organizations (orgs: orgId, slug, name). |
GET /v1/me/mail/threads | All Inboxes across organizations: one page of a view (inbox, starred, sent, drafts) across every mailbox the caller reads in every organization, newest first; each row names its mailboxId and orgId, and actions on it go to that organization's mailbox routes. In the inbox, category narrows it; with q, search results across them (outside Spam and Trash). Access is checked on every page: a mailbox the caller loses stops appearing, and one they gain starts below the rows already returned. The cursor holds one position per mailbox and the last row returned. |
GET /v1/me/mail/counts | Unread inbox conversations per category across the caller's mailboxes in every organization (counts) and for each (mailboxes), and badge: unread Primary conversations in the mailboxes they get push for. |