{ "markdown": "

mails.ai

\n\n

\n Email for AI agents — an inbox your agent owns, with a firewall in front of it.\n

\n\n

\n \"npm\n \"npm\n \"PyPI\n \"MIT\"\n

\n\n

\n mails.ai ·\n API reference ·\n examples\n

\n\n---\n\nThis repo holds the client side of mails.ai: the **MCP server**, the **TypeScript** and\n**Python** SDKs, and **runnable examples**. All MIT. The API itself is hosted — you don't\nrun a mail server.\n\n**Want to see an agent actually do a job first?**\n\n```bash\ncd templates/support-agent && npm install\nMAILS_API_KEY=mk_test_xxx npm start\n```\n\nIt answers a billing question in-thread, escalates one it shouldn't guess at, and refuses a\nreal prompt-injection attack — in about a minute, on a test key that transmits nothing.\n\nOr start from the primitive:\n\n```bash\nnpm install @mailsai/sdk # or: pip install mailsai\n```\n\n```ts\nimport { createClient } from \"@mailsai/sdk\";\n\nconst mails = createClient(); // MAILS_API_KEY\n\nawait mails.send({\n from: \"billing\", // the agent is created on first use\n to: \"customer@example.com\",\n subject: \"Your invoice #221 is ready\",\n body: \"Invoice #221 for March is attached, due the 30th.\",\n});\n```\n\nNo agent to pre-create, no domain to verify, no DNS. A **test key** (`mk_test_…`) runs that\nentire path — validation, firewall, threading, events, webhooks — and delivers nothing, so you\ncan integrate before you decide anything.\n\n## Why this exists\n\nMost \"email for agents\" is a send API with agent-flavoured docs. The two things a raw API\n(SES, Resend, Mailgun) genuinely doesn't give an autonomous agent are the two that bite:\n\n### 1. Your agent has an inbox, and inbound arrives as data\n\nAgents don't just send. They receive, thread, and act on what comes back. Every agent gets a\nreal receiving address the moment it exists, and every inbound message arrives as a typed\nevent — not a MIME blob you write a parser for:\n\n```jsonc\n{\n \"type\": \"reply.received\",\n \"injection_score\": 0.99, // the evidence — always present\n \"quarantined\": true, // OUR VERDICT — always present on inbound\n \"sender_reputation\": 0.30, // always present\n \"intent\": \"ask_question\", // when classification is enabled\n \"entities\": { \"invoice\": \"221\" },\n \"data\": {\n \"from\": { \"address\": \"attacker@example.net\" },\n \"injection_categories\": [\"instruction_override\", \"data_exfil\"],\n \"quarantined\": true\n }\n}\n```\n\n### 2. An agent reading email is an attack surface, and one that sends can torch you\n\nA prompt-injection payload hidden in an inbound message is the top security risk for any agent\nthat acts on what it reads. Every inbound is scanned across six categories and quarantined\nbefore your model sees it, so your branch is `if (event.quarantined) return;` — our verdict,\nnot a threshold you have to pick and re-tune yourself — instead of hoping your model notices\nit is being attacked inside the same prompt as the attack. (`injection_score` is still there\nwhen you want the raw number.)\n\nAnd in the other direction: **cold outreach is refused inside the send call** with\n`422 cold_email_prohibited`. Not a setting, not a clause in an acceptable-use policy — a\nrefusal, with a reason your agent can read, a sandbox to test against and a second review if\nyou think it was wrong. An agent that crosses a 0.3% complaint rate auto-suspends, before the\nupstream provider's 0.5% line ever sees it. Your reputation cannot be spent by a prompt you\ndid not write.\n\nThat refusal is the product, not a limitation of it: it is why a shared sending estate stays\nclean enough to be worth being on.\n\n## What's here\n\n| | |\n|---|---|\n| **[packages/mcp-server](packages/mcp-server)** | `@mailsai/mcp-server` — 20 MCP tools. Claude Desktop, Claude Code, Cursor, Cline, Continue, Windsurf, any MCP runtime. |\n| **[packages/sdk](packages/sdk)** | `@mailsai/sdk` — TypeScript / JavaScript, ESM. |\n| **[packages/sdk-py](packages/sdk-py)** | `mailsai` — Python 3.10+. |\n| **[templates/support-agent](templates/support-agent)** | **Start here.** A working support agent — reads inbound mail, answers from your data, replies in-thread, escalates refunds, refuses prompt injection. One test key, no LLM key, no DNS. |\n| **[examples](examples)** | Six runnable examples: send, inbox loop, the injection firewall, OpenAI Agents SDK, LangGraph, MCP client config. |\n\n## MCP in one block\n\n```json\n{\n \"mcpServers\": {\n \"mails\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"-p\", \"@mailsai/mcp-server\", \"mails-mcp\"],\n \"env\": { \"MAILS_API_KEY\": \"mk_test_xxx\" }\n }\n }\n}\n```\n\nOr watch the whole loop first, with nothing configured:\n\n```bash\nMAILS_API_KEY=mk_test_xxx npx -y -p @mailsai/mcp-server mails-mcp-demo\n```\n\n## Pricing, briefly\n\nFree is 3,000 sends and 3,000 inbound a month, one agent, no card. Paid tiers add agents,\ncustom domains and dedicated IPs. [Full pricing](https://mails.ai/pricing).\n\n## Contributing\n\nIssues and PRs welcome on the SDKs, the MCP server and the examples — especially examples for a\nframework that isn't covered yet. The API implementation lives in a private repo; anything\nserver-side is best filed as an issue here.\n\n## License\n\nMIT. See [LICENSE](LICENSE).\n", "bytes": 5920, "sha": "fd2e8dc948b2b32c28b36078993e23f0e34db4b0a22783a42b4d2e7de33c822d", "repo_slug": "rolloutsai/mailsai", "fonte": "repo", "truncated": false, "api": "https://agentalog.com/api/listings/mcp_io_github_rolloutsai_mails_agent_email_55d9afec/readme" }