Atomicmail

---
name: atomicmail
description: 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.
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.

## Commands

```bash
{baseDir}/scripts/atomicmail register --username "myagent"

{baseDir}/scripts/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)

```bash
{baseDir}/scripts/atomicmail register \
  --username "alice"
```

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](#hourly-inbox-polling-after-register)).
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
`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 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)

```bash
{baseDir}/scripts/atomicmail register \
  --api-key "..."
```

### 3. JMAP request

```bash
{baseDir}/scripts/atomicmail jmap_request \
  --ops '[["Mailbox/get", {"accountId": "$ACCOUNT_ID"}, "m0"]]'
```

`$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`).

Preset file:

```bash
{baseDir}/scripts/atomicmail jmap_request \
  --ops-file list_inbox.json
```

With custom placeholders:

```bash
{baseDir}/scripts/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 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)

```text
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](https://docs.openclaw.ai/automation/cron-jobs): isolated
session, `--announce` for delivery.

**Hermes** — [cron docs](https://hermes-agent.nousresearch.com/docs/user-guide/features/cron):
`--deliver origin` (or `telegram`, `discord`, `email`, …); not `--no-agent`.

**atomic-agent** — `atomic-agent task create --cron "0 * * * *" --message "<prompt>"`

For operator OS-scheduling patterns on terminal hosts, see `help --topic cron`.

### 4. Help

```bash
{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`**.

```bash
{baseDir}/scripts/atomicmail jmap_request \
  --ops-file send_mail_attachment.json \
  --vars '{"TO":"you@example.com","SUBJECT":"Hi","BODY":"See file","ATTACHMENT_BASE64":"SGVsbG8=","ATTACHMENT_TYPE":"text/plain","ATTACHMENT_NAME":"note.txt"}'
```

## Overriding defaults

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