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. This skill was built live in WW-2.
2-Minute Quick Start
CODEBLOCK0
That's it. No pip install, no config files, no OAuth dance.
Commands
| Command | What it does |
|---|
| INLINECODE0 | List inbox emails (newest first) |
| INLINECODE1 |
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:
CODEBLOCK1
In heartbeat/cron:
CODEBLOCK2
Real-World Examples
CODEBLOCK3
Environment Variables
| Variable | Required | Description |
|---|
| INLINECODE10 | ✅ | API token from Fastmail settings |
| INLINECODE11 |
❌ | Override sender email (defaults to primary identity) |
Getting a token
- 1. Go to Fastmail Settings → Security → API Tokens
- Create new token
- Enable scopes: Email (read/write) and Email Submission (for sending)
- Copy the token (starts with
fmu1-)
Storing the token
For OpenClaw agents, add to your gateway config:
CODEBLOCK4
Or use 1Password injection: INLINECODE13
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 |
|---|
| INLINECODE16 | List folders |
| INLINECODE17 |
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 — INLINECODE29
- 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) - INLINECODE31 — 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., agent@yourdomain.com).
为你的智能体赋予邮件能力
你的智能体可以浏览网页、编写代码和管理日历。但它能阅读你的邮件吗？能查找那张发票吗？能发送回复吗？
现在它可以了。零依赖、纯Python、Fastmail的JMAP API。
由The Agent Wire构建——这是一家撰写关于AI智能体新闻通讯的AI智能体公司。该技能在WW-2中现场构建完成。
2分钟快速入门
bash
1. 获取Fastmail API令牌
→ https://app.fastmail.com/settings/security/tokens
→ 权限范围：邮件（读/写）+ 邮件提交（发送）
2. 设置令牌
export FASTMAIL_TOKEN=fmu1-...
3. 检查收件箱
python3 scripts/fastmail.py unread
就这样。无需pip安装，无需配置文件，无需OAuth认证流程。
命令
| 命令 | 功能说明 |
|---|
| inbox [--limit N] [--unread] | 列出收件箱邮件（最新优先） |
| unread |
每个邮箱的未读数量 + 列出未读邮件 |
| search
[--from ADDR] [--after DATE] [--before DATE] | 跨所有邮箱全文搜索 |
| read | 读取完整邮件正文 |
| send | 发送邮件 |
| move | 将邮件移动到指定邮箱 |
| mark-read | 标记为已读 |
| mark-unread | 标记为未读 |
| trash | 移至垃圾箱 |
| mailboxes | 列出所有邮箱及其数量 |
智能体集成
文档示例参考片段：
markdown
邮件
通过Fastmail JMAP检查、搜索和管理邮件。
脚本：python3 scripts/fastmail.py
环境变量：必须设置FASTMAIL_TOKEN。
检查邮件
- - python3 scripts/fastmail.py unread — 快速扫描未读邮件
- python3 scripts/fastmail.py search invoice --after 2026-01-01 — 查找特定邮件
阅读邮件
- - python3 scripts/fastmail.py read — 获取完整正文内容
管理邮件
- - python3 scripts/fastmail.py move — 归档到文件夹
- python3 scripts/fastmail.py mark-read — 标记为已读
- python3 scripts/fastmail.py trash — 移至垃圾箱
发送邮件
- - python3 scripts/fastmail.py send user@example.com Subject Body text
- 发送前务必询问。未经批准绝不发送。
在心跳/定时任务中：
markdown
邮件检查
运行：python3 scripts/fastmail.py unread
如果发现紧急/可操作的邮件，进行摘要并提醒。
如果没有新邮件，则跳过。
实际应用示例
bash
早晨收件箱扫描
python3 scripts/fastmail.py unread
查找本月收据
python3 scripts/fastmail.py search receipt --after 2026-02-01
搜索特定发件人
python3 scripts/fastmail.py search meeting --from boss@company.com --limit 5
阅读特定邮件
python3 scripts/fastmail.py read M1234abcd
归档发票
python3 scripts/fastmail.py move M1234abcd Invoices
快速回复（智能体应在发送前询问）
python3 scripts/fastmail.py send client@example.com Re: Invoice #1234 Thanks, received and filed.
删除垃圾邮件
python3 scripts/fastmail.py trash Mspam5678
环境变量
| 变量 | 必需 | 描述 |
|---|
| FASTMAILTOKEN | ✅ | 来自Fastmail设置的API令牌 |
| FASTMAILIDENTITY |
❌ | 覆盖发件人邮箱（默认为主身份） |
获取令牌
- 1. 前往Fastmail设置 → 安全 → API令牌
- 创建新令牌
- 启用权限范围：邮件（读/写）和邮件提交（用于发送）
- 复制令牌（以fmu1-开头）
存储令牌
对于OpenClaw智能体，添加到你的网关配置中：
json
{
env: {
vars: {
FASTMAIL_TOKEN: fmu1-...
}
}
}
或使用1Password注入：op run --env-file=.env -- python3 scripts/fastmail.py unread
工作原理
使用JMAP（JSON元应用协议）——Fastmail现代化的、基于JSON的邮件API。这是Fastmail为替代IMAP而构建的协议，而且速度飞快。
- - 无IMAP/SMTP — 纯HTTP JSON请求
- 无pip依赖 — 仅使用Python 3标准库（urllib、json）
- 无状态 — 无本地数据库，无需同步，只需查询即可
- 批量请求 — 单个API调用中执行多个操作
使用的JMAP方法
| 方法 | 用途 |
|---|
| Mailbox/get | 列出文件夹 |
| Email/query |
搜索/筛选 |
| Email/get | 获取内容 |
| Email/set | 移动、标记已读/未读、删除 |
| EmailSubmission/set | 发送 |
| Identity/get | 解析发件人地址 |
注意事项
- - 令牌权限范围很重要：邮件权限用于读/写，邮件提交权限用于发送。缺少权限范围会返回403错误。
- urn:ietf:params:jmap:core必须在JMAP的using数组中——省略会导致令人困惑的403错误。
- 邮件ID是不透明字符串（如M1234abcd），不是数字。
- 默认搜索是全局的——添加--from或日期标志来缩小结果范围。
- 获取正文需要显式选择——脚本已处理此问题，但如果你扩展它，请记住fetchTextBodyValues: true。
- 日期为UTC时间——--after 2026-02-18在内部变为2026-02-18T00:00:00Z。
为什么选择Fastmail？
如果你是运行AI智能体的独立创业者，Fastmail是明智之选：
- - 每月$5即可获得完整邮箱账户，支持自定义域名
- JMAP API — 现代化、快速、文档完善
- 无需OAuth迷宫 — 只需一个API令牌
- 注重隐私 — 无扫描、无广告
- 自定义域名 — you@yourdomain.com
- Sieve过滤器 — 服务端规则，智能体可以补充
Gmail的API需要OAuth2、应用注册、同意屏幕和令牌刷新。Fastmail给你一个令牌，然后就不碍事了。
文件
- - scripts/fastmail.py — CLI（单个文件，约300行）
- SKILL.md — 本文件
常见问题
这个技能是什么？
Fastmail JMAP是一个Python脚本，通过Fastmail的JMAP API为AI智能体提供完整的邮件访问权限——读取、搜索、发送、移动、删除。无需OAuth，无需客户端ID，只需一个API令牌。
它解决了什么问题？
Gmail的API需要OAuth同意屏幕、客户端ID、重定向URI和令牌刷新流程——对无头智能体不友好。Fastmail的JMAP API使用单个API令牌即可获得完整访问权限。设置只需2分钟，而不是2小时。
有什么要求？
Python 3（仅标准库）、Fastmail账户（每月$5的标准计划）、以及来自Fastmail设置→隐私与安全→API令牌的API令牌。
费用是多少？
Fastmail标准版每月$5。API包含在内——无按请求收费。相比之下，Google Workspace最低每月$7.20。
能否替代Gmail用于AI智能体？
可以。它支持收件箱、未读、搜索、读取、发送、移动、标记已读/未读、删除和邮箱列表。JMAP协议比Gmail的REST API更简单、对智能体更友好。
是否支持自定义域名？
支持。
