---
title: "agmail docs"
description: "The reference for agents and the people who build them. The short version is on the front page; everything the agent needs to call the service is here."
canonical: "/docs"
updated: "2026-10-07"
---

# agmail docs

The reference for agents and the people who build them. The short version is on the front page; everything the agent needs to call the service is here.

## Overview and how a call is paid

agmail gives an agent an email address for an hour, four hours or a day. The address takes mail only. Each purchase is paid in stablecoins: x402 on Base, Polygon and Solana or MPP on Base.

POST the JSON body with no payment. The 402 answer carries the quote for exactly what you asked, in the `PAYMENT-REQUIRED` header (x402) and in a `WWW-Authenticate: Payment` challenge (MPP).

Sign one challenge and POST the same body again with `PAYMENT-SIGNATURE` (x402) or `Authorization: Payment` (MPP). Every endpoint answers on `/x402/<name>` and on `/mpp/<name>`; both protocols are accepted on both.

The payment settles only after the call is accepted.

A call that cannot be served (a name that is taken, the service at capacity, an extension of an unknown inbox) is not charged. Retrying with the same payment returns the stored answer, without the secret.

## Open an inbox

POST `/x402/inbox-1h`, `/x402/inbox-4h` or `/x402/inbox-24h` (or the same under `/mpp/`) with an optional name. The name is 3 to 32 characters: letters, digits, dots, dashes and underscores, starting and ending with a letter or digit. Check a name for free with `GET /v1/names/{name}`.

RouteLastsMessages keptStored mail

inbox-1h1 hour505 MiB

inbox-4h4 hours10010 MiB

inbox-24h24 hours20020 MiB

`{"name":"myagent"}`

The answer is one JSON object: `inbox_id`, `address`, `secret`, `expires_at`, `plan` and `msg_cap`. The secret is shown only in this answer; keep it. The inbox takes mail once the payment has settled, a minute or so, and its time runs from then.

To extend, POST `/x402/inbox-1h-renew` (or the 4h and 24h routes, or under `/mpp/`) with `{"inbox_id":"ib_<id>","secret":"agm_<secret>"}`. An extension adds the same duration. An inbox cannot be paid for more than 72 hours ahead.

## Read mail

Send the secret as `Authorization: Bearer <secret>` to the inbox's API. An unknown inbox and a wrong secret get the same 401.

RequestWhat it does

GET /v1/inbox/{id}State, expiry and counters

GET /v1/inbox/{id}/messages?after=<seq>List messages, newest last; each has `from`, `subject`, `has_codes` and `size`

GET /v1/inbox/{id}/messages/{mid}One message: `text`, `codes`, `links`, `attachments`

DELETE /v1/inbox/{id}/messages/{mid}Remove one message

DELETE /v1/inbox/{id}Remove the inbox and its mail; no refund

GET /v1/inbox/{id}/waitBlock up to 55 s for a matching message and return it in full; `204` on timeout

GET /v1/inbox/{id}/otpBlock up to 55 s for a message with a code or a verification link; returns `code` and `link`

`wait` and `otp` take `from` and `subject_contains` (case-insensitive substrings) and `after` to skip messages you have seen.

`curl -H "Authorization: Bearer agm_<secret>" \
  "https://agmail.shveik.dev/v1/inbox/ib_<id>/wait?timeout=30&from=github"`

Links in mail are returned as text and are never fetched or followed. Attachments are listed by name, type and size and are not kept.

## MCP tools

The remote MCP server is at `https://agmail.shveik.dev/mcp` (streamable HTTP, stateless). Paid tools are `create_inbox` and `extend_inbox`; the payment is the x402 or MPP challenge inside the tool call, so the client must be able to sign it. Free tools are `check_name`, `wait_for_message`, `get_otp`, `list_messages`, `read_message` and `delete_inbox`.

Listing the tools and getting a quote work in any MCP client. Paying needs a client that can sign x402 payments.

## Limits and retention

A single message is 5 MiB at most on the wire; over that the sender is refused.

Per message: the text kept is 256 KiB at most (longer text is marked `truncated`), up to 20 links and 10 codes; attachments are metadata only.

Per inbox: the message count and the stored-bytes cap of its plan. Over the cap the inbox is full, and senders are asked to retry later.

Mail sent to one inbox is limited to 30 messages a minute; a flood gets a temporary refusal.

Inbox routes allow 120 requests a minute per inbox and 240 a minute per IP; name checks allow 60 a minute per IP. Both answer 429 with `Retry-After`.

When the service is at capacity the quote says so and no payment is taken.

Retention: mail is deleted one hour after the inbox expires (the grace hour, in which the owner can still read and extend). Then the name is free again after a cooldown of the same length. Mail is never kept longer than 73 hours after it arrived.

## Abuse and privacy

Use an inbox within the rules of the services you sign up to. Spam, fraud and abuse get the inbox removed without a refund. Report mail or an inbox to the address on the abuse page.

The service stores, per message, the sender, the subject, the text, the links and codes found in it, and the names and sizes of attachments. The sender's network address is not stored. There is no account, no cookie and no tracking. Read the full terms on the privacy, terms and abuse pages.

/privacy: what is stored and for how long

/terms: what the service is and is not

/abuse: how to report

## Reliability and limits

There is no uptime SLA or uptime guarantee. Service and upstream availability are best-effort and can change.

A quote is shown before payment, and work starts only after settlement. A request refused before settlement is not charged; product-specific refund rules for partial results, orders and deals are described below.

Message waits are capped at 55 seconds. Per-inbox calls are limited to 120 a minute, inbox routes to 240 a minute per IP, and name checks to 60 a minute per IP; these limits return 429 with Retry-After. A wait that times out returns 204; a storage or read failure returns 503.

Free GET docs, guides, pricing and discovery pages are limited to 120 requests per client IP per minute. They return RateLimit headers; a limit response is HTTP 429 with Retry-After. GET /healthz is a liveness check, not an uptime promise.

Failures are signalled with HTTP 402 when payment is required, 429 when a request is limited, 502 when a result cannot be delivered, and 503 when the service cannot accept work. Follow Retry-After when present. Report problems on the contact page at /contact.

## How it differs

Mail APIs with accounts and sending-reputation workflows send mail; agmail creates receive-only inboxes with a quote before per-call payment.

## Discovery

`/agents.md`: the guide for agents (preferred; `/llms.txt` is the same text for older tools)

`/openapi.json`: the OpenAPI 3.1 document with request schemas

`/.well-known/x402`: the x402 manifest

`/pricing.md`: generated endpoint prices and quote behavior

`/docs`: this API reference, with request examples

`/health`: service state

`/mcp`: the MCP server

RouteWhat it is

POST /x402/inbox-1hInbox for one hour

POST /x402/inbox-1h-renewExtend by one hour

POST /x402/inbox-4hInbox for four hours

POST /x402/inbox-4h-renewExtend by four hours

POST /x402/inbox-24hInbox for a day

POST /x402/inbox-24h-renewExtend by 24 hours

Try the service without paying: send a GET request to a listed endpoint to receive its free `402` quote, then decide whether to sign and pay. The quote request does not start a paid delivery.

The free `GET /ask?query=...` route searches the product reference. When available, `POST /mcp/docs` is a free, read-only documentation server with search, section lookup, and endpoint schema tools.

[Official MCP registry entry](https://registry.modelcontextprotocol.io/?q=dev.shveik/agmail) · [Glama listing](https://glama.ai/mcp/connectors/dev.shveik/agmail) · [Smithery listing](https://smithery.ai/servers/shveik/agmail) · [Agent kit on GitHub](https://github.com/shveik-dev/agent-kit) · [Agent guide](/agents.md) · [OpenAPI](/openapi.json) · [x402 manifest](/.well-known/x402)

## API versioning and deprecation policy

Versioned REST resources use `/v1`; paid purchase routes remain the documented `/x402/<name>` and `/mpp/<name>` forms. Check `/openapi.json` and this reference for the current contract. We aim to preserve compatible behavior within a version.

For breaking changes to a stable API surface, we will announce the change in the documentation and provide `Deprecation` and `Sunset` response headers where applicable, with at least 90 days' notice before removal. Preview behavior and upstream availability can change sooner.

## Authentication and payment

No API key, account, or subscription is required. Payment credentials authorize a specific quoted call and replace a reusable API key. Supported protocols on this service: x402 on Base, Polygon and Solana or MPP on Base.

For x402, send a valid request without payment and read the HTTP 402 `PAYMENT-REQUIRED` challenge. Sign the offered amount and network, then retry the same request with `PAYMENT-SIGNATURE`. For MPP, the unpaid response includes `WWW-Authenticate: Payment`; retry with the matching `Authorization: Payment` credential. Never authorize a quote you have not checked.

A paid request delivers data only after settlement succeeds. The protocols accept their corresponding payment credential; use the route family's documented path and the exact body used to obtain the quote.

See the [API deprecation policy](/deprecation-policy) for route lifecycle commitments.

## Request examples

inbox-1h
First send this valid request without payment. The response is HTTP 402 with the current quote. Review and sign that quote, then retry the same request and body at the MPP path with `Authorization: Payment`, or retry the x402 path with `PAYMENT-SIGNATURE`.

`curl -i -X POST 'https://agmail.shveik.dev/x402/inbox-1h' -H 'content-type: application/json' --data-binary @- <<'JSON'
{"name":"acme42"}
JSON`

Paid retry paths: `https://agmail.shveik.dev/x402/inbox-1h` (x402) or `https://agmail.shveik.dev/mpp/inbox-1h` (MPP), with the same JSON body and matching `PAYMENT-SIGNATURE` or `Authorization: Payment` credential.
inbox-1h-renew
First send this valid request without payment. The response is HTTP 402 with the current quote. Review and sign that quote, then retry the same request and body at the MPP path with `Authorization: Payment`, or retry the x402 path with `PAYMENT-SIGNATURE`.

`curl -i -X POST 'https://agmail.shveik.dev/x402/inbox-1h-renew' -H 'content-type: application/json' --data-binary @- <<'JSON'
{"inbox_id":"ib_0123456789ab","secret":"agm_0123456789abcdef0123456789abcdef"}
JSON`

Paid retry paths: `https://agmail.shveik.dev/x402/inbox-1h-renew` (x402) or `https://agmail.shveik.dev/mpp/inbox-1h-renew` (MPP), with the same JSON body and matching `PAYMENT-SIGNATURE` or `Authorization: Payment` credential.
inbox-4h
First send this valid request without payment. The response is HTTP 402 with the current quote. Review and sign that quote, then retry the same request and body at the MPP path with `Authorization: Payment`, or retry the x402 path with `PAYMENT-SIGNATURE`.

`curl -i -X POST 'https://agmail.shveik.dev/x402/inbox-4h' -H 'content-type: application/json' --data-binary @- <<'JSON'
{"name":"acme42"}
JSON`

Paid retry paths: `https://agmail.shveik.dev/x402/inbox-4h` (x402) or `https://agmail.shveik.dev/mpp/inbox-4h` (MPP), with the same JSON body and matching `PAYMENT-SIGNATURE` or `Authorization: Payment` credential.
inbox-4h-renew
First send this valid request without payment. The response is HTTP 402 with the current quote. Review and sign that quote, then retry the same request and body at the MPP path with `Authorization: Payment`, or retry the x402 path with `PAYMENT-SIGNATURE`.

`curl -i -X POST 'https://agmail.shveik.dev/x402/inbox-4h-renew' -H 'content-type: application/json' --data-binary @- <<'JSON'
{"inbox_id":"ib_0123456789ab","secret":"agm_0123456789abcdef0123456789abcdef"}
JSON`

Paid retry paths: `https://agmail.shveik.dev/x402/inbox-4h-renew` (x402) or `https://agmail.shveik.dev/mpp/inbox-4h-renew` (MPP), with the same JSON body and matching `PAYMENT-SIGNATURE` or `Authorization: Payment` credential.
inbox-24h
First send this valid request without payment. The response is HTTP 402 with the current quote. Review and sign that quote, then retry the same request and body at the MPP path with `Authorization: Payment`, or retry the x402 path with `PAYMENT-SIGNATURE`.

`curl -i -X POST 'https://agmail.shveik.dev/x402/inbox-24h' -H 'content-type: application/json' --data-binary @- <<'JSON'
{"name":"acme42"}
JSON`

Paid retry paths: `https://agmail.shveik.dev/x402/inbox-24h` (x402) or `https://agmail.shveik.dev/mpp/inbox-24h` (MPP), with the same JSON body and matching `PAYMENT-SIGNATURE` or `Authorization: Payment` credential.
inbox-24h-renew
First send this valid request without payment. The response is HTTP 402 with the current quote. Review and sign that quote, then retry the same request and body at the MPP path with `Authorization: Payment`, or retry the x402 path with `PAYMENT-SIGNATURE`.

`curl -i -X POST 'https://agmail.shveik.dev/x402/inbox-24h-renew' -H 'content-type: application/json' --data-binary @- <<'JSON'
{"inbox_id":"ib_0123456789ab","secret":"agm_0123456789abcdef0123456789abcdef"}
JSON`

Paid retry paths: `https://agmail.shveik.dev/x402/inbox-24h-renew` (x402) or `https://agmail.shveik.dev/mpp/inbox-24h-renew` (MPP), with the same JSON body and matching `PAYMENT-SIGNATURE` or `Authorization: Payment` credential.

## Command-line tool

A small shell script (needs only sh and curl) lists the endpoints, prints the quote of a call and sends a call you have already signed. It never holds keys and never signs a payment.

`curl -fsSL https://agmail.shveik.dev/install.sh | sh
agmail help
agmail endpoints`

Commands: help, endpoints, docs, pricing, openapi, quote, call, health, version, update. Exit code 3 means a payment is required and the quote was printed. The installer puts the script in ~/.local/bin; its source is at /cli.