API endpoints
Every Mail HTTP API endpoint, read from the OpenAPI document at build, with parameters and a request you can build and copy.
reference~2 minVerified v0.216.0
Every operation the Mail HTTP API answers, read from its OpenAPI document when the docs are built. The document itself is at https://mcp.superagentmail.app/v1/openapi.json, with no key needed. Open an endpoint for its parameters and a request built from the fields you fill in. The request reads your key from the SUPER_AGENT_MAIL_KEY environment variable, so the key never goes into this page.
12 endpoints
Every command below sends its request here.
Read5
GET/v1/mailboxesYour mailboxes · mail_mailboxes
Try it
Terminal
curl 'https://mcp.superagentmail.app/v1/mailboxes' \ -H "Authorization: Bearer $SUPER_AGENT_MAIL_KEY"
GET/v1/inboxInbox · mail_inbox
Parameters
- mailbox_idquery
- stringThe mailbox id from mail_mailboxes. Leave it out, or pass an empty string, to use your own mailbox.
- limitquery
- integerThreads to return. Default 20.
- beforequery
- stringAn ISO timestamp: only threads older than this.
Try it
Terminal
curl 'https://mcp.superagentmail.app/v1/inbox' \ -H "Authorization: Bearer $SUPER_AGENT_MAIL_KEY"
GET/v1/threads/{thread_id}Read a thread · mail_thread
Parameters
- thread_idpath, required
- stringA thread id from mail_inbox or mail_search.
Try it
Terminal
curl 'https://mcp.superagentmail.app/v1/threads/{thread_id}' \
-H "Authorization: Bearer $SUPER_AGENT_MAIL_KEY"GET/v1/searchSearch mail · mail_search
Parameters
- queryquery, required
- stringThe text to find in the subject, sender address or snippet: 2 to 200 characters once trimmed, matched as one phrase.
- mailbox_idquery
- stringThe mailbox id from mail_mailboxes. Leave it out, or pass an empty string, to use your own mailbox.
- limitquery
- integerResults to return. Default 20.
Try it
Terminal
curl 'https://mcp.superagentmail.app/v1/search' \ -H "Authorization: Bearer $SUPER_AGENT_MAIL_KEY"
GET/v1/rulesSending rules · mail_rules
Parameters
- mailbox_idquery
- stringThe mailbox id from mail_mailboxes. Leave it out, or pass an empty string, to use your own mailbox.
Try it
Terminal
curl 'https://mcp.superagentmail.app/v1/rules' \ -H "Authorization: Bearer $SUPER_AGENT_MAIL_KEY"
Write4
POST/v1/mailboxesCreate a shared mailbox · mail_mailbox_create
Parameters
- local_partbody, required
- stringThe part before the @, for example "team".
- domainbody
- stringA domain name, such as agents.example.com: one the workspace has added and verified in the Mail dashboard, or the Mail domain itself. Leave it out for the Mail domain.
Try it
Terminal
curl -X POST 'https://mcp.superagentmail.app/v1/mailboxes' \
-H "Authorization: Bearer $SUPER_AGENT_MAIL_KEY" \
-H 'Content-Type: application/json' \
-d '{"local_part":""}'PATCH/v1/mailboxes/{mailbox_id}Rename an address · mail_mailbox_rename
Parameters
- mailbox_idpath, required
- stringThe mailbox id from mail_mailboxes. Leave it out, or pass an empty string, to use your own mailbox.
- local_partbody, required
- stringThe new part before the @.
- domainbody
- stringA domain name, such as agents.example.com: one the workspace has added and verified in the Mail dashboard, or the Mail domain itself. Leave it out for the Mail domain.
Try it
Terminal
curl -X PATCH 'https://mcp.superagentmail.app/v1/mailboxes/{mailbox_id}' \
-H "Authorization: Bearer $SUPER_AGENT_MAIL_KEY" \
-H 'Content-Type: application/json' \
-d '{"local_part":""}'PUT/v1/webhookSet a webhook · mail_webhook_set
Parameters
- urlbody, required
- stringAn https address on port 443 with a public hostname, or null to clear it.
- mailbox_idbody
- stringThe mailbox id from mail_mailboxes. Leave it out, or pass an empty string, to use your own mailbox.
Try it
Terminal
curl -X PUT 'https://mcp.superagentmail.app/v1/webhook' \
-H "Authorization: Bearer $SUPER_AGENT_MAIL_KEY" \
-H 'Content-Type: application/json' \
-d '{"url":""}'POST/v1/draftsSave a draft · mail_draft
Parameters
- tobody, required
- array of stringPlain email addresses, like ada@example.com.
- ccbody
- array of stringAddresses to copy. At most 20 recipients in all.
- subjectbody, required
- string
- textbody, required
- stringThe message, as plain text.
- thread_idbody
- stringA thread of this mailbox to continue.
- mailbox_idbody
- stringThe mailbox id from mail_mailboxes. Leave it out, or pass an empty string, to use your own mailbox.
- idempotency_keybody
- stringReuse the same key to retry a call that failed on the wire: the message is created once. Leave it out for a new message.
Try it
Terminal
curl -X POST 'https://mcp.superagentmail.app/v1/drafts' \
-H "Authorization: Bearer $SUPER_AGENT_MAIL_KEY" \
-H 'Content-Type: application/json' \
-d '{"to":[],"subject":"","text":""}'Send3
POST/v1/sendSend a message · mail_send
Parameters
- tobody, required
- array of stringPlain email addresses, like ada@example.com.
- ccbody
- array of stringAddresses to copy. At most 20 recipients in all.
- subjectbody, required
- string
- textbody, required
- stringThe message, as plain text.
- thread_idbody
- stringA thread of this mailbox to continue.
- mailbox_idbody
- stringThe mailbox id from mail_mailboxes. Leave it out, or pass an empty string, to use your own mailbox.
- idempotency_keybody
- stringReuse the same key to retry a call that failed on the wire: the message is created once. Leave it out for a new message.
Try it
Terminal
curl -X POST 'https://mcp.superagentmail.app/v1/send' \
-H "Authorization: Bearer $SUPER_AGENT_MAIL_KEY" \
-H 'Content-Type: application/json' \
-d '{"to":[],"subject":"","text":""}'POST/v1/replyReply to a message · mail_reply
Parameters
- message_idbody, required
- stringThe id of the received message, from mail_thread.
- textbody, required
- stringYour answer, as plain text.
- ccbody
- array of stringAddresses to copy. At most 20 recipients in all.
- artifactbody
- stringA Super Artifacts link to share instead of an attachment, such as a report or a page you published in this workspace. It goes under your text, next to the AI line. Only an artifact of this workspace is accepted; mail carries no attachments.
- mailbox_idbody
- stringThe mailbox id from mail_mailboxes. Leave it out, or pass an empty string, to use your own mailbox.
- idempotency_keybody
- stringReuse the same key to retry a call that failed on the wire: the message is created once. Leave it out for a new message.
Try it
Terminal
curl -X POST 'https://mcp.superagentmail.app/v1/reply' \
-H "Authorization: Bearer $SUPER_AGENT_MAIL_KEY" \
-H 'Content-Type: application/json' \
-d '{"message_id":"","text":""}'POST/v1/forwardForward a message · mail_forward
Parameters
- thread_idbody, required
- stringThe thread the message is in.
- message_idbody, required
- stringThe id of the message to forward.
- tobody, required
- array of stringPlain email addresses, like ada@example.com.
- ccbody
- array of stringAddresses to copy. At most 20 recipients in all.
- notebody
- stringWhat you want to say above the forwarded message.
- mailbox_idbody
- stringThe mailbox id from mail_mailboxes. Leave it out, or pass an empty string, to use your own mailbox.
- idempotency_keybody
- stringReuse the same key to retry a call that failed on the wire: the message is created once. Leave it out for a new message.
Try it
Terminal
curl -X POST 'https://mcp.superagentmail.app/v1/forward' \
-H "Authorization: Bearer $SUPER_AGENT_MAIL_KEY" \
-H 'Content-Type: application/json' \
-d '{"thread_id":"","message_id":"","to":[]}'