Create a per-address inbox on your StableEmail subdomain for $0.25 via micropayment.
What it does
This endpoint creates a new inbox on a custom subdomain you own at stableemail.dev. For example, calling it with subdomain "craig" and localPart "biden" provisions the address biden@craig.stableemail.dev. The inbox can optionally forward incoming mail to a real email address, or retain messages for programmatic retrieval via the messages API, or both. Each call costs $0.25 USDC, paid inline via the x402/MPP micropayment protocol on Base, Solana, or Tempo — no API keys or accounts required. The payer's wallet must be the subdomain owner.
Each subdomain supports up to 100 inboxes, and each inbox retains up to 500 messages (content available for 90 days). If forwardTo is omitted, retainMessages is automatically enabled so the inbox works as a programmatic-only mailbox. Unmatched addresses on the subdomain fall through to the catch-all forwarder if configured, or are silently dropped.
This endpoint is part of the broader StableEmail platform, which also offers shared-domain email sending ($0.02/email), subdomain purchases ($5), forwarding inboxes on the root domain ($1/month), and full inbox message read/list/delete APIs. All paid endpoints use the same 402 payment challenge flow: send a POST, receive a 402 with payment requirements, sign the USDC payment, and resend. The agentcash CLI or MCP server handles this automatically.
Capabilities
Use cases
- —AI agents provisioning disposable or project-specific email addresses on a custom subdomain
- —Creating forwarding inboxes for team members on a branded subdomain without traditional email hosting
- —Setting up programmatic mailboxes to receive and process inbound emails via API
- —Automating customer-facing email addresses (e.g., support@yourname.stableemail.dev) with forwarding
Fit
Best for
- —Agents and bots that need to create email addresses programmatically without signup
- —Developers wanting pay-as-you-go email inbox provisioning with no recurring commitments
- —Projects needing branded subdomain email addresses with API-accessible message storage
Not for
- —High-volume email marketing or bulk mailing (500 message cap per inbox)
- —Users who need a traditional full-featured email client with IMAP/SMTP access
- —Organizations requiring email on their own custom domain (only *.stableemail.dev subdomains supported)
Quick start
# 1. POST to create inbox (returns 402 with payment challenge)
curl -X POST https://stableemail.dev/api/subdomain/inbox/create \
-H 'Content-Type: application/json' \
-d '{"subdomain": "craig", "localPart": "biden", "forwardTo": "joe@gmail.com"}'
# 2. Pay $0.25 USDC via x402/MPP, resend with payment header
# Or use: npx agentcash fetch POST https://stableemail.dev/api/subdomain/inbox/create ...Example
Request
{
"forwardTo": "joe@gmail.com",
"localPart": "biden",
"subdomain": "craig"
}Response
{
"inbox": "biden@craig.stableemail.dev",
"success": true,
"messageLimit": 500,
"retainMessages": true
}Endpoint
Quality
Full OpenAPI 3.1 schema with detailed request/response documentation and clear pricing. The endpoint is a POST-only route so the HEAD/GET probe returning 405 is expected and does not indicate downtime. The root site loads successfully (200). Response 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.
- —Response schema is described in guidance text but not formally defined in the OpenAPI spec's responses section.
- —Subdomain must already be purchased ($5) before inboxes can be created on it.
Citations
- —Creating a subdomain inbox costs $0.25 USDChttps://stableemail.dev
- —Max 100 inboxes per subdomain, 500 messages per inboxhttps://stableemail.dev/.well-known/x402
- —Payment accepted on Base, Solana, or Tempo via x402/MPP protocolhttps://stableemail.dev
- —Message content and attachments retained for 90 dayshttps://stableemail.dev/.well-known/x402
- —forwardTo is optional — omit for programmatic-only mailbox with retainMessages auto-enabledhttps://stableemail.dev/.well-known/x402
- —Payer wallet must be the subdomain ownerhttps://stableemail.dev/.well-known/x402