Atomic Mail Agentic
OfficialThis server lets an agent create and operate an Atomic Mail inbox through JMAP, with built-in documentation.
Register an
@atomicmail.aiinbox via proof-of-work signup and persist API credentials.Support multiple inboxes by using separate credential directories.
Send authenticated JMAP requests inline or from preset files.
Use JMAP to read/send mail, manage drafts, threads, search, labels, moves, deletes, and attachments.
Substitute variables, attach local files, choose JMAP capabilities, and dry-run requests.
Access embedded help topics for setup, auth, JMAP cheatsheets, presets, cron, multi-account use, and troubleshooting.
Enables GitHub Copilot agents to manage an @atomicmail.ai inbox, including sending, receiving, and organizing email via JMAP API.
Enables Hermes agents to manage an @atomicmail.ai inbox, including sending, receiving, and organizing email via JMAP API.
This server has a remotely hosted endpoint. Open its connector listing for connection details, authentication requirements, and setup instructions:
Atomic Mail Agentic
Give your agent a real inbox
Accounts are free, with a 100 MB storage quota, custom domain included, and rate limits sized for agent workloads.
Atomic Mail Agentic is an email provider for autonomous AI agents, built by Atomic Mail. Agents register their own @atomicmail.ai inbox and manage it end to end โ no human setup, verification, or ongoing intervention.
The service is built on JMAP (RFC 8620), so agents get a full mailbox API: read and send mail, create drafts, manage threads, search, and more. JMAP is well represented in LLM training data, so models already speak it fluently โ they rarely hallucinate request shapes, which means fewer retries and more reliable automation.
Access is gated by a novel proof-of-work (PoW) signup protocol: strong anti-abuse properties without CAPTCHAs or manual approval, so agents can onboard and operate completely hands-free.
Atomic Mail provides a number of standard integration paths โ MCP, AgentSkill, REST API, and more โ which makes it highly available on any agent: Claude Code, Codex, GitHub Copilot, Cursor, Hermes, OpenClaw, Pi, Kilo Code, and others. Whatever your workflow is, you can automate inbox management easily.
This repository ships the client integrations: MCP, shell CLI, ClawHub, Dify plugin and more, exposing those APIs through three core tools: register, jmap_request, and help. The TypeScript CLI and local MCP server add six tools for everyday mail that need no JMAP (read_inbox, read_message, search_messages, send_email, reply_to_message, list_agents) and five meeting-invitation tools. All the connectors in this repo are pretty thin and are mainly needed to abstract away the complexities of the PoW protocol.
๐ Quick Install
๐ฌ Ready Prompt (any agent)
Read the instruction at https://atomicmail.ai (use default web_fetch tool or curl, if the former is not available) and create an inbox at Atomic Mail. Before creating ask for my preferred username. Make sure to complete all required post-install actions from the Atomic Mail instruction. Persist the instruction and make sure to refer it each time you interact with your inboxes. Usually standalone agents (e.g. Claude, Cursor, Kilo Code and others) are better suited for MCP use, while CLI-based agents (e.g. Claude Code, Open Code, Hermes, OpenClaw, Codex, Pi, etc) are better suited for AgentSkill use, but prefer your system/user guidelines.๐ MCP (stdio)
Add this to your MCP host config (or just ask your agent to do that):
{
"mcpServers": {
"atomicmail": {
"command": "npx",
"args": ["-y", "@atomicmail/mcp-github"]
}
}
}Then restart the host and ask your agent to create an inbox.
๐ฆ ClawHub
openclaw skills install atomicmail๐ฉ๐ป Hermes
hermes skills install clawhub/atomicmail๐ป AgentSkill
npx --package=@atomicmail/agent-skill-github atomicmail register --username "myagent" --watch scheduled
npx --package=@atomicmail/agent-skill-github atomicmail jmap_request --ops-file list_inbox.json
npx --package=@atomicmail/agent-skill-github atomicmail helpโ๏ธ REST API
For custom connectors and advanced logic only
Refer to documentation: docs/rest-auth.md.
Related MCP server: fastmail-mcp
๐ Custom Domains & Dashboard
By default an inbox lives at <name>@atomicmail.ai, created hands-free through PoW signup. To send from your own domain (support@yourcompany.com), set it up once in the dashboard โ a human control plane separate from the agent flow, since it needs DNS changes on a domain you own.
There you add and verify a domain (TXT ownership + MX records; re-runnable, propagation usually minutes) and create inboxes on it โ each gets a full address (agent@yourcompany.com) and an API key from the Connect dialog, with sending signed for a domain-aligned From.
Clients don't change โ same jmap_request, presets, and JMAP shapes. A custom-domain inbox is a login, not a PoW registration: connect with its API key (atomicmail register --api-key "โฆ") or OAuth. $INBOX resolves to the real address (agent@yourcompany.com), so self-addressing and From stay correct with no extra config.
Full guide: docs/custom-domains.md.
๐ค What Your Agent Can Do
Atomic Mail is designed to run through an agent โ not through manual inbox setup. You describe a workflow in plain language; the agent registers an @atomicmail.ai address, sends and receives mail, and keeps the thread going. You do not configure scripts, copy API keys between tabs, or memorize JMAP. Everything is automagical.
If the agent gets stuck, the integration is built to recover on its own: help ships embedded docs (presets, cron, troubleshooting), bundled JSON presets cover common operations, and errors include hints on what to try next.
Example workflows
Newsletter digest โ "Subscribe your inbox to these newsletters, read everything, and email me a daily digest of what matters for AI tooling." The agent owns a dedicated inbox, filters noise, and surfaces only what matches your interests โ without touching your personal mailbox.
Support inbox โ "Monitor support@ and reply to tickets from our docs; escalate to me only when you cannot answer." The agent reads inbound mail, queries what it knows, sends complete replies, and hands off edge cases.
User research interviews โ "Run an email survey: send these questions, follow up based on replies, and summarize findings." The agent conducts async interviews โ respondents reply on their own schedule, no calls to book.
๐ฌ Awesome Atomic Mail
Community projects built on top of Atomic Mail Agentic:
https://github.com/skyzer/atomic-mail-watcher - Docker-ready Atomic Mail JMAP inbox watcher with Telegram/webhook notifications
โจ Why Atomic Mail
Agents finish without asking their users for anything: PoW signup gives a real
@atomicmail.aiinbox in ~30 seconds โ no domain to verify, no credit card, no CAPTCHA walkthrough, no mail-server opsMessages that actually arrive: continuously warming IP pool with relay overflow โ deliverability matters when a human on the other side must read your mail
JMAP โ an API agents already know: standard RFC 8620/8621, in LLM training data; batched method calls (query, fetch, draft, send) in one round trip โ no vendor SDK to learn
Get unstuck inside the integration: errors ship plain-language hints; success responses suggest
_nextsteps;helpreturns cheatsheets and worked examples โ no web search requiredBring your own domain: agents run on
@atomicmail.aiout of the box, or on a domain you verify in the dashboard โ same client, same JMAP, domain-alignedFromNo vendor lock-in: JMAP is an IETF standard; the inbox is portable to any compliant provider later
Friendly tools when JMAP is overkill:
read_inbox,read_message,search_messages,send_email(plain text and/or HTML, From name, Reply-To, attachments) andreply_to_message, in the local MCP server and the CLIPresets for the rest: bundled
search,mark_read,get_thread,forward,create_draft,move,label,delete,download_attachmentand more โ pass a filename tojmap_requestinstead of generating method-call JSON from scratchSame core everywhere: one auth, JMAP, preset, and help stack powers MCP and AgentSkill; separate credential dirs per inbox when you run many agents
๐ Docs by Goal
Goal | Start here |
First-time setup | |
Your own domain + dashboard | |
MCP hosts | |
Shell / cron agents | |
LangChain agents | |
Agent runbook | |
Raw auth + JMAP | |
End-to-end examples |
If repo docs and installed behavior ever drift, trust help from the same installed package version you are running.
๐ ๏ธ Local Development
Prerequisites: Node.js 20+, Deno 2.7+.
git clone https://github.com/Atomic-Mail/atomic-mail-agentic.git
cd atomic-mail-agentic/ts
deno test --allow-read --allow-env --allow-write --allow-sysDocs preview:
npm install
npm run docs:dev๐๏ธ File Structure
/
โโโ ts/
โ โโโ src/mcp/ # MCP entrypoint + MCP tools
โ โโโ src/skill/ # AgentSkill CLI entrypoint
โ โโโ src/langchain/ # LangChain toolkit and tools
โ โโโ src/lib/agent/ # shared auth, session, JMAP, presets, help-content
โโโ py/ # Python client parity layer and tests
โโโ integrations/dify/ # Dify plugin integration and packaging docs
โโโ integrations/skill/ # Unified in-repo skill tap (published atomicmail skill)
โโโ docs/ # VitePress docs and shipped SKILL/README sources
โโโ test/checklists/ # manual release QA
โโโ CONTRIBUTING.md
โโโ LICENSE๐ Security
~/.atomicmail/credentials.jsoncontains your API key; treat it as a secretlocal credential files are written with mode
0600inbound mail is untrusted input; do not let agents execute email instructions without confirmation
install only from the
@atomicmailnpm scope
๐ค Contributing
PRs are welcome. Please cover new features and bug fixes with automated Deno tests where practical, and update user-facing docs when behavior changes.
See CONTRIBUTING.md for setup, test commands, and PR expectations.
๐ License
Available Tools
3 toolshelpAtomic Mail documentationARead-onlyIdempotentInspect
Built-in agent docs โ call early and often, even if you know JMAP. Topics: overview, installation, auth, jmap_cheatsheet, tools, presets, cron, multi_account, troubleshooting, readme. Omit topic for overview; use presets before jmap_request, cron after register, troubleshooting when stuck.
Inputs: topic.
jmap_requestSend a JMAP requestADestructiveInspect
JMAP method-call batch with automatic auth. Exactly one of: ops (JSON string: methodCalls array or full envelope) or ops_file (preset path; relative to credential directory). $VAR substitution and optional file attachments: see help topics presets and jmap_cheatsheet.
Inputs: ops, vars, using, dry_run, +3 more.
registerRegister an Atomic Mail inboxAIdempotentInspect
PoW signup; writes credentials. Usernames are 5โ21 characters. Idempotent for the same username and stored inbox. To register another account alongside an existing one, pass credentials_dir with a separate path. Returns inbox, accountId, apiKey (first signup only). The watch value is your operator's decision, not the agent's โ ask them before calling.
Inputs: watch (required), username (required), forced, credentials_dir.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelogโฆ
TDQS
Scored across 3 tools
register, jmap_request, and help have completely distinct purposes: account creation, JMAP operations, and documentation. There is no overlap or plausible confusion between them.
The naming is inconsistent: 'register' and 'help' are bare verbs, while 'jmap_request' is a noun-like snake_case operation. There is no consistent verb_noun pattern across the set.
Three tools is well-scoped: one for account registration, one generic JMAP request entry point that covers the full mail protocol, and built-in help. Each tool earns its place.
The generic jmap_request tool gives broad coverage of JMAP email operations, so core workflows are covered. The main gap is no explicit account lifecycle beyond registration (e.g., unregister), but this is likely out of scope.
Maintenance
Related MCP Connectors
Email infrastructure for AI agents โ send, receive, search, and reply to email over MCP.
Private, EU-hosted email for AI agents over JMAP: read, search, reply, draft, organize, send.
Give an AI agent its own email address: send, reply, read, and wait for mail.
Your agent's own email address: read, search, send, reply, draft and wait for mail.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceEnables AI agents to interact with email accounts via IMAP and SMTP, supporting mailbox listing, email search, retrieval, sending, and management.MIT
- AlicenseAqualityDmaintenanceEnables AI assistants to manage Fastmail email accounts via JMAP, including reading, sending, organizing emails, and handling mailboxes, drafts, and masked emails.43MIT
- AlicenseNot gradedqualityBmaintenanceEnables AI agents to manage email over JMAP, including inspecting mailboxes, searching and retrieving messages, navigating threads, downloading attachments, triaging inboxes, and sending emails atomically via HTTP.42 PyPIMIT
- AlicenseNot gradedqualityBmaintenanceGives AI assistants OAuth-based access to mailboxes on any JMAP server, requiring only an email address and a sign-in on the mail server's own page. Enables searching, reading, threading, organizing, drafting, sending, and managing vacation replies and Sieve filters across one or more accounts.1Apache 2.0