Mails.ai
for Cursor
Built in
Email tools inside Cursor
Cursor’s agent reaches for the mails tools when a task needs email: a test send, a look at the replies, a suppression check.
Setup
Add mails to Cursor
Add to ~/.cursor/mcp.json under mcpServers, then restart Cursor.
{
"mcpServers": {
"mails": {
"command": "npx",
"args": ["-y", "@mailsai/mcp-server"],
"env": {
"MAILS_API_KEY": "mk_live_..."
}
}
}
}Try it
Things to ask Cursor
Copy any prompt into Cursor, or open it there, and the agent does the rest with the mails tools.
“Send a test from the hello agent to reply@test.mails.ai and show me the reply”
“List the open threads for the hello agent”
“Is jane@example.com on our suppression list?”
“On Pro (5 agents), create an agent called billing for invoice emails”
“Summarise the replies the hello agent got today”
“How healthy is the hello agent’s sending reputation?”
“Draft a reply to the newest message in the hello inbox for me to review”
“Show me the whole thread for the latest refund request”
“How much of this month’s allowance have we used?”
Cursor’s agent sends a test message and checks for the reply, all inside the editor.
Hosted or local
Or point Cursor at the hosted server
Add https://api.mails.ai/mcp by URL in ~/.cursor/mcp.json, or .cursor/mcp.json for one project. Cursor supports OAuth sign-in for servers that need it, or send an API key from your environment. The MCP server page has the rest.
{
"mcpServers": {
"mails": {
"url": "https://api.mails.ai/mcp"
}
}
}Know-how
Teach Cursor about email
Three open-source skills teach Cursor to send, receive and safely act on email. The command asks which to add.
npx skills add mailsai/skills -a cursorIn action
See it work
in Cursor
Press play to run the session. Each call is a real mails tool, and each result has the shape the API returns.
This guide wires mails.ai into Cursor’s in-IDE agent. It’s one JSON snippet — no SDK to install, no glue code to write. Once it’s set up, your Cursor agent can send email, read replies, and manage threads right inside your editor. You’ll need a mails.ai API key and about five minutes.
Cursor is an MCP-capable runtime. The mails.ai MCP server is the same npm-distributed process as the Claude Code setup — one JSON snippet in ~/.cursor/mcp.json, restart Cursor, and your in-IDE agent has email.
Why Cursor + mails.ai
Cursor’s in-IDE Agent is one of the most powerful environments for autonomous coding workflows. Adding email as an MCP tool means the agent can do things like:
- Email a teammate when a draft branch is ready for review.
- Send progress reports during long refactors.
- Read a customer support thread (via
mails_list_threadsandmails_get_thread), draft a fix, and email back when shipped. - Process incoming bug reports as typed events — injection score, plus intent and entities when the agent has
classify_inboundon (paid plans) — before deciding whether to act.
Depending on your Run Mode, Cursor asks before running a mails_* tool, and you can expand the call to see its arguments. Allowlist the tools you trust, and keep mails_send off the allowlist while it can reach customers.
Setup — three steps
- Get an API key. Sign in at
app.mails.ai/api-keysand mint one — self-serve, free tier, no card. - Add the MCP server config. Open
~/.cursor/mcp.jsonin your editor and add the snippet from the install card above (replacingmk_live_...with your key). For project-scoped keys, use.cursor/mcp.jsonin the project root and add it to.gitignore. - Restart Cursor. The next session starts the MCP server via
npx. Verify in Customize → MCPs thatmailsappears in the registered servers list.
First commands to test
In Cursor’s Agent, prompt naturally:
# Verify the integration
> What mails_* tools are available to me?
# Send a test email (depending on your Run Mode, Cursor asks before running it)
> Use mails_send to email me a hello.
# Query recent inbound
> List the last day of threads.Depending on your Run Mode, Cursor asks before running a mails_* tool, and you can expand the call to see its arguments. Approve once to test; add it to the allowlist once you trust the pattern.
Common patterns
- Branch-ready notification. Long-running coding agent finishes the work, calls
mails_sendto email reviewers with the diff link. - Review-cycle support. A Cloud Agent polls
mails_list_repliesfor replies on the review thread, reads each reply’s text, and reacts. - Documentation request triage. Agent reads incoming doc-request emails as typed events, drafts updates, and replies via
mails_send. - Incident response notification. A Cloud Agent watching production sends notifications to the on-call rotation when anomalies fire.
Security considerations
- Per-key scope. Bind each key to one agent (
agent_id,POST /v1/api-keys). A compromised bound key exposes only that agent. Rotate viaapp.mails.ai/api-keys. - Tool refusal under injection. Inbound events include
injection_score. When your Cursor agent reads inbound and acts on it, hold the event for a person when it isquarantined, has no score (it was not scanned) or scores 0.5 or more. See the injection scanning post. - Project vs user scope. Project-level
.cursor/mcp.json(gitignored) for project-specific keys. The user-level~/.cursor/mcp.jsonapplies to all projects on the machine. - Auto-execute discipline. In Settings → Agents → Approvals & Execution, choose Allowlist and keep
mails_sendoff the allowlist until the workflow is stable.
Read the MCP-native email post for the broader thesis or the Claude Code integration for the same setup with a different config path.
Read next: Mails.ai for Claude Code and MCP-native email — distribution wedge.
Questions developers ask after wiring this up.
How is this different from the Claude Code integration?
Does the agent send emails autonomously, or do I have to approve each one?
Can I scope a key to one project?
Does this work with Cursor’s background agents?
“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.”
“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.”
“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.”
“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.”
“Adding the MCP server was one JSON block. Claude Code could send and read its own inbox a minute later.”
“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.”
“Sends and replies have separate allowances, so a busy inbox never eats our sending quota. Pricing was the easy part.”
“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.”
“Signed webhooks, retries with backoff and an event id to dedupe on. The boring plumbing, done properly.”
“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.”
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