# Machine Inbox

> Email for agents. Create a short-lived inbox, receive messages, and reply through HTTP.

Base URL: https://machineinbox.com
OpenAPI: https://machineinbox.com/openapi.json
Service metadata: https://machineinbox.com/meta.json
Paid client examples: https://machineinbox.com/examples/README.txt
Payment: Machine Payments Protocol (MPP) stripe/charge, or x402 v2 (USDC on Base mainnet)
Environment: Live payments. The unpaid 402 advertises both rails: WWW-Authenticate: Payment for MPP and PAYMENT-REQUIRED for x402. Pay with either; x402 requests must send an Idempotency-Key. The pro_inbox tier is MPP only.

## Create an inbox

POST /api/v1/inboxes
Price: $2.00 (seven days) or $5.00 (pro: thirty days, 500 messages, 100 MiB, 50 replies per day)
Header: Idempotency-Key (16-200 characters)
Body: none for the standard inbox, or {"product":"pro_inbox"} for the pro tier

The unpaid request returns HTTP 402 with a WWW-Authenticate: Payment challenge for stripe/charge. Use an MPP-compatible client to create a Stripe Shared Payment Token and retry with Authorization: Payment. A successful response includes Payment-Receipt.

Keep the same Idempotency-Key across the challenge and paid retry. It is optional for protocol validators, but strongly recommended for buyer retries and recovery. Treat the key as a secret: it authorizes idempotent replays of the completed purchase, so use a high-entropy value. The inbox purchase includes authenticated replies for the inbox lifetime. Save the returned inbox.id and token. The mailbox token is shown only in the completed response.

## Extend an inbox

POST /api/v1/inboxes/{inboxId}/extend
Price: $1.00 for seven more days
Header: X-Mailbox-Token: mi_live_... (Authorization carries the MPP Payment credential)
Header: Idempotency-Key (a new unique value)

Extends the current expiry by seven days. An inbox can never live more than 35 days into the future. Expired inboxes are deleted and cannot be extended: extend at least ten minutes before expiry.


## Read mail

GET /api/v1/inboxes/{inboxId}/messages
Authorization: Bearer mi_live_...

Reading is included. Poll with a limit of 25. Use nextCursor as the before query parameter.
Fetch one message to receive its text, HTML, rawUrl, and attachment downloadUrl values. Send the same Authorization header when following those URLs.

## Reply

POST /api/v1/inboxes/{inboxId}/messages/{messageId}/reply
Price: included with inbox
Authorization: Bearer mi_live_...
Idempotency-Key: a new unique value
Content-Type: application/json
Body: {"text":"Your reply"}

Replies may go only to a sender address aligned with a passing SPF, DKIM, or DMARC identity recorded by Cloudflare. An unaligned Reply-To is ignored; messages without an authenticated reply target remain readable but cannot be replied to. New outbound conversations, CC, BCC, attachments, and custom headers are not supported.
Poll the returned message ID. Outbound status progresses through queued, sending, sent, and delivered. Deferred means Cloudflare will retry delivery. Bounced, failed, rejected, and complained are terminal states.

## Limits

Standard inbox: seven-day retention, 100 messages, 25 MiB per inbox, 20 replies per UTC day. Pro inbox: thirty-day retention, 500 messages, 100 MiB per inbox, 50 replies per UTC day. All inboxes: 5 MiB per message. Delete an inbox with DELETE /api/v1/inboxes/{inboxId}.

Terms: https://machineinbox.com/terms.html
Acceptable use: https://machineinbox.com/acceptable-use.html
Privacy: https://machineinbox.com/privacy.html