Atomicmail

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). In this skill runtime, atomicmail help --topic readme intentionally returns a short stub.

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.

Commands

npx --package=@atomicmail/agent-skill atomicmail register --username "myagent" --watch scheduled

npx --package=@atomicmail/agent-skill atomicmail jmap_request --ops-file list_inbox.json

Run atomicmail --help or atomicmail <command> --help for flags.

Defaults

• authUrl: https://auth.atomicmail.ai
• apiUrl: https://api.atomicmail.ai
• credentials directory: ~/.atomicmail

Workflow

1. Register (new account)

npx --package=@atomicmail/agent-skill atomicmail register \
  --username "alice" \
  --watch scheduled

--watch is required — it is your operator's decision, not yours; ask them. Run register with no --watch to see the accepted values (each is a real choice about how the operator works, so neither is a safe default to guess). On the scheduling value, register prints the per-host schedule setup command.

Writes credentials.json, session.jwt, capability.jwt. Prints JSON including inbox and accountId.

Required next step: the watch value decides who reads the inbox (see Inbox checks). On scheduled, schedule a daily agent turn with list_inbox.json on your runtime's own scheduler — never at the OS level, and never cron atomicmail jmap_request alone.

Usernames must be 5–21 characters (local-part of your @atomicmail.ai address).

If credentials already exist for a different username, register refuses to run, which protects the old account. To add another inbox without replacing the current one, pass a separate --credentials-dir (MCP: credentials_dir on register / jmap_request) — that is the supported path, and the only one you should reach for. Replacing the credentials in a directory permanently destroys access to that inbox; there is no normal flag for it, and the refusal error is where the operator-authorised escape hatch is spelled out.

2. Register (existing API key, in case losing the credentials file)

npx --package=@atomicmail/agent-skill atomicmail register \
  --api-key "..."

3. JMAP request

npx --package=@atomicmail/agent-skill atomicmail jmap_request \
  --ops '[["Mailbox/get", {"accountId": "$ACCOUNT_ID"}, "m0"]]'

$ACCOUNT_ID, $INBOX, $INBOX_MAILBOX_ID, $SENT_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).

Preset file:

npx --package=@atomicmail/agent-skill atomicmail jmap_request \
  --ops-file list_inbox.json

With custom placeholders:

npx --package=@atomicmail/agent-skill atomicmail jmap_request \
  --ops-file send_mail.json \
  --vars '{"TO":"alice@example.com","SUBJECT":"Hello","BODY":"Hi there"}'

Bundled presets (no local file creation required):

• send_mail.json ($TO, $SUBJECT, $BODY)
• send_mail_attachment.json ($TO, $SUBJECT, $BODY, $ATTACHMENT_BASE64, $ATTACHMENT_TYPE, $ATTACHMENT_NAME)
• 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 the scheduled inbox check
• list_sent.json (latest 50 the agent sent; uses $SENT_MAILBOX_ID) — send presets file their copy in Sent with $draft cleared, so it never shows in the inbox
• reply.json ($MAIL_ID, $BODY)

Inbox checks (after register)

Registration only creates credentials. Nothing reads the inbox until something wakes an agent to do it — that is what the required watch value decides, and it is your operator's call, not yours:

• scheduled — a recurring job wakes an agent once a day to read the inbox and report what arrived.
• on-demand — no such job; mail is read only when a human asks, and anything arriving in between sits unread with nobody told.