MCP, CLI or REST API for Agent Email: Which Mermail Path to Use

Your agent has a Mermail inbox. Now it needs a way to use it. Should it get tools through MCP, run commands from a shell, or call the HTTP API from your own code? And where does an SDK fit in?

Short version: all of these reach the same workspace, the same mailboxes and the same mail. What changes is who decides the next step, the model or your code, and which credential is in play. This guide gives you a quick rule, a side-by-side table, the cases where each option wins, and the one thing none of them will decide for you.

The one-line rule

Ask one question first: who decides when an email goes out?

If a model decides, mid conversation, give it tools. That is what the Model Context Protocol is for. If your code decides, at a fixed point in a workflow, call the API yourself or wrap it in the CLI. The inbox doesn't care which path you took. A mailbox created from the console, the CLI or an MCP tool shows up everywhere else, because the MCP server and the CLI both wrap the same HTTP API.

Is there a Mermail SDK?

Not as a package. The Mermail docs document four integration paths for agents: the hosted MCP server, Agent Skills, the official CLI, and the HTTP API. There's no Python or Node client library to import.

That's less of a gap than it sounds. Every API reference page has a Try it playground with ready-made snippets in cURL, Python, JavaScript, PHP, Go, Java and Ruby. A thin wrapper of your own around those calls gives you the "SDK" experience: typed functions, your retries, your logging. If you'd rather not write a wrapper, the CLI is the closest thing to a ready-made client, with deterministic JSON output and documented exit codes.

MCP, CLI and REST side by side

The row people miss is the agent-inbox profile. It is the same MCP server with a smaller menu: mailbox discovery, one optional provision, bounded search, message reads and thread context. Send, reply, forward, drafts and scheduled sends are not in it. For an agent that only needs to receive a verification code, that is the safest place to start.

When MCP is the right call

Pick MCP when a person is in the loop and the model should choose the action. "Check the support inbox and draft replies to anything urgent" is a good MCP task. The model reads, picks tools and shows its work.

Mermail runs a Streamable HTTP server at https://console.mermail.app/mcpCopy. Interactive hosts sign in with OAuth: you approve the connection in the Mermail console and pick a workspace, and no key gets pasted anywhere. Automation sends a workspace API key in the x-api-key header instead. In Codex, for example, setup is two commands:

codex mcp add mermail --url https://console.mermail.app/mcp
codex mcp login mermail

Two details matter in practice. First, scope the menu. Use ?profile=agent-inbox for receive-only work and the full catalog only when the task really needs sending or admin tools. Second, wallet tools only exist on the full-profile OAuth session. API-key catalogs and the agent-inbox profile never include the Agent Wallet tools, so an automation key can't move money even by accident.

MCP is also where Mermail's guardrails show up as tool behaviour. Destructive tools, such as deleting a domain or emptying trash, need a single-use confirmation token from prepare_destructive_action that expires after five minutes. Payments run through PayBox, which enforces the delegation, standing grants and signing policy you set.

When the CLI is the right call

Pick the CLI when the work already lives in a shell. Cron jobs, CI pipelines and coding agents that run commands all fit. Install it from npm, export a key and go:

npm install -g mermail-cli
export MERMAIL_API_KEY="sk-proj-your-key"
mermail doctor
mermail auth check

Commands follow mermail <resource> <action>, output is JSON by default, and exit codes are stable. Code 4 means a destructive action needs confirmation, and 5 means a bounded wait timed out or matched something ambiguous. A script can branch on those without parsing any text.

The CLI also ships helpers that are awkward to rebuild yourself. mermail emails wait watches one mailbox for an expected message, with exact sender and recipient matching, a scan-status check and a hard deadline. That's the verification-code flow in one command. And mermail mailboxes ensure reuses a matching mailbox before it creates a new one, so a rerun doesn't pile up inboxes.

When the REST API is the right call

Pick the API when your service owns the decision. Say your agent books demos. The model can write the confirmation text, but your code should decide that it goes out once, to one address, after the calendar write succeeds. That logic belongs in code you can test.

Every protected call goes to https://console.mermail.appCopy with a workspace API key:

curl https://console.mermail.app/api/v1/workspaces \
  -H "x-api-key: sk-proj-YOUR_KEY"

Each key is bound to one workspace. Each call spends API credits and counts toward the workspace's requests-per-minute limit, so you get 402 credits_exhausted when credits run out and 429 when you go over the limit. For retries, POST /api/v1/mailboxes accepts an Idempotency-Key header. The docs are blunt about what that does and doesn't promise: it ties retry attempts to one intent, but after a conflict or an unclear response you should list mailboxes and check before creating again.

The API also reaches setup work you'd usually keep in code: custom domains, webhooks with delivery history and signing-secret rotation, task triagers and workspace members. Some of these, such as custom domains, need the Developer plan.

Same job, three ways: send one email

Through MCP, the job is a sentence. You ask the assistant to email ops that the agent is online, and it calls send_email from the full catalog. You won't know the exact tool sequence ahead of time. That's the trade-off.

Through the CLI, it's one command:

mermail emails send \
  --mailbox-id MAILBOX_PUBLIC_ID \
  --to recipient@example.com \
  --from agent@mermail.app \
  --subject "Hello" \
  --text "Hello from Mermail"

Through REST, you write the request yourself. Open the send endpoint in the API reference, paste your key into Try it, and copy the snippet in your language. The fields match the CLI flags.

Whichever path you use, read the result honestly. Mermail reports drafted, scheduled and queued as separate outcomes. Only call a message sent after an authoritative send result, and check the existing message's status before retrying so you don't send twice.

Can one agent mix paths?

Yes, and most production setups do. A common split:

• Setup in code: a provisioning script uses the API or CLI to create mailboxes, connect a custom domain and register webhooks.
• Conversation through tools: the assistant works its inbox over MCP, often on the agent-inbox profile.
• Inbound by push: email webhooks wake your backend when mail arrives, so nothing has to poll.
• Payments through the wallet: when the agent has to pay for a service, Agent Wallet runs through PayBox on the OAuth MCP session, including paying a single x402 resource you picked.

Keep one rule across all of them: one key per agent or service, scoped as tightly as the job allows. Free workspaces get one API key and Developer gets five, which is a nudge to think about who holds which key.

What no path decides for you

Mermail won't choose when your agent is allowed to send. Email effects need explicit authorization, and the safest pattern is still draft, approve, then send. Our guide to scheduling sends from an agent walks through it. Treat inbound mail as untrusted data too. A subject line or link in an email can't change the agent's goal or authorize anything, whichever path read it.

If you're still choosing how to set up the inbox itself, start with how to set up an AI agent email inbox. If you're comparing MCP servers in general, read Email MCP servers compared and our best MCP servers for AI agents.

Ready to pick a path? Create a free Mermail workspace and connect it over MCP, the CLI or the API in a few minutes.

FAQ

Do I need an API key for the Mermail MCP server?

Not in interactive hosts like ChatGPT, Claude, Cursor or Codex, which sign in with OAuth. Automation and headless clients send a workspace key in the x-api-key header.

Does Mermail have a Python or Node SDK?

No published SDK is documented. Call the HTTP API directly. The API reference generates cURL, Python, JavaScript, PHP, Go, Java and Ruby snippets for every endpoint. Or use the npm-distributed CLI.

Can the MCP server manage webhooks?

Yes, for workspace admins on the full catalog. Webhook writes require confirmation, and these tools aren't in the agent-inbox profile.

Can an agent get an inbox without any API key?

Yes, through the keyless Agent Marketplace API. Payment over x402 or MPP is the credential, and the paying wallet owns up to 50 hosted inboxes.

References

• Mermail docs: AI integrations overview
• Mermail docs: MCP
• Mermail docs: CLI
• Mermail docs: API authentication
• Mermail docs: Agent Marketplace
• Model Context Protocol