Claude Code as a mail assistant
Give Claude Code your mail, either through airpost-mcp with an access level or through the airpost CLI with the agent skill.
What you’ll build
A Claude Code setup where you can ask things like “what did the auditors send last week, and save the attachments into ./audit” or “draft a reply to Dana’s contract thread” from your terminal. You pick one of two ways in:
| airpost-mcp | airpost CLI + skill | |
|---|---|---|
| What the agent calls | MCP tools (search_mail, reply_to_thread, …) | airpost commands in the shell |
| Limits | Access level, hidden accounts and folders, audit log | None: your full rights |
| Good for | Day-to-day assistance | Scripting tasks you’d otherwise do yourself |
Use the MCP route unless you want the agent to have everything you have. Don’t give one agent both.
Prerequisites
- Airpost with
airpostandairpost-mcp. See Install the CLI. - An engine running (the desktop app, or
airpost engine install). - Claude Code with
claudeon yourPATH.
Route A: airpost-mcp
Register the server
airpost-mcp install --client claude-code
This runs claude mcp add-json airpost ... --scope user. To register it only for one project instead, write the entry into that project’s .mcp.json:
cd ~/work/acme
airpost-mcp install --client claude-code --config-file .mcp.json
Pick the access level
Leave it at Read mail for questions and search. Choose Read and draft in Preferences > MCP if you want the agent to write drafts and archive. Sending stays with you unless you choose Read, draft and send.
Check it
airpost-mcp status
claude mcp list
claude mcp list shows airpost as connected.
Ask
claude
> Find the mail from the auditors in the last two weeks and save every
PDF they attached into ./audit.
Claude calls search_mail (with something like from:auditor has:attachment after:2w), get_thread to see the files arrays, and get_attachment, whose result includes the file’s local path. It then copies those files with its own shell tools.
Route B: the CLI and the agent skill
The CLI acts with your full rights. Access levels, hidden folders and the audit log don’t apply to it.
Install the skill
airpost skill install --agent claude
This writes ~/.claude/skills/airpost. Use --project to put it in ./.claude/skills for one repository.
Ask
> Archive everything from notifications@github.com older than a week,
but show me the dry run first.
The skill teaches Claude to run the dry run before the change:
airpost archive --query 'from:notifications@github.com before:7d' --dry-run --json
airpost archive --query 'from:notifications@github.com before:7d' --wait --json
and to report the undo token from the result.
Expected output
For the attachment question with Route A, Claude ends with something like:
Saved 3 files to ./audit:
./audit/Q3-findings.pdf (from "Q3 audit: findings", Oct 30)
./audit/management-letter.pdf
./audit/PBC-list-v2.pdf
The calls are in the audit log:
airpost-mcp status # prints the audit log path
tail -n 5 "<config-dir>/mcp-audit.log" | jq -c '{toolName, outcome}'
How it works
airpost-mcp install writes a stdio entry that runs the airpost-mcp binary by full path with --config-dir pinned, so Claude Code always reaches the same profile. airpost-mcp talks to the running engine over its local socket; nothing goes through a server. The policy file is read on every call, so changing the level takes effect on the next tool call.
The skill is a SKILL.md built into the airpost binary. It tells Claude when to use the CLI, the search grammar, the draft flow (draft reply, draft validate, draft send) and the safety rules.
Variations
- Project-scoped mail. Combine
--config-file .mcp.jsonwith hidden accounts so a work repository only sees the work account. - Codex.
airpost-mcp install --client codexorairpost skill install --agent codex. - Remote engine. If your engine runs on a server, use MCP over HTTP with a bearer token instead of stdio. See Always-on VPS.
Cleanup
airpost-mcp uninstall --client claude-code
airpost skill uninstall --agent claude