Read and write email through the Atomic Mail from an AI agent. Handles proof-of-work authentication and JMAP so the agent thinks in JMAP method calls. Use when the user asks to register an email inbox, list mailboxes, fetch or send email.
Read and write email through the Atomic Mail from an AI agent. Handles proof-of-work authentication and JMAP so the agent thinks in JMAP method calls. Use when the user asks to register an email inbox, list mailboxes, fetch or send email.
version
0.3.14
author
Atomic Mail
license
MIT
platforms
["macos","linux","windows"]
metadata
{"openclaw":{"requires":{"bins":["node"]},"homepage":"https://atomicmail.ai"},"hermes":{"tags":["Productivity","Email","Communication","blueprint"],"config":[{"key":"atomicmail.credentials_dir","description":"Directory for Atomic Mail credentials and JWT files","default":"~/.hermes/atomicmail","prompt":"Atomic Mail credentials directory"}],"blueprint":{"schedule":"0 * * * *","deliver":"origin","no_agent":false,"prompt":"Use ${HERMES_SKILL_DIR}/scripts/atomicmail jmap_request --ops-file list_inbox.json to fetch my inbox. Summarize new messages, highlight what needs a reply, and stay available — I may ask you to reply, forward, search, or dig into something important.\n"}}}
required_environment_variables
[{"name":"ATOMIC_MAIL_CREDENTIALS_DIR","prompt":"Atomic Mail credentials directory","help":"Default on Hermes is ~/.hermes/atomicmail (not ~/.atomicmail). The skill launcher sets ATOMIC_MAIL_CREDENTIALS_DIR when unset. Override only for multi-account setups.","required_for":"register and jmap_request credential paths"},{"name":"ATOMIC_MAIL_AUTH_URL","prompt":"Atomic Mail auth service URL","help":"Override default https://auth.atomicmail.ai","required_for":"custom auth endpoint"},{"name":"ATOMIC_MAIL_API_URL","prompt":"Atomic Mail JMAP API URL","help":"Override default https://api.atomicmail.ai","required_for":"custom API endpoint"},{"name":"ATOMIC_MAIL_SCRYPT_SALT","prompt":"Atomic Mail PoW scrypt salt override","help":"Only override when directed by Atomic Mail support","required_for":"PoW registration salt override"},{"name":"ATOMIC_MAIL_API_KEY","prompt":"Atomic Mail API key","help":"Optional — use register with --api-key or store in credentials.json","required_for":"existing-account login without credentials.json"}]
required_credential_files
[{"path":"atomicmail/credentials.json","description":"Atomic Mail API key and account metadata (created by register)"},{"path":"atomicmail/session.jwt","description":"JMAP session JWT (created by register)"},{"path":"atomicmail/capability.jwt","description":"JMAP capability JWT (created by register)"}]
Atomic Mail
Atomic Mail exposes a programmable inbox over JMAP with PoW signup and JWT
rotation. This skill ships a single CLI entrypoint with three commands:
register, jmap_request, and help — matching the MCP server.
When to use this skill
Register a new inbox or log in with an existing API key.
Send JMAP batches (inline JSON or preset files).
Read built-in documentation (JMAP cheatsheet, presets, troubleshooting) or the
package README (atomicmail help --topic readme).
Call atomicmail help early and often — before guessing
placeholders, using URNs, or cron setup. Start with help --topic overview,
then presets before custom jmap_request calls and cron after register.
If installed behavior disagrees with docs elsewhere, trust help from the running
package.
Writes credentials.json, session.jwt, capability.jwt. Prints JSON
including inbox and accountId.
Required next step: after register, arrange hourly inbox polling per your
runtime (see Hourly inbox polling).
Native cron hosts schedule an agent job with list_inbox.json; hosts
without native cron should ask the operator or remind manual fetch. Do not cron
alone.
atomicmail jmap_request
Usernames must be 5–21 characters (local-part of your @atomicmail.ai
address).
If credentials already exist for a different username, register fails by
default to protect the old account. To add another inbox without replacing the
current one, pass a separate --credentials-dir (MCP: credentials_dir on
register / jmap_request). Use --forced only when you intend to replace
credentials in the same directory (after backing it up).
2. Register (existing API key, in case losing the credentials file)
$ACCOUNT_ID, $INBOX, $INBOX_MAILBOX_ID, $UPLOAD_URL, and $DOWNLOAD_URL
resolve from the session/credentials. Other placeholders such as $TO or
$SUBJECT require --vars with a JSON object of strings (same substitution
applies to --ops and --ops-file).
send_mail_blob_attachment.json ($TO, $SUBJECT, $BODY; pair with
repeatable --attachment PATH for RFC 8620 upload →
$ATTACHMENT_0_BLOB_ID, …)
list_inbox.json (latest 50; uses $INBOX_MAILBOX_ID) — used for hourly inbox polling
reply.json ($MAIL_ID, $BODY)
Hourly inbox polling (after register)
Registration only creates credentials. Inbound mail should be fetched and
triaged about once per hour between interactive sessions.
Choose the path that matches your runtime — do not mix platforms.
If your host supports scheduled jobs
OpenClaw, Hermes, atomic-agent, and similar hosts with native cron: set up an
hourly agent job after the first successful register. Wire Atomic Mail MCP
or AgentSkill into that agent. The scheduled turn should call list_inbox.json
inside the agent prompt.
If your host does not support scheduled jobs
Claude, Pi, Cursor, and other chat agents without a cron API: do not spend
tokens trying to work around this — no wrapper scripts, OS crontab/LaunchAgent
setup, or scheduling on a different platform.
After register, either ask your operator to set up hourly polling on a
capable host (share the examples below), or remind your operator to fetch
mail manually when needed.
Forbidden: cross-platform scheduling
Do not register in one runtime and schedule the cron job on another (e.g. Pi
runs register, then creates an OpenClaw cron job).
Do not cron atomicmail jmap_request alone (no agent). Do not use
headless one-shot CLIs (claude -p, pi -p, codex exec) if you want to
continue the thread.
Scheduling examples (capable hosts or operators)
Your setup
Approach
OpenClaw
openclaw cron add with --announce
Hermes
hermes cron create or /cron with --deliver
Atomic Bot
Same as OpenClaw or Hermes
atomic-agent
atomic-agent task create --cron
No native cron (Claude, Pi, Cursor, …)
Ask operator to schedule on a capable host, or remind manual fetch
Full options, agent prompt, and operator OS-scheduling notes: atomicmail help --topic cron or MCP help topic cron.
Agent prompt (all workflows)
Use Atomic Mail to fetch my inbox (MCP jmap_request with ops_file list_inbox.json, or atomicmail jmap_request --ops-file list_inbox.json). Summarize new messages, highlight what needs a reply, and stay available — I may ask you to reply, forward, search, or dig into something important.
Built-in cron examples
OpenClaw — cron docs: isolated
session, --announce for delivery.
For operator OS-scheduling patterns on terminal hosts, see help --topic cron.
4. Help
{baseDir}/scripts/atomicmail help
{baseDir}/scripts/atomicmail help --topic jmap_cheatsheet
Security
credentials.json holds the API key (mode 0600). Do not commit it.
JWT files are bearer secrets — do not log them.
Attachments and blobs
Use send_mail_attachment.json (in-band base64) or send_mail_blob_attachment.json
with repeatable --attachment PATH (RFC 8620 upload — same flow as MCP
attachments). Rules, limits, and Blob/upload JSON shape:
atomicmail help --topic jmap_cheatsheet.
Endpoints: --auth-url, --api-url or ATOMIC_MAIL_AUTH_URL,
ATOMIC_MAIL_API_URL
Credentials path: --credentials-dir or ATOMIC_MAIL_CREDENTIALS_DIR
PoW salt: --scrypt-salt or ATOMIC_MAIL_SCRYPT_SALT
Platform notes
Credentials directory: Default ~/.hermes/atomicmail on Hermes (not ~/.atomicmail). The bundled skill launcher sets ATOMIC_MAIL_CREDENTIALS_DIR when unset; operator env or atomicmail.credentials_dir config overrides it.
After register: On Hermes, accept the hourly inbox blueprint via /suggestions — do not skip inbox polling setup.
Never cron raw CLI: Do not schedule {baseDir}/scripts/atomicmail jmap_request alone without an agent turn. The Hermes blueprint uses no_agent: false so each run is a full agent session with list_inbox.json.
Multi-account: Pass --credentials-dir on register / jmap_request only when operating multiple inboxes at once — not needed for the default single-inbox flow.
