fastmail-jmap

Files (1)

• SKILL.md

SKILL.md (first lines)

# Fastmail JMAP

Use Fastmail's JMAP JSON API with the local VM helper or curl elsewhere. The endpoint returns mail
content and may modify or permanently delete messages; keep operations
read-only unless the user explicitly asks for a specific change.

## Shelley VM: local SOPS delivery only

On Shelley's VM, use the fixed-path helper below. Do **not** read SSM, print
credentials, run `sops --decrypt` directly, or populate shell token variables.
The helper reads the approved hash-checked ciphertext release
`29f833d1f234500c3c160659be4bce88e00fa87d` under
`~/.local/share/shelley-secrets/releases/`, decrypts in memory using the existing
VM SSH identity (kept outside that release), discovers the session internally,
and returns only a status or requested method responses. No live NAS fetch or
AWS fallback occurs. Python resolves `Path.home()` for these home paths.

Status-only session + Core/echo, with no mailbox reads:

```bash
python3 "$HOME/.config/shelley/jobs/fastmail_jmap.py" check
```

For an authorized data lookup, send a bounded JSON request on stdin. Use the
literal `$PRIMARY_MAIL_ACCOUNT` placeholder; the helper replaces it internally
with the discovered primary mail account. Never dump the session object.

```bash
python3 "$HOME/.config/shelley/jobs/fastmail_jmap.py" request <<'JSON'
{
  "using": ["urn:ietf:params:jmap:core", "urn:ietf:params:jmap:mail"],
  "methodCalls": [["Mailbox/get", {
    "accountId": "$PRIMARY_MAIL_ACCOUNT",
    "ids": null,
    "properties": ["id", "name", "role"]
  }, "q"]]
}
JSON
```

Read only task-needed responses; check `methodResponses` for errors. The helper
rejects write methods by default. Add `--allow-write` only after explicit
present-task approval for the exact mutation; the flag is not authorization.
Do not test writes during a connectivity check. The helper has no blob/download
mode yet: stop for scoped implementation rather than bypassing credential
handling or reading SSM. Missing release/key is a blocker, not permission to
copy private identities or install software. SSM remains intact for explicit,
reviewed rollback only.

Skip the generic curl authentication/examples below on this VM. Their JMAP
method shapes can be adapted to helper stdin, but do not extract its token.

## Other hosts: authentication and safe curl setup

1. Fastmail Settings → Privacy & Security → Manage API tokens → New API token.
   Select **JMAP**, then the narrowest scope that covers the task. Fastmail
   offers read-only access; **Email** permits modifying and permanently
   deleting mail; **Email submission** permits sending and requires Email.
   Contacts, Masked Email, and submission have separate scopes. API tokens
   are not available on Basic plans.
2. Use an approved secret manager or read the token interactively without echo.
   Do not print, commit, or put it in chat. Disable shell tracing and avoid
   command-line arguments or shell history. This branch is not for Shelley VM:

   ```bash
   set +x
   read -rsp 'Fastmail JMAP token: ' FASTMAIL_TOKEN
   printf '\n'
   JMAP_SESSION_URL=https://api.fastmail.com/jmap/session
   ```

3. Send it as `Authorization: Bearer …`. Here-doc curl config keeps the
   expanded header out of curl's argument list; do not enable `set -x` or
   verbose/header tracing:

   ```bash
   curl --fail-with-body --silent --show-error --config - <<EOF
   url = "${JMAP_SESSION_URL}"
   header = "Authorization: Bearer ${FASTMAIL_TOKEN}"
   EOF
   ```

   Clear the variable when done: `unset FASTMAIL_TOKEN`.

## Session and API requests

Fetch the session object first. Use its `apiUrl`, `primaryAccounts`, and
`capabilities`; do not hard-code an account ID or assume an API URL beyond the
documented session endpoint. Session discovery needs JMAP core access.

```bash
session=$(curl --fail-with-body --silent --show-error --config - <<EOF
url = "${JMAP_SESSION_URL}"
header = "Authorization: Bearer ${FASTMAIL_TOKEN}"
EOF
)
JMAP_API_URL=$(jq -r '.apiUrl' <<<"$session")
JMAP_ACCOUNT_ID=$(jq -r '.primaryAccounts["urn:ietf:params:jmap:mail"]' <<<"$session")
```

JMAP API calls are JSON POST requests. The request's `using` array declares
the capabilities, and each `methodCalls` entry is `[method, arguments, tag]`.
Use the session's primary mail account ID for `accountId`. For nontrivial
requests, write JSON with `jq` to a private temporary file and send it with
`--data-binary @FILE`; interpolating raw JSON into curl's config `data` string
is easy to mis-escape and can produce HTTP 400 errors.

Find the inbox mailbox ID with `Mailbox/get`, then use it to list recent
message IDs. This concrete request shows the curl/JMAP wire format:

```bash
curl --fail-with-body --silent --show-error --config - <<EOF
url = "${JMAP_API_URL}"
header = "Authorization: Bearer ${FASTMAIL_TOKEN}"
header = "Content-Type: application/json"
data = "{\"using\":[\"urn:ietf:params:jmap:core\",\"urn:ietf:params:jmap:mail\"],\"methodCalls\":[[\"Email/query\",{\"accountId\":\"${JMAP_ACCOUNT_ID}\",\"filter\":{\"inMailbox\":\"INBOX_MAILBOX_ID\"},\"sort\":[{\"property\":\"receivedAt\",\"isAscending\":false}],\"limit\":5},\"q\"]]}"
EOF
```

From jason-riddle/agent-skills, MIT.

More from jason-riddle/agent-skills