Read a single subdomain inbox message via micropayment — $0.001 USDC per call, no API keys.
What it does
This endpoint reads a single message from a subdomain inbox on StableEmail. It is part of the StableEmail platform, which provides pay-per-use email delivery, forwarding inboxes, and custom subdomains — all authenticated via x402/MPP micropayments rather than traditional API keys or accounts.
POST a JSON body with a `messageId` and pay $0.001 USDC (on Base, Solana, or Tempo) per call. The response includes the full message: sender, recipients, subject, date, plain text body, HTML body, attachment metadata with 1-hour download URLs, and a received timestamp. Reading a message also marks it as read. Message content is retained for 90 days from receipt. The payer wallet must be the subdomain owner.
This endpoint is one piece of a broader subdomain inbox system. Subdomain owners first purchase a subdomain ($5), create per-address inboxes ($0.25 each, up to 100 per subdomain, 500 messages each), then list and read messages programmatically. Free SIWX-authenticated endpoints handle inbox management (create, update, delete, list). Payment is handled via the x402/MPP protocol: send the request, receive a 402 challenge, sign the USDC payment, and resend. Compatible clients like agentcash handle this flow automatically.
Capabilities
Use cases
- —AI agents reading inbound emails on a custom subdomain inbox programmatically
- —Automated workflows that process incoming messages (e.g., parsing order confirmations, support tickets)
- —Building a custom email client on top of subdomain inboxes without traditional email provider accounts
- —Monitoring a dedicated inbox address for specific incoming communications
Fit
Best for
- —Agents and bots that need programmatic read access to a dedicated email inbox
- —Developers who want email receiving without managing IMAP/POP3 infrastructure
- —Pay-per-use email reading with no subscription or API key setup
Not for
- —High-volume email reading where per-message costs add up (thousands of reads per day)
- —Reading emails from external mailboxes (Gmail, Outlook) — only works with StableEmail subdomain inboxes
- —Users who need messages retained longer than 90 days
Quick start
curl -X POST https://stableemail.dev/api/subdomain/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/subdomain/inbox/messages/read '{"messageId":"msg-abc123"}'Example
Request
{
"messageId": "msg-abc123"
}Response
{
"message": {
"id": "msg-abc123",
"to": [
"biden@craig.stableemail.dev"
],
"date": "2025-01-15T10:30:00Z",
"from": "sender@example.com",
"html": "<p>Hi, just confirming our meeting tomorrow at 2pm.</p>",
"text": "Hi, just confirming our meeting tomorrow at 2pm.",
"subject": "Meeting tomorrow",
"receivedAt": "2025-01-15T10:30:05Z",
"attachments": [
{
"size": 45230,
"filename": "agenda.pdf",
"contentType": "application/pdf"
}
]
},
"success": true
}Endpoint
Quality
Full OpenAPI schema with request/response structure documented, clear pricing ($0.001 USDC), comprehensive guidance text, and live origin (root returns 200). The probe shows 405 on HEAD/GET which is expected since this is a POST-only endpoint. Response schema details come from guidance text rather than formal OpenAPI response schemas, slightly reducing the score.
Warnings
- —Probe returned 405 because HEAD/GET were tried on a POST-only endpoint; the endpoint is expected to be live when called with POST and a valid payment.
- —No formal OpenAPI response schema defined — response structure is documented only in the x-guidance text.
- —Message content is retained for only 90 days from receipt.
Citations
- —Read a single subdomain inbox message costs $0.001 USDChttps://stableemail.dev/.well-known/x402
- —Returns message with id, from, to, subject, date, text, html, attachments, receivedAt and marks as readhttps://stableemail.dev
- —Payment accepted on Base (eip155:8453), Solana, or Tempo via x402/MPP protocolhttps://stableemail.dev
- —Payer wallet must be the subdomain ownerhttps://stableemail.dev
- —Message content and attachments retained for 90 days from receipthttps://stableemail.dev
- —Attachment download URLs expire after 1 hourhttps://stableemail.dev
- —Max 100 inboxes per subdomain, 500 messages per inboxhttps://stableemail.dev