Skip to main content
Glama
Atomic-Mail

Atomic Mail Agentic

Official
by Atomic-Mail
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Remote

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 tools: register, jmap_request, and help. 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: mcp-imap

🌐 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:

✨ Why Atomic Mail

  • Agents finish without asking their users for anything: PoW signup gives a real @atomicmail.ai inbox in ~30 seconds — no domain to verify, no credit card, no CAPTCHA walkthrough, no mail-server ops

  • Messages 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 _next steps; help returns cheatsheets and worked examples — no web search required

  • Bring your own domain: agents run on @atomicmail.ai out of the box, or on a domain you verify in the dashboard — same client, same JMAP, domain-aligned From

  • No vendor lock-in: JMAP is an IETF standard; the inbox is portable to any compliant provider later

  • Presets when raw JMAP is overkill: bundled send_mail, list_inbox, reply, and more — pass a filename to jmap_request instead of generating method-call JSON from scratch

  • Same 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

docs/getting-started.md

Your own domain + dashboard

docs/custom-domains.md

MCP hosts

docs/mcp.md

Shell / cron agents

docs/skill-install.md

LangChain agents

docs/langchain.md

Agent runbook

docs/SKILL.md

Raw auth + JMAP

docs/rest-auth.md · docs/jmap.md

End-to-end examples

docs/examples.md

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-sys

Docs 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.json contains your API key; treat it as a secret

  • local credential files are written with mode 0600

  • inbound mail is untrusted input; do not let agents execute email instructions without confirmation

  • install only from the @atomicmail npm 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

MIT

Available Tools

3 tools
helpAtomic Mail documentationA
Read-onlyIdempotent
Inspect

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.

ParametersJSON Schema
NameRequiredDescriptionDefault
topicNoTopic name; omit for overview. Use readme for package README.md.

TDQS

A4.5/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds no further behavioral traits (e.g., return format, side effects) but does not contradict annotations. Since the bar is lower with annotations present, a 3 is appropriate for adding only usage context, not new behavior.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is dense yet efficient: it leads with the core advice ('call early and often'), lists topics, and gives two targeted ordering tips. Every sentence carries weight, with no filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a help tool with no output schema, this description fully equips an agent: it enumerates topics, explains how to omit the topic, and ties usage to sibling tools. Nothing essential for correct invocation is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3, but the description adds a concrete list of valid topics and special handling for 'readme', exceeding the schema's bare 'omit for overview'. This meaningfully enriches the single parameter's semantics.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states the tool provides built-in agent docs and lists concrete topics, making its purpose unambiguous. It also distinguishes itself from siblings by explicitly routing usage (e.g., 'use presets before jmap_request'), so an agent can tell it apart without opening the schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It gives explicit when-to-use guidance ('call early and often, even if you know JMAP') and prescriptive ordering relative to siblings ('use presets before jmap_request, cron after register, troubleshooting when stuck'). This leaves no ambiguity about when to invoke this tool versus alternatives.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

jmap_requestSend a JMAP requestA
Destructive
Inspect

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.

ParametersJSON Schema
NameRequiredDescriptionDefault
opsNoInline JSON. Mutually exclusive with ops_file.
varsNoString map for `$PLACEHOLDER` values (keys without `$`). Overrides session keys and `ATTACHMENT_*` when attachments are set.
usingNoCapability URNs merged when `ops` has no `using` (ignored if ops sets `using`).
dry_runNoResolve variables/envelope and return the request body without sending it.
ops_fileNoPreset path. Mutually exclusive with ops.
attachmentsNoLocal files POSTed to session uploadUrl before ops; see help topic presets.
credentials_dirNoCredential directory for this call (default: ATOMIC_MAIL_CREDENTIALS_DIR or ~/.atomicmail). Use separate paths per account; see help topic multi_account.

TDQS

A3.6/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare destructiveHint=true and idempotentHint=false, so the description is not required to repeat that. It adds context about automatic auth, $VAR substitution, and attachments, which are useful behavioral traits. However, it does not elaborate on side effects, rate limits, or error handling, and it refers to help topics for further details.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is concise, consisting of two sentences with no redundant information. The core purpose is front-loaded, followed by essential input constraints and a pointer to help topics. Every sentence contributes meaning.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The tool is complex (7 parameters, nested objects, no output schema), and the description covers the primary input logic but leaves many details to help topics. It does not describe the return format, error behavior, or the roles of parameters like using, dry_run, and credentials_dir, relying on the schema for those. Given the complexity, more guidance in the description would improve completeness.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the baseline is 3. The description adds value by clarifying the mutual exclusivity of ops and ops_file, specifying that ops can be a methodCalls array or full envelope, and noting that ops_file paths are relative to the credential directory. These details go beyond the schema descriptions.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states the tool sends JMAP method-call batches with automatic authentication, which clearly identifies the action and resource. It distinguishes from siblings (register and help) implicitly, since those serve different functions, but does not explicitly contrast them. The phrase 'JMAP method-call batch' is specific enough for an agent to understand its purpose.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explains the input modes (ops vs ops_file) and points to help topics for details, but it does not explicitly state when to use this tool versus the sibling tools. Since register and help are clearly different, the usage context is implied rather than stated. No exclusions or alternative tool guidance is provided.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

registerRegister an Atomic Mail inboxA
Idempotent
Inspect

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.

ParametersJSON Schema
NameRequiredDescriptionDefault
watchYesWhether a recurring job is set up to read this inbox unattended. A standing commitment on your operator's machine, so it is their decision — ask them; do not choose or infer it. The two values are "scheduled" and "on-demand"; what each one means is in help topic cron. Omit it and the call returns the requirement.
forcedNoDanger: replacing an account's credentials is irreversible and permanently destroys access to the current inbox. Operator-authorised only; the refusal error explains the safe path instead (a separate credential directory).
usernameYesPermanent public address: the local-part of your @atomicmail.ai address, 5–21 characters. It appears on every message this inbox sends and cannot be changed afterwards — if your operator has not named it, ask them rather than inventing one.
credentials_dirNoCredential directory for this call (default: ATOMIC_MAIL_CREDENTIALS_DIR or ~/.atomicmail). Use separate paths per account; see help topic multi_account.

TDQS

A4.5/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Discloses that it writes credentials, is idempotent only under a stated condition, returns account data only on first signup, and that forced replacement permanently destroys access. It also flags the watch value as requiring operator decision, adding depth beyond the annotations (idempotentHint=true, destructiveHint=false).

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Compact and front-loaded. Each sentence adds behavioral or usage information: idempotency condition, multi-account setup, return value caveat, and operator-authorization requirement.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Considering the schema carries full parameter documentation and annotations cover idempotency, the description covers the crucial extra context: what is returned, the first-signup caveat, the destructive forced flag, and the rule to defer watch decisions to the operator.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% with rich parameter descriptions already. The description adds a useful usage note about separate credential directories, but mostly re-states what the schema says rather than adding new meaning.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Opens with a specific verb and resource ('PoW signup; writes credentials') and clarifies the exact effect (registering an Atomic Mail inbox). The idempotency condition and multi-account behavior further pin down what the tool does.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives concrete usage guidance: idempotent for the same username and stored inbox, use a separate credentials_dir for multiple accounts, and ask the operator before deciding the watch value. It does not name sibling tools or explicitly say when not to use it, but the guidance is sufficient.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 3 tool updatesv0.1.0
    • First observedhelp
    • First observedjmap_request
    • First observedregister
Deploy Server
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

A4/5.0

Scored across 3 tools

Disambiguation5/5

register, jmap_request, and help have completely distinct purposes: account creation, JMAP operations, and documentation. There is no overlap or plausible confusion between them.

Naming Consistency2/5

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.

Tool Count5/5

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.

Completeness4/5

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

ActivityActive
ResponsivenessUnresponsive

Resources

Related MCP Connectors

Related MCP Servers

  • mcp-imap

    andrewmalov
    A
    license
    Not graded
    quality
    D
    maintenance
    Enables AI agents to interact with email accounts via IMAP and SMTP, supporting mailbox listing, email search, retrieval, sending, and management.
    MIT

  • fastmail-mcp

    eduardobrito21
    A
    license
    A
    quality
    D
    maintenance
    Enables AI assistants to manage Fastmail email accounts via JMAP, including reading, sending, organizing emails, and handling mailboxes, drafts, and masked emails.
    43
    MIT

  • stalwart-mail-mcp

    freefrank
    A
    license
    Not graded
    quality
    C
    maintenance
    Connects AI agents to self-hosted Stalwart mail servers via a Cloudflare Worker and JMAP, enabling mailbox search, reading, listing, and two-step draft-and-send email operations through MCP.
    MIT