mails.ai

Mails.ai for Claude Code

Get startedAll integrations

Built in

Email tools inside Claude Code

Claude Code calls the mails tools when a task needs email, and shows you each call and what came back.

Claude Code · ~/my-app

  1. ❯ Send a test from the hello agent to reply@test.mails.ai and show me the answer

  2. tool mails_sendagent: "hello"to: "reply@test.mails.ai"subject: "Test"body_text: "Hello from Claude Code"

  3. { "id": "msg_01K…", "status": "delivered", … }

  4. tool mails_list_repliesagent: "hello"

  5. { "data": [{ "type": "reply.received", "data": { "subject": "Re: Test", … } }] }

  6. The test address answered in the same thread: “This is an automatic reply from the mails.ai test address.”

Setup

Add mails to Claude Code

Add to ~/.claude.json under mcpServers, then restart Claude Code.

Get startedAbout the MCP server
{
  "mcpServers": {
    "mails": {
      "command": "npx",
      "args": ["-y", "@mailsai/mcp-server"],
      "env": {
        "MAILS_API_KEY": "mk_live_..."
      }
    }
  }
}

Claude Code reads the whole thread first, then replies from the agent’s own address.

Noor HaddadLead Engineer, Larchwhistle

Hosted or local

Or sign in to the hosted server

One command adds https://api.mails.ai/mcp. Then type /mcp in Claude Code and choose mails, or run claude mcp login mails, and sign in. No key sits in a file. The MCP server page has the rest.

claude mcp add --transport http mails \
  https://api.mails.ai/mcp

# then type /mcp in Claude Code and choose mails,
# or sign in from your shell:
claude mcp login mails

Know-how

Teach Claude Code about email

Three open-source skills teach Claude Code to send, receive and safely act on email. The command asks which to add.

Get startedAbout the skills
npx skills add mailsai/skills -a claude-code

In action

See the skills in action

With the skills added, Claude Code checks a message before it answers it, and replies in the same thread.

Guide

Drop-in MCP server setup

MCP server · 4 min read · claude.com

This guide shows you how to give Claude Code email capabilities. Your agent can send and receive email without any extra tooling. You’ll need a mails.ai API key and about ten minutes.

Claude Code is an MCP-capable runtime. The mails.ai MCP server is an npm-distributed process that exposes email primitives as tools. Drop the snippet above into ~/.claude.json, restart Claude Code, and your session can send, read, and manage email without any SDK install or glue code on your end.

Why Claude Code + mails.ai

Claude Code already runs the Anthropic Sonnet/Opus models with a tool-calling loop. Adding email as an MCP tool means the model picks mails_send or mails_list_threads autonomously when the user’s request implies email work — no per-task prompt engineering, no separate API client to wire up. The same Claude Code session that edits your code can also reply to support tickets, send out scheduled communications, and parse inbound replies.

And because the MCP server runs client-side via npx, there is nothing to host on your end. The server is a thin tool-shape over the public REST API, with auth and retries handled in one place.

Setup — three steps

  1. Get an API key. Sign in at app.mails.ai/api-keys and mint one — self-serve, free tier, no card. A key can be bound to one agent.
  2. Add the MCP server config. Open ~/.claude.json in your editor of choice and add the snippet from the install card above (replacing mk_live_... with your key). If mcpServers already exists, just add mails as a sibling key.
  3. Restart Claude Code. The next session starts the MCP server via npx at startup. Tool discovery is automatic — you can verify by typing /mcp in Claude Code and looking for the mails entry.

First commands to test

After restart, prompt your Claude Code session naturally — the model will reach for the right tool:

# Verify the integration
> What mails_* tools do I have access to?

# Send a test email
> Use mails_send to email myself a hello message.

# Check replies
> List the most recent threads from the last day.

For each prompt, Claude Code calls the appropriate mails_* tool, returns the structured result, and presents it back. No glue code, no manual JSON wrangling.

Common patterns

These built-in tools cover most agent workflows:

  • mails_send — send an email from a named agent. Returns the message id, its thread_id and status, and the cold-email firewall’s classifier_score, from 0 (clean) to 1 (cold or spam), which shows how the send was graded.
  • mails_list_replies — list an agent’s typed reply events (reply.received), with since for polling. For push delivery, register a webhook.
  • mails_list_threads — query the agent’s conversation history. Filter by agent or status (open, closed, archived). Read-only, free.
  • mails_check_suppression — check whether an address is suppressed; mails_allowlist_address overrides that for one address with a written reason. Sends to suppressed addresses return a structured error rather than firing.
  • mails_get_reputation — query an agent’s reputation score (0-1), workspace-scoped. Useful to catch an at-risk agent before the 0.3% complaint auto-suspend. For a high-stakes inbound, check the event’s sender_reputation and injection_score.

Security considerations

  • Key scope. A key bound to one agent can act only as that agent, so a leak stays with it. Rotate keys via app.mails.ai/api-keys.
  • Tool refusal under injection. The reply.received event includes injection_score. Hold the event for a person instead of acting when it is quarantined, has no score (it was not scanned) or scores 0.5 or more — the prompt-injection RCE class is real (see that post) and Claude Code reading instructions from the body and following them is exactly the failure mode the score is designed to gate.
  • High-stakes confirmation. If your Claude Code agent has both mails_send and tools for irreversible actions (database writes, money movement), require an explicit human-in-the-loop confirmation before sending on behalf of those actions. The MCP tool surface itself does not enforce this; your agent prompt and runtime configuration do.
  • Project vs user scope. Add the server at local scope (the default) so only this project sees the key, or commit .mcp.json with "MAILS_API_KEY": "${MAILS_API_KEY}" and set the variable in CI. User-scope servers in ~/.claude.json apply to all your projects.

What ships next

The tools above ship today on the Free, Pro and Scale plans, billed monthly or yearly. The hosted server at https://api.mails.ai/mcp signs in with OAuth, so no key sits in a file. Per-agent hourly and daily send limits, when you set them, are enforced; a send past the limit gets a 429.

Read the MCP-native email post for the broader distribution thesis, or the architecture page for what the server calls under the hood.

Read next: MCP-native email — distribution wedge and Typed reply events for agents.

Questions developers ask after wiring this up.

Where do I get an API key?
Mint one at app.mails.ai/api-keys — self-serve, free tier, no card. A key reaches every agent in the workspace unless it is bound to one with agent_id (POST /v1/api-keys). If your Claude Code session manages multiple agents, pass the agent field to mails_send to choose one, or mint one agent-bound key per agent and use the env var to switch.
Does this work with Claude Code’s task tool / sub-agents?
Yes. MCP tools registered at the parent session are available in sub-agents launched with the Agent tool. The mails_* surface shows up identically in either context. If a sub-agent needs a different API key (different mails.ai agent), give that sub-agent its own inline mcpServers entry, with its own env, in its agent file.
How do I read replies in Claude Code?
Two paths. (1) Polling: call mails_list_replies with a since timestamp to fetch new replies on demand — useful in interactive sessions. (2) Webhook: register a webhook URL once (dashboard Webhooks page or POST /v1/webhooks), and have replies flow to your own handler outside Claude Code (better for autonomous operation).
What about secrets — my MAILS_API_KEY in ~/.claude.json?
The config file is on your machine. Treat it like ~/.aws/credentials. For shared machines or CI, add the server at local scope (the default) so only this project sees the key, or commit .mcp.json with "MAILS_API_KEY": "${MAILS_API_KEY}" and set the variable in CI. Or use the hosted server at https://api.mails.ai/mcp, which signs in with OAuth, so no key sits in a file.

“Replies come back as events with an injection score already on them. We deleted a whole layer of parsing code the week we switched, and we gate on the quarantine flag, so our agent never sees the ones that look like attacks.”

Tomás VargaStaff Engineer, Cinderjay

“Moving our agent onto our own domain was a few DNS records at the registrar. No nameserver move, and our existing mail kept working. Replies to the agent still come back to its inbox, threaded with the message they answer.”

Ishani VaidyaCTO, Sedgequay

“Our agent writes every reply as a draft, with a key that can’t send. Someone on the team reads it and hits Send now in the dashboard.”

Marcus FeldFounder, Marrowkite

“Our tests send to the test address and wait for the real reply, so the whole loop is covered before a customer ever writes in. It answers in about a second, which keeps the suite fast.”

Ana Lucía RíosEngineering Lead, Gorsefinch

“Adding the MCP server was one JSON block. Claude Code could send and read its own inbox a minute later.”

Jonah AbramsDeveloper, Wickerjay

“A reputation score per agent tells us exactly which one needs attention, instead of one number for the whole account. It comes from each agent’s own replies, bounces and complaints, and we read it from the API.”

Mei Lin ZhouOperations, Larchwhistle

“Sends and replies have separate allowances, so a busy inbox never eats our sending quota. Pricing was the easy part.”

Kwabena AdomakoFounder, Oxbowlark

“Half our agents are LangGraph in Python and half are Node. Both SDKs make the same calls, so the team doesn’t have to think about it.”

Sofia BrandtEngineer, Moss & Ladder

“Signed webhooks, retries with backoff and an event id to dedupe on. The boring plumbing, done properly.”

Nikhil BhonsleBackend Lead, Thimblecrow

“We signed up, made a key and sent our first message without talking to anyone, and the free tier never asked for a card. That’s how infrastructure should feel.”

Frieda WesselFounder, Ploverwick Studio

Give your first agent an inbox

Free covers 3,000 emails and 3,000 inbound replies a month, with no card. Upgrade when your agents get busy.

Get your API key