Read a single inbox message via micropayment — $0.001 per call, no API keys.
What it does
This endpoint reads a single inbound email message from a StableEmail forwarding inbox (username@stableemail.dev). It is part of the StableEmail Inbox Messages API, which lets you programmatically access emails received at your purchased inbox address. The inbox must have `retainMessages` enabled.
Send a POST request with `{"messageId": "<id>"}` and pay $0.001 USDC per call via x402 or MPP (settling on Base, Solana, or Tempo). The response includes the full message: sender, recipients, subject, date, plain-text body, HTML body, and attachment metadata (filename, content type, size). Attachment download URLs are returned with a 1-hour expiry. Reading a message also marks it as read. Message content is retained for 90 days from receipt.
No API keys or accounts are required. The payer wallet must be the inbox owner. Authentication and payment are handled through the standard x402/MPP 402-challenge flow: send the request, receive a 402 with payment details, sign the payment, and resend. AI agents can use the agentcash MCP server (`npx -y agentcash@latest`) or CLI for automatic payment negotiation. Note that this is a POST endpoint — HEAD and GET probes return 405, which is expected behavior.
Capabilities
Use cases
- —AI agents reading inbound emails from a programmatic mailbox
- —Automated workflows that process incoming messages and attachments
- —Monitoring a forwarding inbox for specific emails or notifications
- —Building email-driven bots that respond to received messages
- —Reading customer inquiries received at a branded inbox address
Fit
Best for
- —AI agents needing programmatic email access without API key management
- —Low-volume email reading where pay-per-call is cheaper than a subscription
- —Developers integrating email reading into x402/MPP payment workflows
Not for
- —High-volume email processing where per-message costs add up (use traditional IMAP/POP3)
- —Reading emails from external mailboxes not hosted on stableemail.dev
- —Sending emails (use /api/send or /api/inbox/send instead)
Quick start
curl -X POST https://stableemail.dev/api/inbox/messages/read \
-H 'Content-Type: application/json' \
-d '{"messageId": "msg-abc123"}'
# Returns 402 → pay $0.001 USDC via x402/MPP → resend with payment header
# Or use: npx agentcash fetch POST https://stableemail.dev/api/inbox/messages/read '{"messageId":"msg-abc123"}'Example
Request
{
"messageId": "msg-abc123"
}Response
{
"message": {
"id": "msg-abc123",
"to": [
"alice@stableemail.dev"
],
"date": "2025-01-15T10:30:00Z",
"from": "bob@example.com",
"html": "<p>Hi Alice, can we meet at 2pm?</p>",
"text": "Hi Alice, can we meet at 2pm?",
"subject": "Meeting tomorrow",
"receivedAt": "2025-01-15T10:30:05Z",
"attachments": [
{
"size": 45200,
"filename": "agenda.pdf",
"contentType": "application/pdf"
}
]
},
"success": true
}Endpoint
Quality
Full OpenAPI schema with request/response structure documented in guidance. The endpoint is a POST (probed with HEAD/GET returning 405, which is expected). Pricing is clear ($0.001 USDC). Response schema is documented in guidance text but not formally in OpenAPI response definitions. No dedicated docs page exists (404).
Warnings
- —Probe returned 405 because HEAD/GET were used on a POST-only endpoint; the endpoint is live based on OpenAPI and landing page evidence.
- —No formal OpenAPI response schema — response structure is inferred from the x-guidance documentation.
- —The /docs page returns 404; all documentation comes from the OpenAPI guidance field and landing page.
Citations
- —Read a single inbox message costs $0.001 USDChttps://stableemail.dev/.well-known/x402
- —Endpoint accepts POST with {messageId} body and returns full message with text, HTML, attachmentshttps://stableemail.dev
- —Payment accepted on Base, Solana, or Tempo via x402/MPP protocolhttps://stableemail.dev
- —Message content available for 90 days from receipt; attachment download URLs expire in 1 hourhttps://stableemail.dev
- —Payer wallet must be the inbox ownerhttps://stableemail.dev
- —Agent integration via agentcash MCP server (npx -y agentcash@latest)https://stableemail.dev