Mail MCP tools

Every tool the Mail MCP server lists, with its inputs, its output and the HTTP route that runs it.

reference~5 minVerified v0.216.0

The Mail MCP server is https://mcp.superagentmail.app/mcp. A read only connection sees only the tools that read, and a call to any other is refused with read_only.

Tool	What it is	Effect	On a read only key
`mail_mailboxes`	Your mailboxes	Reads mail	Yes
`mail_inbox`	Inbox	Reads mail	Yes
`mail_thread`	Read a thread	Reads mail	Yes
`mail_search`	Search mail	Reads mail	Yes
`mail_mailbox_create`	Create a shared mailbox	Changes settings or saves a draft	No
`mail_mailbox_rename`	Rename an address	Changes settings or saves a draft	No
`mail_webhook_set`	Set a webhook	Changes settings or saves a draft	No
`mail_rules`	Sending rules	Reads mail	Yes
`mail_draft`	Save a draft	Changes settings or saves a draft	No
`mail_send`	Send a message	Sends, through the gate	No
`mail_reply`	Reply to a message	Sends, through the gate	No
`mail_forward`	Forward a message	Sends, through the gate	No

The server checks every call against the schemas below and refuses what they do not allow with invalid_arguments. A model may send null for an optional argument. The HTTP API takes the same snake case names.

mailbox_id is optional everywhere: leave it out to use the agent's own mailbox, or the call fails with no_mailbox. Reuse an idempotency_key to retry a call that failed on the wire, and the message is made once.

mail_mailboxes

Field	Type	Notes
Route		`GET` `/v1/mailboxes`. No input.
Output `mailboxes`	array	Each has `id`, `kind` (`agent` or `shared`), `localPart`, `address`, `status` (`open` or `closed`), `gateMode` (`review`, `filtered` or `none`), and when set `webhookUrl` and `webhookVersion`.
Output `notice`	string or null	Why the agent has no address yet.

mail_inbox

Field	Type	Notes
Route		`GET` `/v1/inbox`. Threads, newest first.
`mailbox_id`	string	Optional.
`limit`	integer	1 to 50, default 20.
`before`	string	An ISO timestamp. Pass the `lastMessageAt` of the oldest thread to page back.
Output `threads`	array	Each has `id`, `subject`, `correspondents`, `flagged`, `startedByPerson`, `lastMessageAt`, `messageCount` and `latest` (`direction`, `from`, `snippet`, `machine`, `injectionScore`).

mail_thread

Field	Type	Notes
Route		`GET` `/v1/threads/:id`.
`thread_id`	string	Required. From `mail_inbox` or `mail_search`.
Output `thread`	object	The thread fields above plus `mailboxId`.
Output `notice`	string	A line to pass on.
Output `messages`	array	Each has `id`, `direction`, `from`, `to`, `cc`, `subject`, `at`, `machine`, `auth`, `injection`, `text`, `truncated` and `attachments` (`filename`, `mimeType`, `size`). `auth` and `injection` are the screening results.

mail_search

Field	Type	Notes
Route		`GET` `/v1/search`. The query is matched as one exact phrase in the subject, sender address or snippet, ignoring case. No operators or wildcards.
`query`	string	Required. 2 to 200 characters once trimmed.
`mailbox_id`	string	Optional. Without it, the agent's mailbox and the shared ones are searched.
`limit`	integer	1 to 50, default 20.
Output `results`	array	Newest first. Each has `threadId`, `mailboxId`, `messageId`, `createdAt` and when known `direction`, `from`, `subject`, `snippet`.

mail_rules

Field	Type	Notes
Route		`GET` `/v1/rules`. Read only: a person changes the rules in the dashboard.
`mailbox_id`	string	Optional.
Output	object	`mailboxId`, `gateMode`, `allowList` (addresses and domains), `allowedModes` and when known `plan`.

mail_send

Field	Type	Notes
Route		`POST` `/v1/send`. A new message from the agent's address.
`to`	array of strings	Required. 1 to 20 addresses.
`cc`	array of strings	Up to 20, and 20 recipients in all.
`subject`	string	Required. 1 to 998 characters.
`text`	string	Required. Plain text, 1 to 100,000 characters.
`thread_id`	string	A thread of this mailbox to continue.
`mailbox_id`, `idempotency_key`	string	Optional. The key is 1 to 200 characters.
Output	object	The send answer.

mail_reply

Field	Type	Notes
Route		`POST` `/v1/reply`. Answers a received message, in its thread, to its sender. A reply to machine mail is always held.
`message_id`	string	Required. From `mail_thread`.
`text`	string	Required. 1 to 100,000 characters.
`cc`	array of strings	Up to 20.
`artifact`	string	A Super Artifacts link from this workspace, shared under the text instead of an attachment.
`mailbox_id`, `idempotency_key`	string	Optional.
Output	object	The send answer.

mail_forward

Field	Type	Notes
Route		`POST` `/v1/forward`. Attachments are not forwarded.
`thread_id`, `message_id`	string	Required. The message to forward and its thread.
`to`	array of strings	Required. 1 to 20.
`cc`	array of strings	Up to 20.
`note`	string	Up to 20,000 characters, shown above the message.
`mailbox_id`, `idempotency_key`	string	Optional.
Output	object	The send answer.

mail_draft

Field	Type	Notes
Route		`POST` `/v1/drafts`. Saves a message for a person to review. Nothing is sent.
Input		Those of `mail_send`.
Output	object	The send answer.

The send answer

Only status and outboundId are always present.

Output	Type	Meaning
`status`	string	`sent`, `pending`, `held`, `drafted`, `failed` or `rejected`. Over HTTP the last two are errors.
`outboundId`	string	The id of this message.
`threadId`	string or null	Its thread.
`reasons`	array	Why it is held. See Gate modes.
`duplicate`	boolean	An earlier call with the same `idempotency_key` made it.
`notice`	string	A line for the agent to pass on.
`reviewUrl`	string	Where a person approves a hold or a draft.
`error`	string or null	What went wrong when `failed` or `rejected`.

mail_mailbox_create

Field	Type	Notes
Route		`POST` `/v1/mailboxes`. A shared mailbox. It needs Team, room left, and an agent a workspace owner connected.
`local_part`	string	Required. The name before the `@`.
`domain`	string	4 to 253 characters. A verified custom domain, or the Mail domain. Only an owner's agent can use a custom domain.
Output `mailbox`	object	One mailbox, as above.

mail_mailbox_rename

Field	Type	Notes
Route		`PATCH` `/v1/mailboxes/:id`, where the path fills `mailbox_id`. People who wrote to the old address bounce afterwards.
`local_part`	string	Required. The new name.
`mailbox_id`	string	Optional.
`domain`	string	Move to a verified custom domain, or back to the Mail domain by naming it.
Output `mailbox`	object	One mailbox, as above.

mail_webhook_set

Field	Type	Notes
Route		`PUT` `/v1/webhook`. Sends a signed POST for each new message.
`url`	string or null	Required. https, port 443, a public host name. `null` clears it.
`mailbox_id`	string	Optional.
Output	object	`mailboxId`, `url` and `version`. With `null`, `cleared` is true. Otherwise also `secret`, shown once, `secretShownOnce`, and `signature`, a sentence on how requests are signed. Calling again makes a new secret and retires the old. See Webhook signing.