AgentMail

01

Setup

1. 01Create an API key. In your AgentMail dashboard, create an API key. AgentMail bills usage to that account directly.
2. 02Connect AgentMail. In the superagnt app open Integrations, pick AgentMail, paste the key and press Connect.

02

Things to know

• Create an inbox with connection_agentmail_inboxes_write action create. Leave out username and AgentMail picks a random one. domain defaults to agentmail.to, and any other domain must be verified in AgentMail first. The message, thread and draft tools take the inbox_id the call returns.
• get_organization shows the organization's inbox and domain limits and how many of each are in use.
• Lists page with limit and page_token. Message, thread and draft lists also filter by labels and before or after timestamps. To see spam, blocked, unauthenticated or trashed messages, pass include_spam, include_blocked, include_unauthenticated or include_trash.
• Attachments and a message's raw .eml source come back as expiring download URLs, not as file content.
• batch_get_messages returns the metadata, without bodies, of up to 500 messages in one call.
• System labels (sent, received, bounced and the like) cannot be added or removed, and update_thread rejects a thread with 100 or more messages.
• delete_thread moves a thread to trash. A thread already in trash, or one deleted with permanent=true, is gone for good.
• A draft saved with send_at is sent by AgentMail at that time, with no further call.
• Sending a message, a reply, a reply-all, a forward or a draft, and every delete, always ask a person first by default. Everything else runs without asking, saving a draft with send_at included: see Permissions.
• The connection does not cover AgentMail account administration: API keys, domains and pods stay managed in AgentMail.

Webhooks

• connection_agentmail_webhooks_write action create posts the event_types you pick to your url: message.received (and its .spam, .blocked and .unauthenticated variants), message.sent, message.delivered, message.bounced, message.complained, message.rejected and domain.verified.
• A webhook can be scoped to up to 10 inbox_ids and up to 10 pod_ids.
• Point it at a superagnt_ inbound webhook endpoint to start an agent when mail arrives. AgentMail signs each delivery with the webhook's secret, which an inbound endpoint does not check, so leave the endpoint's signature verification off and keep its URL secret.
• Without a webhook, poll list_messages with after set to the time of your last check.

03

Examples

Create an inbox

curl -X POST "https://api.superagnt.com/v1/connections/agentmail/v0/inboxes" \
  -H "Authorization: Bearer $AGNTDATA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"username": "support-agent", "display_name": "Support Agent"}'

Send a message

curl -X POST "https://api.superagnt.com/v1/connections/agentmail/v0/inboxes/<inbox_id>/messages/send" \
  -H "Authorization: Bearer $AGNTDATA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "jenny.rosen@example.com",
    "subject": "Your order has shipped",
    "text": "Hi Jenny, your order left our warehouse today."
  }'

Push new mail to an agent

curl -X POST "https://api.superagnt.com/v1/connections/agentmail/v0/webhooks" \
  -H "Authorization: Bearer $AGNTDATA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://api.superagnt.com/webhooks/ingest/<endpoint id>",
    "event_types": ["message.received"]
  }'

17 tools, one per resource and risk

MCP servers and agents on the grouped surface list AgentMail as these tools. Each takes an action, and the ones that work across record types an object. Every operation also keeps its own per-operation name, in the next table, which works on every server. How grouping works: Grouped tools.

All 36 operations

Each operation is a REST path under https://api.superagnt.com/v1/connections/agentmail and an MCP tool. The per-operation tool name is the one permissions, approvals and usage records use.

Related