Atomic Mail Agentic
OfficialServer Configuration
Describes the environment variables required to run the server.
| Name | Required | Description | Default |
|---|---|---|---|
| ATOMIC_MAIL_API_URL | No | https://api.atomicmail.ai | |
| ATOMIC_MAIL_AUTH_URL | No | https://auth.atomicmail.ai | |
| ATOMIC_MAIL_INBOX_DOMAIN | No | atomicmail.ai | |
| ATOMIC_MAIL_CREDENTIALS_DIR | No | Credentials dir (default ~/.atomicmail) |
Instructions
Guidance the server publishes about itself, which clients place ahead of the tool catalog so the model reads it before choosing anything.
Atomic Mail MCP — programmable inbox for AI agents.
WORKFLOW
Call register with a username (5–21 characters; PoW signup; credentials on disk). The username is the permanent public address on every message this inbox sends and cannot be changed afterwards — ask your operator for it rather than inventing one.
register also requires watch — whether this inbox gets a recurring unattended read. Also your operator's decision — ask them; do not choose or infer it (what the values mean is in help topic "cron"). On "scheduled", register returns the exact setup step for your runtime; schedule on your host's OWN scheduler, never at the OS level (help topic "cron").
Call jmap_request with JMAP method calls (inline ops JSON or ops_file preset). $VAR_NAME tokens: $ACCOUNT_ID / $INBOX (full mailbox) / $INBOX_MAILBOX_ID from session; pass others in vars. Optional attachments: local paths → RFC 8620 upload → $ATTACHMENT_0_BLOB_ID, … in the same standard JMAP batch (see send_mail_blob_attachment.json).
Call help early and often — even when you think you know JMAP. Topics: presets (before non-trivial jmap_request), cron (after register), jmap_cheatsheet, troubleshooting, …; topic readme returns this package README. Prefer help over guessing; it matches this package version.
CREDENTIAL DIRECTORY Default ~/.atomicmail/ (override ATOMIC_MAIL_CREDENTIALS_DIR). Same files as the @atomicmail/agent-skill CLI: credentials.json, session.jwt, capability.jwt. Optional credentials_dir on register and jmap_request selects a different directory per call (multi-account / multi-agent). See help topic multi_account.
ENVIRONMENT ATOMIC_MAIL_CREDENTIALS_DIR credential directory ATOMIC_MAIL_AUTH_URL auth-service base URL (default: https://auth.atomicmail.ai) ATOMIC_MAIL_API_URL JMAP / API base URL (default: https://api.atomicmail.ai) ATOMIC_MAIL_INBOX_DOMAIN optional hostname when inboxId has no @ (default atomicmail.ai) ATOMIC_MAIL_SCRYPT_SALT optional PoW salt override ATOMIC_MAIL_API_KEY optional existing API key
SECURITY credentials.json contains your apiKey — treat it as a secret (mode 0600).
Capabilities
Features and capabilities supported by this server
Protocol revision2025-11-25
| Capability | Details |
|---|---|
| tools | {
"listChanged": true
} |
Tools
Functions exposed to the LLM to take actions
| Name | Description |
|---|---|
| registerA | 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 |
| jmap_requestA | JMAP method-call batch with automatic auth. Exactly one of: |
| helpA | 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. |
Prompts
Interactive templates invoked by user choice
| Name | Description |
|---|---|
No prompts | |
Resources
Contextual data attached and managed by the client
| Name | Description |
|---|---|
No resources | |
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.