List messages in a subdomain inbox via micropayment — $0.001 per call, no API keys.
What it does
This endpoint lists messages stored in a per-address inbox on a custom subdomain of StableEmail (e.g., `biden@craig.stableemail.dev`). It is a POST endpoint protected by an x402/MPP micropayment of $0.001 USDC per call, settled on Base, Solana, or Tempo. The payer wallet must be the subdomain owner. The request body specifies the subdomain name, the local part of the inbox address, and optional pagination parameters (cursor and limit up to 100, default 20). The response includes a paginated list of message summaries, a nextCursor for pagination, the current message count, the 500-message inbox limit, and an optional warning when the inbox is at or near 80% capacity.
This endpoint is part of StableEmail's broader suite of pay-per-use email services. Subdomain owners first purchase a subdomain ($5) and create inboxes on it ($0.25 each, up to 100 per subdomain). Inbound emails are retained for programmatic access for 90 days. Individual messages can then be read via the companion `/api/subdomain/inbox/messages/read` endpoint ($0.001 each). Management operations like inbox creation, deletion, and settings updates use free SIWX wallet authentication rather than payments.
StableEmail requires no API keys or accounts. Authentication and authorization are handled entirely through the x402/MPP payment protocol — the wallet address in the payment header identifies the caller. AI agents can integrate via the agentcash MCP server (`npx -y agentcash@latest`) or any x402/MPP-compatible HTTP client paying USDC.
Capabilities
Use cases
- —AI agent checking a dedicated inbox for inbound replies or notifications
- —Automated workflow polling a subdomain inbox for incoming messages
- —Monitoring a project-specific email address for support requests
- —Building a custom email dashboard backed by StableEmail subdomains
Fit
Best for
- —AI agents needing programmatic email receive capability without API key management
- —Developers who want pay-per-use inbox access with no subscription commitment
- —Projects requiring per-address inboxes on a custom subdomain with wallet-based access control
Not for
- —High-volume email ingestion requiring thousands of messages per minute (500-message inbox cap)
- —Users who need traditional IMAP/POP3 email client access
- —Scenarios requiring free or unlimited inbox reads (each list call costs $0.001)
Quick start
# List messages in a subdomain inbox (requires x402/MPP payment of $0.001 USDC)
curl -X POST https://stableemail.dev/api/subdomain/inbox/messages \
-H 'Content-Type: application/json' \
-d '{"subdomain": "craig", "localPart": "biden", "limit": 20}'Example
Request
{
"limit": 20,
"localPart": "biden",
"subdomain": "craig"
}Response
{
"success": true,
"messages": [
{
"id": "msg-abc123",
"read": false,
"subject": "Meeting tomorrow",
"fromEmail": "sender@example.com",
"receivedAt": "2025-01-15T10:30:00Z"
},
{
"id": "msg-def456",
"read": true,
"subject": "Your receipt",
"fromEmail": "noreply@service.com",
"receivedAt": "2025-01-14T08:15:00Z"
}
],
"nextCursor": "msg-def456",
"messageCount": 42,
"messageLimit": 500
}Endpoint
Quality
Full OpenAPI 3.1 schema with detailed request/response documentation and clear pricing. The endpoint is a POST route so the HEAD/GET probe returning 405 is expected, not a liveness failure. The response body schema is documented in guidance text but not formally in the OpenAPI responses section, which slightly reduces the score.
Warnings
- —Probe returned 405 because HEAD/GET were used on a POST-only endpoint; this does not indicate the endpoint is down.
- —The OpenAPI spec does not include a formal response schema for 200 responses — response structure is documented only in the guidance text.
- —Example response JSON is inferred from guidance documentation, not captured from a live call.
Citations
- —Endpoint costs $0.001 USDC per call on Base, Solana, or Tempohttps://stableemail.dev
- —Request body requires subdomain and localPart fields, with optional cursor and limit (max 100, default 20)https://stableemail.dev/.well-known/x402
- —Max 500 messages per inbox, warning at >=80% capacityhttps://stableemail.dev
- —Payer wallet must be the subdomain ownerhttps://stableemail.dev
- —Message content and attachments retained for 90 days from receipthttps://stableemail.dev
- —AI agents can integrate via agentcash MCP server (npx -y agentcash@latest)https://stableemail.dev