atomicmail

Files (167)

• SKILL.md
• _dnt.polyfills.d.ts · lib/esm/
• _dnt.polyfills.d.ts.map · lib/esm/
• _dnt.polyfills.js · lib/esm/
• agent-auth-http.d.ts · lib/esm/lib/agent/auth/
• agent-auth-http.d.ts.map · lib/esm/lib/agent/auth/
• agent-auth-http.js · lib/esm/lib/agent/auth/
• agent-jwt.d.ts · lib/esm/lib/agent/auth/
• agent-jwt.d.ts.map · lib/esm/lib/agent/auth/
• agent-jwt.js · lib/esm/lib/agent/auth/
• agent-pow.d.ts · lib/esm/lib/agent/auth/
• agent-pow.d.ts.map · lib/esm/lib/agent/auth/
• agent-pow.js · lib/esm/lib/agent/auth/
• agent-utm.d.ts · lib/esm/lib/agent/auth/
• agent-utm.d.ts.map · lib/esm/lib/agent/auth/
• agent-utm.js · lib/esm/lib/agent/auth/
• agent-help-content.d.ts · lib/esm/lib/agent/jmap/
• agent-help-content.d.ts.map · lib/esm/lib/agent/jmap/
• agent-help-content.js · lib/esm/lib/agent/jmap/
• agent-jmap-blob-limits.d.ts · lib/esm/lib/agent/jmap/
• agent-jmap-blob-limits.d.ts.map · lib/esm/lib/agent/jmap/
• agent-jmap-blob-limits.js · lib/esm/lib/agent/jmap/
• agent-jmap-blob-upload.d.ts · lib/esm/lib/agent/jmap/
• agent-jmap-blob-upload.d.ts.map · lib/esm/lib/agent/jmap/
• agent-jmap-blob-upload.js · lib/esm/lib/agent/jmap/
• agent-jmap-email-charset.d.ts · lib/esm/lib/agent/jmap/
• agent-jmap-email-charset.d.ts.map · lib/esm/lib/agent/jmap/
• agent-jmap-email-charset.js · lib/esm/lib/agent/jmap/
• agent-jmap-run.d.ts · lib/esm/lib/agent/jmap/
• agent-jmap-run.d.ts.map · lib/esm/lib/agent/jmap/
• agent-jmap-run.js · lib/esm/lib/agent/jmap/
• agent-jmap-verify.d.ts · lib/esm/lib/agent/jmap/
• agent-jmap-verify.d.ts.map · lib/esm/lib/agent/jmap/
• agent-jmap-verify.js · lib/esm/lib/agent/jmap/
• agent-jmap.d.ts · lib/esm/lib/agent/jmap/
• agent-jmap.d.ts.map · lib/esm/lib/agent/jmap/
• agent-jmap.js · lib/esm/lib/agent/jmap/
• agent-vars.d.ts · lib/esm/lib/agent/jmap/
• agent-vars.d.ts.map · lib/esm/lib/agent/jmap/
• agent-vars.js · lib/esm/lib/agent/jmap/
• auth.d.ts · lib/esm/lib/agent/jmap/help-content/
• auth.d.ts.map · lib/esm/lib/agent/jmap/help-content/
• auth.js · lib/esm/lib/agent/jmap/help-content/
• cron.d.ts · lib/esm/lib/agent/jmap/help-content/
• cron.d.ts.map · lib/esm/lib/agent/jmap/help-content/
• cron.js · lib/esm/lib/agent/jmap/help-content/
• index.d.ts · lib/esm/lib/agent/jmap/help-content/
• index.d.ts.map · lib/esm/lib/agent/jmap/help-content/
• index.js · lib/esm/lib/agent/jmap/help-content/
• installation.d.ts · lib/esm/lib/agent/jmap/help-content/
• installation.d.ts.map · lib/esm/lib/agent/jmap/help-content/
• installation.js · lib/esm/lib/agent/jmap/help-content/
• jmap-cheatsheet.d.ts · lib/esm/lib/agent/jmap/help-content/
• jmap-cheatsheet.d.ts.map · lib/esm/lib/agent/jmap/help-content/
• jmap-cheatsheet.js · lib/esm/lib/agent/jmap/help-content/
• multi-account.d.ts · lib/esm/lib/agent/jmap/help-content/
• multi-account.d.ts.map · lib/esm/lib/agent/jmap/help-content/
• multi-account.js · lib/esm/lib/agent/jmap/help-content/
• overview.d.ts · lib/esm/lib/agent/jmap/help-content/
• overview.d.ts.map · lib/esm/lib/agent/jmap/help-content/
• …and 107 more

SKILL.md (first lines)

# 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" \
  --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](#inbox-checks-after-register)). 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 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`, `$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:

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

From Atomic-Mail/atomic-mail-agentic, MIT.

More from Atomic-Mail/atomic-mail-agentic