MCP

MiniMailer ships a native MCP (Model Context Protocol) server. An AI agent connects to it and can send email, check suppressions, read inbound mail, and run campaigns as first-class tool calls — no custom integration code, no HTTP client glue, no prompt-pasted API docs.

Connect

The server speaks Streamable HTTP at:

https://minimailer.app/mcp/v1

Authenticate one of two ways:

OAuth — MCP clients that support the OAuth flow (Claude, and most desktop clients) can connect and authorize interactively.
API token — send a personal access token with the mcp:use scope as a bearer header. Right for headless agents and CI.

For Claude Code:

claude mcp add --transport http minimailer https://minimailer.app/mcp/v1

For clients configured by JSON, the shape is the usual:

{
    "mcpServers": {
        "minimailer": {
            "type": "http",
            "url": "https://minimailer.app/mcp/v1",
            "headers": { "Authorization": "Bearer <token>" }
        }
    }
}

MCP traffic shares the REST API's rate limits — an agent burning tokens can't starve your own API usage beyond your tier's budget.

Tools

Tool	What it does
`send-email-tool`	Send a transactional email from a verified domain
`check-suppression-tool`	Check whether an address is suppressed for a domain
`remove-suppression-tool`	Remove a non-permanent suppression
`get-email-stats-tool`	Delivery/open/click stats for a sent email
`list-inbound-emails-tool`	Recent inbound email summaries
`get-inbound-email-tool`	One inbound email in full (headers, bodies)
`send-campaign-tool`	Dispatch a prepared campaign
`list-campaigns-tool`	List campaigns and their statuses
`get-campaign-stats-tool`	Aggregate stats for a campaign

The server also exposes resources an agent can read for context — your verified sending domains and your inboxes — and a prompt (compose-transactional-email-prompt) that guides a model through composing a well-formed transactional message.

Tool inputs mirror the REST API: a send takes to, subject, html/text (at least one), optional cc/bcc copy recipients (up to 10 each), optional reply_to addresses (up to 10, on the sending domain's family), and resolves the sender from from or domain — when from is omitted the sender defaults to noreply@{domain}. Ownership is enforced exactly as in the REST API: an agent can only ever send from domains on the authenticated account.

Built for agents, honestly

Two behaviours are specific to the MCP path:

AI disclosure is on by default. Sends through the MCP server attach a machine-readable X-AI-Generated header marking the message as AI-originated. An explicit ai_disclosure: false opts out. The header does not replace any human-facing disclosure your use case requires in the email body — it complements it.
Per-agent reputation. Pass an agent_id (up to 128 chars, [A-Za-z0-9_-.]) on sends and MiniMailer tracks reputation per agent, not just per domain. One misbehaving agent surfaces in its own metrics — and in agent.* webhooks — before it can drag down everything else you send. How reputation works →

Examples

See MCP examples for copy-paste agent-prompt recipes — password resets, receipts, replying to inbound mail, attributing sends to an agent, and dispatching campaigns.

Errors

Tool calls return structured errors, not stack traces: an unverified or unowned domain reads as not found, an inactive domain names its current status, and free-tier quota exhaustion says exactly that. Agents can act on the message text without parsing HTML or guessing at HTTP semantics.