[{"data":1,"prerenderedAt":28},["ShallowReactive",2],{"$fgg6ex82sp58f":3},{"href":4,"title":5,"description":6,"kind":7,"mark":7,"planned":8,"contributors":9,"provenance":7,"express":8,"bridge":8,"html":10,"headings":11},"\u002Fdocs\u002Femail\u002Fmcp-and-api","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.",null,false,[],"\u003Ch2 id=\"what-there-is\">What there is\u003C\u002Fh2>\n\u003Cp>Mail can be reached from outside the portal in three ways. Each one only ever reaches the mailbox it belongs to:\u003C\u002Fp>\n\u003Cdiv class=\"prose__table\">\n\u003Ctable>\n\u003Cthead>\n\u003Ctr>\n\u003Cth>From\u003C\u002Fth>\n\u003Cth>Whose mailbox\u003C\u002Fth>\n\u003Cth>How\u003C\u002Fth>\n\u003C\u002Ftr>\n\u003C\u002Fthead>\n\u003Ctbody>\n\u003Ctr>\n\u003Ctd>An MCP client\u003C\u002Ftd>\n\u003Ctd>Your own, as a person\u003C\u002Ftd>\n\u003Ctd>The \u003Ccode>os.my_mail_*\u003C\u002Fcode> tools on the enterprise's \u003Ca href=\"\u002Fdocs\u002Fmcp\">MCP server\u003C\u002Fa>\u003C\u002Ftd>\n\u003C\u002Ftr>\n\u003Ctr>\n\u003Ctd>Code, as you\u003C\u002Ftd>\n\u003Ctd>Your own, as a person\u003C\u002Ftd>\n\u003Ctd>\u003Ccode>\u002Fv1\u002Fmail\u003C\u002Fcode> and the routes under it, with your session or a token of your own\u003C\u002Ftd>\n\u003C\u002Ftr>\n\u003Ctr>\n\u003Ctd>Code, with a token\u003C\u002Ftd>\n\u003Ctd>A member's, to read\u003C\u002Ftd>\n\u003Ctd>\u003Ccode>\u002Fv1\u002Fmembers\u002F{id}\u002Femails\u003C\u002Fcode> and the routes under it, with \u003Ccode>members:read\u003C\u002Fcode>\u003C\u002Ftd>\n\u003C\u002Ftr>\n\u003C\u002Ftbody>\n\u003C\u002Ftable>\n\u003C\u002Fdiv>\n\u003Cp>A member's own tasks reach its mailbox with the built-in mail tools instead: see\n\u003Ca href=\"\u002Fdocs\u002Femail\u002Fmail-in-tasks\">Mail in tasks\u003C\u002Fa>.\u003C\u002Fp>\n\u003Cp>This page says what each family is for and who may use it. The exact fields, answers and errors of every tool are in\nthe generated \u003Ca href=\"\u002Fdocs\u002Fmcp\u002Ftools\">MCP tool reference\u003C\u002Fa>, and every route with the scope it needs is on\n\u003Ca href=\"\u002Fdocs\u002Fapi\u002Fendpoints\">Endpoints\u003C\u002Fa>.\u003C\u002Fp>\n\u003Ch2 id=\"your-mailbox-over-mcp\">Your mailbox over MCP\u003C\u002Fh2>\n\u003Cp>Connect the enterprise's MCP server from Claude, ChatGPT or any MCP client by signing in, and choose what the app may\ndo with \u003Ccode>mail\u003C\u002Fcode> on the consent screen (\u003Ca href=\"\u002Fdocs\u002Fmcp\u002Fconnected-apps\">Connected apps\u003C\u002Fa>). \u003Cstrong>Account\u003C\u002Fstrong> shows the server\naddress to paste and the apps you have connected, each with \u003Cstrong>Disconnect\u003C\u002Fstrong>.\u003C\u002Fp>\n\u003Cul>\n\u003Cli>\u003Cstrong>Read\u003C\u002Fstrong> gives the app your inbox, one message with its text and formatting, the files on a message, your contacts,\nyour signatures and extra addresses, and the one-click buttons your inbox offers.\u003C\u002Fli>\n\u003Cli>\u003Cstrong>Write\u003C\u002Fstrong> adds replying, forwarding and sending, deleting, filing (labels, handled states, many messages at once),\npressing a button or putting it on a cadence, saving and removing contacts, and setting your signatures.\u003C\u002Fli>\n\u003C\u002Ful>\n\u003Cp>For example, \u003Ccode>os.my_mail_list\u003C\u002Fcode> lists your mail and \u003Ccode>os.my_mail_read\u003C\u002Fcode> opens one message; \u003Ccode>os.my_mail_send\u003C\u002Fcode>,\n\u003Ccode>os.my_mail_reply\u003C\u002Fcode> and \u003Ccode>os.my_mail_forward\u003C\u002Fcode> send, and each takes the body as \u003Ccode>markdown\u003C\u002Fcode>, attachments by link, by a\nfile already in your mailbox or as bytes, and \u003Ccode>signature: false\u003C\u002Fcode> to go unsigned (\u003Ca href=\"\u002Fdocs\u002Femail\u002Fwriting-mail\">Writing mail\u003C\u002Fa>).\nNothing you send waits for approval: it is your own mail.\u003C\u002Fp>\n\u003Ch2 id=\"your-mailbox-over-the-api\">Your mailbox over the API\u003C\u002Fh2>\n\u003Cp>The same mailbox is \u003Ccode>\u002Fv1\u002Fmail\u003C\u002Fcode> for a person signed in, or for a token of their own: \u003Ccode>GET \u002Fv1\u002Fmail\u003C\u002Fcode> lists it with the\nsame filters and a free-text search, \u003Ccode>GET \u002Fv1\u002Fmail\u002F{id}\u003C\u002Fcode> opens a message, and the routes under it reply, forward,\ndelete, file and download attachments, a file as JSON up to 4 MB. \u003Ccode>POST \u002Fv1\u002Fmail\u003C\u002Fcode> sends a new message. Contacts,\nsignatures, extra addresses' signatures and the one-click buttons each have routes under \u003Ccode>\u002Fv1\u002Fmail\u003C\u002Fcode> too. A change on\nmany messages at once takes up to 200 of them.\u003C\u002Fp>\n\u003Cp>A body given both as \u003Ccode>markdown\u003C\u002Fcode> and as \u003Ccode>text\u003C\u002Fcode> or \u003Ccode>html\u003C\u002Fcode> is refused with \u003Ccode>mail_body_conflict\u003C\u002Fcode>. Attachments over the\nlimits are refused whole, with \u003Ccode>attachments_over_limit\u003C\u002Fcode>, and nothing is sent (\u003Ca href=\"\u002Fdocs\u002Femail\u002Flimits\">Limits\u003C\u002Fa>).\u003C\u002Fp>\n\u003Ch2 id=\"a-token-of-your-own\">A token of your own\u003C\u002Fh2>\n\u003Cp>For a script, a scheduled job or a client that cannot sign in, \u003Cstrong>Account\u003C\u002Fstrong> issues a token that is yours: name it,\nchoose \u003Cstrong>Read\u003C\u002Fstrong> or \u003Cstrong>Read and write\u003C\u002Fstrong>, and copy it once. It is you, for your mailbox, and nothing else: as a bearer\ntoken it reaches \u003Ccode>\u002Fv1\u002Fmail\u003C\u002Fcode> and the \u003Ccode>os.my_mail_*\u003C\u002Fcode> tools, and is refused every other route of the enterprise with\n\u003Ccode>personal_token_only_reaches_mail\u003C\u002Fcode>. An owner neither sees nor manages it, and the enterprise's \u003Cstrong>API tokens\u003C\u002Fstrong> page lists\nonly the enterprise's own. It stops the moment you revoke it on \u003Cstrong>Account\u003C\u002Fstrong> or leave the enterprise. Over the API,\nsigned in: \u003Ccode>GET \u002Fv1\u002Fmail\u002Ftokens\u003C\u002Fcode>, \u003Ccode>POST \u002Fv1\u002Fmail\u002Ftokens\u003C\u002Fcode> with a name and \u003Ccode>mail:read\u003C\u002Fcode>, or \u003Ccode>mail:write\u003C\u002Fcode> too, and\n\u003Ccode>DELETE \u002Fv1\u002Fmail\u002Ftokens\u002F{id}\u003C\u002Fcode>.\u003C\u002Fp>\n\u003Cp>An enterprise API token is refused the \u003Ccode>mail\u003C\u002Fcode> scope and the \u003Ccode>\u002Fv1\u002Fmail\u003C\u002Fcode> routes: it belongs to the enterprise and to\nnobody, so no person's mailbox is its to read.\u003C\u002Fp>\n\u003Ch2 id=\"a-members-mailbox-over-the-api\">A member's mailbox over the API\u003C\u002Fh2>\n\u003Cp>An enterprise token with \u003Ccode>members:read\u003C\u002Fcode> reads a member's mailbox: \u003Ccode>GET \u002Fv1\u002Fmembers\u002F{id}\u002Femails\u003C\u002Fcode> lists it, a page at a\ntime, \u003Ccode>GET \u002Fv1\u002Fmembers\u002F{id}\u002Femails\u002F{emailId}\u003C\u002Fcode> opens one message and marks it read, and its attachments download from\nunder it. Working a member's mailbox, its contacts and its signature is for the enterprise owner, signed in: a token or\na connected app cannot act on it. \u003Ccode>GET \u002Fv1\u002Fmembers\u002F{id}\u002Fmailbox-actions\u003C\u002Fcode>, and \u003Ccode>os.member_mailbox_actions\u003C\u002Fcode> over MCP,\nlist the one-click buttons a member's mailbox offers.\u003C\u002Fp>\n\u003Cp>The domains the enterprise receives mail on are \u003Ccode>\u002Fv1\u002Fenterprise\u002Fdomains\u003C\u002Fcode>\n(\u003Ca href=\"\u002Fdocs\u002Femail\u002Faddresses-and-domains#over-the-api\">Addresses and domains\u003C\u002Fa>).\u003C\u002Fp>\n",[12,16,19,22,25],{"id":13,"text":14,"level":15,"planned":8},"what-there-is","What there is",2,{"id":17,"text":18,"level":15,"planned":8},"your-mailbox-over-mcp","Your mailbox over MCP",{"id":20,"text":21,"level":15,"planned":8},"your-mailbox-over-the-api","Your mailbox over the API",{"id":23,"text":24,"level":15,"planned":8},"a-token-of-your-own","A token of your own",{"id":26,"text":27,"level":15,"planned":8},"a-members-mailbox-over-the-api","A member's mailbox over the API",1794928143036]