Mail over MCP and the API

A person reads and answers their own mailbox from an agent over the enterprise's MCP server, or from code over the API. A member's mailbox is read over the API, and worked by its own tasks.

What there is

Mail can be reached from outside the portal in three ways. Each one only ever reaches the mailbox it belongs to:

From Whose mailbox How
An MCP client Your own, as a person The os.my_mail_* tools on the enterprise's MCP server
Code, as you Your own, as a person /v1/mail and the routes under it, with your session or a token of your own
Code, with a token A member's, to read /v1/members/{id}/emails and the routes under it, with members:read

A member's own tasks reach its mailbox with the built-in mail tools instead: see Mail in tasks.

This page says what each family is for and who may use it. The exact fields, answers and errors of every tool are in the generated MCP tool reference, and every route with the scope it needs is on Endpoints.

Your mailbox over MCP

Connect the enterprise's MCP server from Claude, ChatGPT or any MCP client by signing in, and choose what the app may do with mail on the consent screen (Connected apps). Account shows the server address to paste and the apps you have connected, each with Disconnect.

  • Read gives the app your inbox, one message with its text and formatting, the files on a message, your contacts, your signatures and extra addresses, and the one-click buttons your inbox offers.
  • Write adds replying, forwarding and sending, deleting, filing (labels, handled states, many messages at once), pressing a button or putting it on a cadence, saving and removing contacts, and setting your signatures.

For example, os.my_mail_list lists your mail and os.my_mail_read opens one message; os.my_mail_send, os.my_mail_reply and os.my_mail_forward send, and each takes the body as markdown, attachments by link, by a file already in your mailbox or as bytes, and signature: false to go unsigned (Writing mail). Nothing you send waits for approval: it is your own mail.

Your mailbox over the API

The same mailbox is /v1/mail for a person signed in, or for a token of their own: GET /v1/mail lists it with the same filters and a free-text search, GET /v1/mail/{id} opens a message, and the routes under it reply, forward, delete, file and download attachments, a file as JSON up to 4 MB. POST /v1/mail sends a new message. Contacts, signatures, extra addresses' signatures and the one-click buttons each have routes under /v1/mail too. A change on many messages at once takes up to 200 of them.

A body given both as markdown and as text or html is refused with mail_body_conflict. Attachments over the limits are refused whole, with attachments_over_limit, and nothing is sent (Limits).

A token of your own

For a script, a scheduled job or a client that cannot sign in, Account issues a token that is yours: name it, choose Read or Read and write, and copy it once. It is you, for your mailbox, and nothing else: as a bearer token it reaches /v1/mail and the os.my_mail_* tools, and is refused every other route of the enterprise with personal_token_only_reaches_mail. An owner neither sees nor manages it, and the enterprise's API tokens page lists only the enterprise's own. It stops the moment you revoke it on Account or leave the enterprise. Over the API, signed in: GET /v1/mail/tokens, POST /v1/mail/tokens with a name and mail:read, or mail:write too, and DELETE /v1/mail/tokens/{id}.

An enterprise API token is refused the mail scope and the /v1/mail routes: it belongs to the enterprise and to nobody, so no person's mailbox is its to read.

A member's mailbox over the API

An enterprise token with members:read reads a member's mailbox: GET /v1/members/{id}/emails lists it, a page at a time, GET /v1/members/{id}/emails/{emailId} opens one message and marks it read, and its attachments download from under it. Working a member's mailbox, its contacts and its signature is for the enterprise owner, signed in: a token or a connected app cannot act on it. GET /v1/members/{id}/mailbox-actions, and os.member_mailbox_actions over MCP, list the one-click buttons a member's mailbox offers.

The domains the enterprise receives mail on are /v1/enterprise/domains (Addresses and domains).