canonical: https://jentic.com/apis/mermail.app/mermail

# Mermail App Mermail Agent Marketplace

The Mermail API gives an AI agent its own hosted email inbox, bound to a crypto wallet instead of an API key. An agent creates a mailbox, lists and searches its messages, reads threads and attachments, saves drafts, and sends, replies to, or forwards email. Payment is the credential: unpaid calls return 402, reads and drafts are $0 identity handshakes over x402, sending costs $0.01, and creating an inbox costs $2 in USDC. Inbound bodies are scan-gated, so non-clean messages come back as metadata with content_omitted.

## For AI agents

Create a wallet-bound email inbox for an agent, then read, search, send, reply to, and forward mail from it, paying per call over x402 instead of using an API key.

## Scope

Does not send bulk marketing campaigns, manage your own domain's DNS, or deliver SMS. Use for wallet-bound hosted agent inboxes only.

## Capabilities

- Create a hosted agent inbox, optionally choosing the Mermail address and name
- List and search inbox messages by query, from, to, subject, date range, or folder
- Require scan_status clean through require_scan_status before an agent reads message bodies
- Read a single message, its full thread, its safe context, or a downloaded attachment
- Send an email with to, from, and subject, then reply to or forward a received message
- Save a draft for later review instead of sending immediately
- Replay a paid call safely with the same Idempotency-Key and body after an uncertain settlement

## Use cases

### An agent with its own inbox, connected through Jentic

Agents that sign up for services or talk to people by email need an address of their own. Through Jentic the agent finds the Mermail create-mailbox operation, gets a hosted inbox, and then lists and searches it for replies. Because Mermail puts the mailbox id in the URL path, your Jentic One rules can hold the agent to that one inbox and to the operations you choose.

Example prompt: POST `/api/agent/v1/mailboxes` with name 'research-agent', store the returned mailboxId, then GET `/api/agent/v1/mailboxes/{mailboxId}/emails` with require_scan_status 'clean'

### Catching verification and sign-up emails

When an agent registers for a service, the confirmation link arrives by email. The search operation filters by from, subject, and a date_start and date_end window, and the agent_safe_content and require_scan_status parameters keep unscanned bodies away from the model. Reading the message or its context returns the content only when the scan is clean.

Example prompt: GET `/api/agent/v1/mailboxes/{mailboxId}/search` with from 'no-reply@example.com', subject 'Confirm', and require_scan_status 'clean', then GET the matching message by emailId

### Human-approved replies with drafts

For outbound mail you want to check first, the agent saves a draft with a body and optional thread_id or in_reply_to, and sends only after review. Sending, replying, and forwarding each require to, from, and subject and cost $0.01 per call, while drafts are a $0 handshake.

Example prompt: POST `/api/agent/v1/mailboxes/{mailboxId}/drafts` with body 'Thanks, confirmed for Tuesday.' and thread_id from the original message

### Forwarding receipts and attachments

An agent that receives receipts or reports can download an attachment by attachmentId or forward the whole message to another address, keeping the thread history with in_reply_to and references.

Example prompt: POST `/api/agent/v1/mailboxes/{mailboxId}/emails/{emailId}/forward` with to 'accounts@example.com', from the mailbox address, and subject 'Fwd: Invoice 1042'

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| POST | `/api/agent/v1/mailboxes` | Create a hosted agent inbox |
| GET | `/api/agent/v1/mailboxes/{mailboxId}/emails` | List inbox messages |
| GET | `/api/agent/v1/mailboxes/{mailboxId}/search` | Search inbox messages |
| POST | `/api/agent/v1/mailboxes/{mailboxId}/emails` | Send an email |
| POST | `/api/agent/v1/mailboxes/{mailboxId}/emails/{emailId}/reply` | Reply to an email |
| GET | `/api/agent/v1/mailboxes/{mailboxId}/threads/{threadId}` | Get a message thread |
| POST | `/api/agent/v1/mailboxes/{mailboxId}/drafts` | Save a draft |

## Key resources

- **Mailboxes** — Create, list, and read wallet-bound hosted inboxes
- **Emails** — List, search, read, send, reply to, and forward messages
- **Threads and context** — Read a whole thread or a message's scan-gated context
- **Drafts** — Save drafts for later sending
- **Folders and labels** — List inbox folders and custom labels

## AI readiness

This API is usable in Jentic One now. Its AI-readiness score against Jentic's framework shows where it stands today and where improvements would make it even easier for agents to use.

- **Score:** 58 / 100
- **Maturity:** Foundational
- **Dimensions:**
  - Foundational Compliance: 81 / 100
  - Developer Experience & Jentic Compatibility: 63 / 100
  - AI-Readiness & Agent Experience: 44 / 100
  - Agent Usability: 94 / 100
  - Security: 100 / 100
  - AI Discoverability: 28 / 100
- **View full report:** https://jentic.com/apis/mermail.app/mermail/scorecard
- **How the score is calculated:** https://docs.jentic.com/reference/api-readiness-framework/overview/
- **More about the dimensions:** https://docs.jentic.com/reference/api-readiness-framework/specification/#dimensional-model-overview

### Score it yourself

Every API in the directory is allowlisted, so you can re-score it with no key required.

- **Score your own API:** https://jentic.com/scorecard.md
- **Scoring CLI agent skill:** https://github.com/jentic/jentic-api-scorecard/blob/main/skills/jentic-api-scorecard/SKILL.md

```sh
npx @jentic/api-scorecard-cli score <openapi-url>
```

## Why Jentic

- **Setup:** Wiring Mermail by hand means handling its 402 challenge, attaching an x402 PAYMENT-SIGNATURE or MPP Payment-Authorization header, and replaying uncertain paid calls with the same Idempotency-Key. Through Jentic you install once, import Mermail from the API Directory, and your agent calls it with the operation schemas in hand.
- **Permission scoping:** Mermail puts the mailbox id in the URL path (`/api/agent/v1/mailboxes/{mailboxId}/...`), so a rule can pin your agent to one inbox and the operations you pick. You choose the operations it may call, so paid ones like send, reply, forward, or mailbox creation are not included unless you add them.
- **Credential handling:** Mermail declares no API key or token: paid routes are authorised per request by an x402 payment signature, so there is no long-lived secret for the agent to hold. Calls still run through your own Jentic One instance, where your rules and logs apply.
- **Discovery method:** Agents search Jentic by intent such as 'search my agent inbox' or 'reply to an email', and Jentic returns the matching Mermail operation with its input schema so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **MailSlurp API** — Programmable inboxes for testing and automation, using an API key
- **Resend API** — Transactional email sending from your own domain
- **Mailtrap API** — Email testing sandboxes and sending

## FAQ

### What authentication does the Mermail API use?

The Mermail agent API declares no API key or token in its OpenAPI spec. Payment is the credential: an unpaid call returns 402, and the agent retries with an x402 payment or identity-handshake value in the PAYMENT-SIGNATURE header, or an MPP value in Payment-Authorization on paid writes when that is enabled. Reads and drafts are $0 handshakes that bind the wallet; the spec notes that the older workspace API at `/api/v1` still uses x-api-key.

### How much does the Mermail API cost per call?

Per the spec, creating a mailbox costs $2, and sending, replying, and forwarding cost $0.01 each, paid in USDC. Listing, reading, searching, folders, labels, and drafts are $0 identity handshakes. The live 402 challenge is the authoritative quote.

### How do I create an agent inbox through Jentic?

Install Jentic One with `curl -fsSL https://raw.githubusercontent.com/jentic/jentic-one/main/tools/install.sh | sh` and import the Mermail API from the directory. Your agent searches 'create an email inbox for my agent', gets POST `/api/agent/v1/mailboxes` with its schema, and sends an optional email and name; the payment header is part of the call. To run it on your own infrastructure, install Jentic One from its GitHub repo.

### Can I limit what my agent is allowed to do with the Mermail API?

Yes. For example, write a rule that allows only the list, search, and get-message operations under `/api/agent/v1/mailboxes/mbx_123`, so the agent can read that one inbox but cannot send, reply, forward, or create new paid mailboxes. Add the send operation when you are ready, and every call it makes is logged.

### Is there a Mermail MCP server?

You don't need an MCP server to give your agent Mermail. Jentic connects it directly from the API Directory: import it and your agent calls it, discovering operations on demand instead of loading extra tool definitions into its context.

### What are the rate limits for the Mermail API?

The OpenAPI spec does not specify rate limits. Check the Mermail documentation at https://mermail.app for current limits.

### How does Mermail keep unsafe email content away from my agent?

Inbound messages are scanned. The list and search operations accept require_scan_status (clean, flagged, or skipped) and agent_safe_content, and the get, context, and attachment operations return metadata with content_omitted when a body is not clean. The spec advises requiring scan_status clean before using body content.