Mails.ai
for Windsurf
Built in
Email tools inside Windsurf
Cascade calls the mails tools when a task needs email, and shows each call and its result as it works.
When the migration finishes, email reply@test.mails.ai from the hello agent and check it arrived
- tool mails_sendagent: "hello"to: "reply@test.mails.ai"subject: "Migration finished"body_text: "The migration finished."
{ "id": "msg_01K…", "status": "delivered", … }
- tool mails_list_repliesagent: "hello"
{ "data": [{ "type": "reply.received", "data": { "subject": "Re: Migration finished", … } }] }
Sent from the hello agent; the test address answered in the same thread.
Setup
Add mails to Windsurf
Add to ~/.config/devin/mcp_config.json. To verify, open the Actions (...) menu in the Cascade panel and check its MCPs section.
{
"mcpServers": {
"mails": {
"command": "npx",
"args": ["-y", "@mailsai/mcp-server"],
"env": {
"MAILS_API_KEY": "mk_live_..."
}
}
}
}Cascade emails me when a long task finishes, so I stopped watching the editor.
Hosted or local
Or add the hosted server
Add mails by URL in ~/.config/devin/mcp_config.json, the file both Cascade and the Devin Local agent read. Devin Desktop supports OAuth, so you sign in to mails.ai in your browser instead of keeping a key there. The MCP server page has the rest.
{
"mcpServers": {
"mails": {
"url": "https://api.mails.ai/mcp"
}
}
}Know-how
Teach Windsurf about email
Three open-source skills teach Windsurf to send, receive and safely act on email. The command asks which to add.
npx skills add mailsai/skills -a windsurfIn action
See the skills
in action
With the skills added, Windsurf checks a message before it answers it, and replies in the same thread.
This guide gives Windsurf’s Cascade agent the ability to send and read email. Cascade runs long, autonomous tasks — and now it can email you progress updates, notify teammates, or triage inbound replies mid-task. You’ll add one JSON file and save it. A mails.ai API key is all you need.
Windsurf (now Devin Desktop) is an AI-native IDE built around the Cascade autonomous agent. Add the mails.ai MCP server to ~/.config/devin/mcp_config.json and Cascade auto-discovers the same mails_* tools for use in Code mode or Plan mode (Plan writes a plan and asks before implementing).
Why Windsurf + mails.ai
Cascade’s strength is autonomous, multi-step work across your codebase. Adding email as an MCP tool means Cascade can:
- Send progress notifications during long-running refactors or analyses (“refactoring complete, here’s the diff link”).
- Read incoming feedback via
mails_list_threadsmid-task and adapt the plan based on stakeholder input. - Triage and reply to PR review comments received as email notifications, by reading the typed event and acting on the
intentfield (intent requiresclassify_inbound, a paid-plan option). - Coordinate with humans across timezones — pause work, email a question, resume when the reply lands.
Setup
- Get an API key. Sign in at
app.mails.ai/api-keysand mint one — self-serve, free tier, no card. - Edit ~/.config/devin/mcp_config.json. Create the file if it doesn’t exist. Add the snippet from the install card. Replace
mk_live_...with your key. - Save the file. Open the Actions (...) menu in the Cascade panel and check its MCPs section to verify the server is registered with its tools listed.
- Choose the agent for customer mail. Per the docs, Cascade does not ask before MCP calls by default; the Devin Local agent does, so use it for customer mail.
First commands to test
# In Cascade
> What mails_* tools are available?
# Plan-mode test
> Plan a test email send: use mails_send to email myself "Cascade test".
# After approving the plan, Cascade executes
> Execute the plan.
# Verify
> Use mails_list_threads to confirm the test send.Common patterns
- Progress emails on long tasks. A Cascade task with many steps can email you as it goes — helps you verify progress without watching the IDE.
- A recipient rule for autonomous send. A Cascade rule can tell Cascade to send only to
@yourcompany.com; it guides the model and blocks nothing. - Memory-aware reply handling. When Cascade reads a thread via
mails_get_thread(every message in order), it may save a memory from mail it read, useful for multi-day stakeholder coordination. Review memories under Customizations.
Security considerations
- Approval mode discipline. Cascade’s autonomous loop is powerful. Per the docs, Cascade does not ask before MCP calls by default; the Devin Local agent does, so use it for customer mail.
- Volume cap via a Cascade rule. As well as the agent’s send limits, include “send no more than 5 emails per session” in a Cascade rule for any agent with mails_* tools enabled.
- Memory persistence + injection. If your agent reads an inbound with high
injection_score, Cascade may save a memory from mail it read. Even with the score-guard preventing action, the malicious payload sits in the agent’s context. Review memories under Customizations if you process suspicious inbound.
Compare against Cline, Continue, or Cursor for other MCP-runtime IDE setups.
Read next: Mails.ai for Cline and Mails.ai for Continue.
Questions developers ask after wiring this up.
Does Cascade auto-call mails_* tools without approval?
Cascade acts on its own. Will it spam my customers?
What about Windsurf’s memory / preview window features?
Does this work with the Windsurf Plugin for VS Code (formerly Codeium)?
“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.”
“The 422 on cold outreach is the feature I didn’t know I wanted. An agent can’t talk itself into emailing strangers.”
“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