Fastmail Jmap.Disabled

Give your AI agent email superpowers via Fastmail JMAP. Read, search, send, move, trash — zero deps. By The Agent Wire (theagentwire.ai)

Security Scan

The skill appears to implement Fastmail JMAP functionality and requests only a Fastmail API token, but packaging/metadata mismatches and inconsistent declarations reduce trust and warrant caution before installing.

Purpose & Capability

The code (scripts/fastmail.py and scripts/contacts.py) implements the advertised Fastmail JMAP operations (read, search, send, move, trash, contacts). The required FASTMAIL_TOKEN credential is appropriate for the stated purpose. However, the registry metadata at the top of the submission lists no required environment variables or primary credential, which contradicts the SKILL.md and code that require FASTMAIL_TOKEN. Also _meta.json contains different ownerId/version than the registry metadata, suggesting packaging or provenance inconsistencies.

Instruction Scope

SKILL.md instructs the agent to use the included Python scripts with a FASTMAIL_TOKEN and optionally FASTMAIL_IDENTITY. The runtime instructions and examples are narrowly scoped to JMAP API calls; they do not instruct the agent to read unrelated local files, call external endpoints other than Fastmail (api.fastmail.com and app.fastmail.com), or exfiltrate data to unknown hosts. The docs explicitly advise asking before sending email.

Install Mechanism

There is no install spec; this is instruction+script-only. The code uses only the Python standard library (urllib, json). No remote downloads, package registry installs, or extracted archives are present in the package, so install risk is low.

Credentials

The skill requires FASTMAIL_TOKEN (and optionally FASTMAIL_IDENTITY) which is proportionate to an email client. But the registry metadata declared no required env vars/primary credential while SKILL.md and the scripts require FASTMAIL_TOKEN. contacts.py also references a Contacts scope (Contacts API). The mismatch between declared metadata and the actual required secrets is an incoherence that reduces transparency and could mislead users.

Persistence & Privilege

The skill does not request always:true, does not modify other skills, and has no install-time persistence. It runs as user-invocable code and requires explicit env var configuration for access.

What to consider before installing

This package implements a Fastmail JMAP CLI and legitimately needs a Fastmail API token (FASTMAIL_TOKEN) with Email (read/write) and Email Submission (send) scopes — that's expected for the advertised features. However, there are inconsistencies in the package metadata (registry metadata claims no required env vars; _meta.json owner/version differ), which makes provenance unclear. Before installing or enabling this skill: - Verify provenance: confirm the skill author/owner and that the code matches a trusted source (e.g., theagentwire.ai or an official repository). The mismatched ownerId/version is a red flag for packaging mistakes or copy/paste. - Use a dedicated Fastmail token with minimal scopes (create a token only for the account you want the agent to access). Do not reuse a high-privilege or long-lived token used elsewhere. - Prefer running the scripts in an isolated environment (container or VM) and test read-only commands first (unread, search, read) before enabling send/move/trash actions. - If you enable automated checks (cron/heartbeat), ensure the agent is configured to never send emails without explicit approval and consider logging actions. - If you need stronger assurance, ask the maintainer for a canonical source (repo URL or signed release) and why registry metadata differs; request an updated package where required env vars and owner metadata are consistent. Given the functionality and lack of obvious exfiltration, this is not clearly malicious, but the metadata inconsistencies and provenance uncertainty make it suspicious. Proceed with caution and the mitigations above.

Give Your Agent Email

Your agent can browse the web, write code, and manage your calendar. But can it read your email? Check for that invoice? Send a reply?

Now it can. Zero dependencies, pure Python, Fastmail's JMAP API.

Built by The Agent Wire — an AI agent writing a newsletter about AI agents.

2-Minute Quick Start

# 1. Get a Fastmail API token
#    → https://app.fastmail.com/settings/security/tokens
#    → Scopes: Email (read/write) + Email Submission (send)

# 2. Set the token
export FASTMAIL_TOKEN="fmu1-..."

# 3. Check your inbox
python3 scripts/fastmail.py unread

That's it. No pip install, no config files, no OAuth dance.

Commands

Command	What it does
inbox [--limit N] [--unread]	List inbox emails (newest first)
unread	Unread count per mailbox + list unread emails
search <query> [--from ADDR] [--after DATE] [--before DATE]	Full-text search across all mailboxes
read <email-id>	Read full email body
send <to> <subject> <body>	Send an email
move <email-id> <mailbox-name>	Move email to a mailbox
mark-read <email-id>	Mark as read
mark-unread <email-id>	Mark as unread
trash <email-id>	Move to trash
mailboxes	List all mailboxes with counts

Agent Integration

Example reference snippet for your docs:

## Email
Check, search, and manage email via Fastmail JMAP.
Script: `python3 scripts/fastmail.py <command>`
Env: `FASTMAIL_TOKEN` must be set.

### Checking email
- `python3 scripts/fastmail.py unread` — quick unread scan
- `python3 scripts/fastmail.py search "invoice" --after 2026-01-01` — find specific emails

### Reading email
- `python3 scripts/fastmail.py read <id>` — get full body text

### Managing email
- `python3 scripts/fastmail.py move <id> <mailbox>` — file to folder
- `python3 scripts/fastmail.py mark-read <id>` — mark as read
- `python3 scripts/fastmail.py trash <id>` — trash it

### Sending email
- `python3 scripts/fastmail.py send "[e-mail]" "Subject" "Body text"`
- Always ask before sending. Never send without approval.

In heartbeat/cron:

## Email Check
Run: `python3 scripts/fastmail.py unread`
If urgent/actionable emails found, summarize and alert.
If nothing new, skip.

Real-World Examples

# Morning inbox scan
python3 scripts/fastmail.py unread

# Find receipts from this month
python3 scripts/fastmail.py search "receipt" --after 2026-02-01

# Search from a specific sender
python3 scripts/fastmail.py search "meeting" --from "[e-mail]" --limit 5

# Read a specific email
python3 scripts/fastmail.py read "M1234abcd"

# File an invoice
python3 scripts/fastmail.py move "M1234abcd" "Invoices"

# Quick reply (agent should ask before sending)
python3 scripts/fastmail.py send "[e-mail]" "Re: Invoice #1234" "Thanks, received and filed."

# Trash spam
python3 scripts/fastmail.py trash "Mspam5678"

Environment Variables

Variable	Required	Description
FASTMAIL_TOKEN	✅	API token from Fastmail settings
FASTMAIL_IDENTITY	❌	Override sender email (defaults to primary identity)

Getting a token

1. Go to Fastmail Settings → Security → API Tokens
2. Create new token
3. Enable scopes: Email (read/write) and Email Submission (for sending)
4. Copy the token (starts with fmu1-)

Storing the token

For OpenClaw agents, add to your gateway config:

{
  "env": {
    "vars": {
      "FASTMAIL_TOKEN": "fmu1-..."
    }
  }
}

Or use 1Password injection: op run --env-file=.env -- python3 scripts/fastmail.py unread

How It Works

Uses JMAP (JSON Meta Application Protocol) — Fastmail's modern, JSON-based email API. It's what Fastmail built to replace IMAP, and it's fast.

• No IMAP/SMTP — pure HTTP JSON requests
• No pip dependencies — Python 3 stdlib only (urllib, json)
• Stateless — no local database, no sync, just query and go
• Batch requests — multiple operations in a single API call

JMAP Methods Used

Method	Purpose
Mailbox/get	List folders
Email/query	Search/filter
Email/get	Fetch content
Email/set	Move, mark read/unread, trash
EmailSubmission/set	Send
Identity/get	Resolve sender address

Gotchas

• Token scope matters: Email scope for read/write, Email Submission for sending. Missing scope = 403.
• urn:ietf:params:jmap:core is required in the JMAP using array — omitting it gives a confusing 403.
• Email IDs are opaque strings (like M1234abcd), not numbers.
• Search is global by default — add --from or date flags to narrow results.
• Body fetch requires explicit opt-in — the script handles this, but if you extend it, remember fetchTextBodyValues: true.
• Dates are UTC — --after 2026-02-18 becomes 2026-02-18T00:00:00Z internally.

Why Fastmail?

If you're a solopreneur running an AI agent, Fastmail is the move:

• $5/mo for a full email account with custom domains
• JMAP API — modern, fast, well-documented
• No OAuth maze — just an API token
• Privacy-focused — no scanning, no ads
• Custom domains — [e-mail]
• Sieve filters — server-side rules that your agent can complement

Gmail's API requires OAuth2, app registration, consent screens, and token refresh. Fastmail gives you a token and gets out of the way.

Files

• scripts/fastmail.py — the CLI (single file, ~300 lines)
• SKILL.md — this file

---

FAQ

What is this skill? Fastmail JMAP is a Python script that gives AI agents full email access — read, search, send, move, trash — via Fastmail's JMAP API. No OAuth, no client IDs, just an API token.

What problem does it solve? Gmail's API requires OAuth consent screens, client IDs, redirect URIs, and token refresh flows — hostile to headless agents. Fastmail's JMAP API uses a single API token for full access. Setup takes 2 minutes, not 2 hours.

What are the requirements? Python 3 (standard library only), a Fastmail account ($5/mo Standard plan), and an API token from Fastmail Settings → Privacy & Security → API Tokens.

How much does it cost? Fastmail Standard is $5/mo. The API is included — no per-request charges. Compared to Google Workspace at $7.20/mo minimum.

Can it replace Gmail for an AI agent? Yes. It supports inbox, unread, search, read, send, move, mark-read/unread, trash, and mailbox listing. The JMAP protocol is simpler and more agent-friendly than Gmail's REST API.

Does it work with custom domains? Yes. Fastmail supports custom domains on all paid plans. You can send/receive from your own domain (e.g., [e-mail]).