---
name: mailagents
description: Use when the user wants Codex to work with MailAgents or Cloud Mail email: inspect mailbox identity, list/search/read messages, send or reply to email, manage attachments, or process agent email tasks through the MailAgents MCP server.
---

# MailAgents

MailAgents is a Cloudflare Worker based mailbox and email automation system. Use this skill when a user asks to work with MailAgents email from Codex.

## Connection

The MailAgents Worker exposes MCP at:

```text
<MAILAGENTS_BASE_URL>/mcp
```

Authentication is provided by either:

- `X-Agent-Token: <token>`
- `Authorization: Bearer <token>`

Use a mailbox token for normal read/send work. Use a manager token only for manager-only actions such as creating webhooks or managing multiple mailboxes.

This plugin runs a local MCP stdio bridge at `scripts/mcp-bridge.mjs`. It defaults to `https://mailagents.net`. Configure a different deployment with:

```bash
export MAILAGENTS_BASE_URL="https://your-mailagents-domain"
```

The bridge forwards Codex MCP JSON-RPC calls to `<MAILAGENTS_BASE_URL>/mcp`. It adds `X-Agent-Token` when `MAILAGENTS_AGENT_TOKEN` is set; otherwise it performs OAuth locally, stores access/refresh state under `~/.mailagents/codex-oauth/`, refreshes access tokens automatically, and uses the current OAuth access token as the mailbox agent token.

## Common Tools

- `whoami`: inspect authenticated token, scopes, and accessible mailbox.
- `list_mailboxes`: list mailboxes visible to the token.
- `list_emails`: list received or sent messages with pagination. Results are compact by default and omit full bodies/raw rows unless `bodyMode` or `includeRaw` is requested.
- `get_email`: fetch one message with full body and attachment metadata.
- `get_email_decrypted` / `decrypt_email_local`: stable helper aliases for encrypted-message next-action fields. Through the local plugin bridge, matching Agent E2EE envelopes are decrypted into `plainText`/`html`; direct remote MCP calls return envelope metadata and next actions and may set `plaintextAvailableOnlyInPluginBridge`.
- `search_emails`: search by keyword, sender, recipient, subject, dates, direction, or attachment presence. Results are compact by default.
- `send_email`: send a new email from the authenticated mailbox. Supports `bodyRef` / `draftRef` for long bodies.
- `reply_email`: reply to an existing message. `to` is optional and defaults to the original sender. Supports `bodyRef` / `draftRef` for long bodies.
- `create_body_ref`: store a long body for 24 hours and send later by reference.
- `mark_read`: mark messages as read.
- `list_attachments`: list attachment metadata for a message.
- `ensure_agent_e2ee_key`, `list_agent_e2ee_keys`, and `revoke_agent_e2ee_key`: manage local agent public keys for encrypted body access. The plugin bridge normally calls these automatically.
- `list_email_tasks`, `claim_next_email_task`, `claim_email_task_batch`, `update_email_task`, `release_email_task`, and related task tools: process inbound email as agent work items.

## Operating Guidance

Before reading or sending email, call `whoami` when the current token or mailbox is unclear.

For message lookup:

1. Prefer `search_emails` when the user gives a sender, subject, keyword, or date.
2. Use `list_emails` for recent mailbox browsing; the default compact result is usually enough for inbox summaries.
3. Use `get_email` before summarizing, replying to, or acting on a specific message. If you need bodies for multiple list/search results, request `bodyMode: "plain"` or `bodyMode: "full"` deliberately.
4. If a message has `agentDecrypted: true`, treat `plainText` and `html` as normal readable body content. It was decrypted locally by the plugin bridge, not by the server.
5. If a message still has `decryptRequired: true`, explain that the body is end-to-end encrypted and no matching local agent envelope was available. Ask the user to open the email in the MailAgents web UI, decrypt it with the browser-local private key, and paste or share the decrypted body before summarizing or acting on the message.
6. For long reports, prefer `create_body_ref` first and then pass `bodyRef` or `draftRef` to `send_email` or `reply_email`.

Encrypted messages may still include metadata such as sender, recipients, timestamps, attachments, and `encryptionKeyId`. Do not treat an empty `plainText` or `html` field as a plugin failure when `encrypted: true` and `decryptRequired: true` are present.

For sending:

1. Confirm ambiguous recipients, accounts, and intent before sending.
2. Use `idempotencyKey` for any retryable send or reply operation.
3. Prefer plain text plus HTML only when the user asks for formatted mail.
4. Do not invent attachments. Use existing attachment data or ask the user for the file.

For task processing:

1. Use `claim_next_email_task` or `claim_email_task_batch` before performing work on queued inbound messages.
2. Set a stable `owner` or `agentId`, such as `codex`.
3. Renew long-running leases before they expire.
4. Finish by setting task status to `handled`, `needs_human`, or `ignored` with a concise reason.

## Local Project

The local source project usually lives at:

```text
/Users/zh/Documents/New project 3/cloud-mail
```

Useful project commands:

```bash
cd "/Users/zh/Documents/New project 3/cloud-mail/mail-worker"
pnpm dev
pnpm deploy
pnpm test
```

```bash
cd "/Users/zh/Documents/New project 3/cloud-mail/mail-vue"
pnpm dev
pnpm build
```

Use the plugin scripts as shortcuts when available:

```bash
/Users/zh/plugins/mailagents/scripts/local-dev-worker.sh
/Users/zh/plugins/mailagents/scripts/deploy-worker.sh
/Users/zh/plugins/mailagents/scripts/verify-mcp.sh https://example.com <agent-token>
```

For local troubleshooting or when a Codex thread has not loaded the MailAgents
MCP tools, use the bundled CLI helper from the plugin repository:

```bash
/Users/zh/Documents/New project 3/mailagents-codex-plugin/plugins/mailagents/scripts/mailagents-cli.sh whoami --no-browser
/Users/zh/Documents/New project 3/mailagents-codex-plugin/plugins/mailagents/scripts/mailagents-cli.sh inbox --limit 10 --no-browser
/Users/zh/Documents/New project 3/mailagents-codex-plugin/plugins/mailagents/scripts/mailagents-cli.sh diagnose --no-browser
```

Authenticated CLI calls need network access to the MailAgents Worker. In a
restricted Codex sandbox, request network approval if `tools` works but
`whoami`, `inbox`, or `get` times out. Add `--no-e2ee` for a quick metadata-only
check that skips local Agent E2EE setup/decryption.