Email with StableEmail

Send emails, manage inboxes, and run custom subdomains via x402 payments at https://stableemail.dev.

Setup

See rules/getting-started.md for installation and wallet setup.

Quick Reference

Free Management Endpoints

Free endpoints use SIWX wallet authentication (handled automatically by npx agentcash@latest fetch).

Send an Email

Send from the shared relay@stableemail.dev address:

npx agentcash@latest fetch https://stableemail.dev/api/send -m POST -b '{
  "to": ["recipient@example.com"],
  "subject": "Hello from x402",
  "html": "<h1>Hi!</h1><p>This email was sent via x402 payments.</p>",
  "text": "Hi! This email was sent via x402 payments.",
  "replyTo": "your-real-email@example.com"
}'

Parameters:

• to — array of recipient emails (required)
• subject — email subject (required)
• html and/or text — email body (at least one required)
• replyTo — reply-to address (optional but recommended)
• attachments — array of {content, contentType, filename} (optional, max 5, base64 encoded, ~3.75MB limit each)

Attachment example:

{
  "attachments": [{
    "content": "base64-encoded-content...",
    "contentType": "application/pdf",
    "filename": "report.pdf"
  }]
}

For calendar invites, use contentType: "text/calendar; method=REQUEST".

Forwarding Inbox

Buy username@stableemail.dev for $1/month. Emails are forwarded to your real address and/or retained for programmatic access.

Buy an Inbox

npx agentcash@latest fetch https://stableemail.dev/api/inbox/buy -m POST -b '{
  "username": "alice",
  "forwardTo": "alice@gmail.com"
}'

Omit forwardTo to use as a programmatic-only mailbox (retainMessages auto-enabled).

Send from Inbox

npx agentcash@latest fetch https://stableemail.dev/api/inbox/send -m POST -b '{
  "username": "alice",
  "to": ["bob@example.com"],
  "subject": "Hello",
  "html": "<p>Hi Bob</p>",
  "text": "Hi Bob"
}'

Top Up Inbox

npx agentcash@latest fetch https://stableemail.dev/api/inbox/topup -m POST -b '{"username": "alice"}'

Anyone can top up any inbox. Top-ups stack. Bulk discounts: 90 days/$2.50 (17% off), 365 days/$8 (34% off).

Cancel and Refund

npx agentcash@latest fetch https://stableemail.dev/api/inbox/cancel -m POST -b '{"username": "alice"}'

Returns pro-rata USDC refund on-chain automatically.

Read Inbox Messages

Enable message retention, then read messages programmatically.

Enable Retention

npx agentcash@latest fetch https://stableemail.dev/api/inbox/update -m POST -b '{"username": "alice", "retainMessages": true}'

List Messages

npx agentcash@latest fetch https://stableemail.dev/api/inbox/messages -m POST -b '{"username": "alice", "limit": 20}'

Read a Message

npx agentcash@latest fetch https://stableemail.dev/api/inbox/messages/read -m POST -b '{"messageId": "msg_abc123"}'

Returns full message with from, to, subject, date, text, html, and attachment download URLs (URLs expire after 1 hour). Message content and attachments are retained for 90 days.

Custom Subdomains

Buy yourname.stableemail.dev for $5 one-time. Send from any address on your subdomain for $0.005/email.

Buy a Subdomain

npx agentcash@latest fetch https://stableemail.dev/api/subdomain/buy -m POST -b '{"subdomain": "yourname"}'

Rules: 3-30 chars, lowercase alphanumeric + hyphens. DNS verification takes ~5 minutes.

Send from Subdomain

npx agentcash@latest fetch https://stableemail.dev/api/subdomain/send -m POST -b '{
  "from": "support@yourname.stableemail.dev",
  "to": ["customer@example.com"],
  "subject": "Your order confirmation",
  "html": "<p>Thank you for your order!</p>"
}'

Create Subdomain Inboxes

Create per-address inboxes on your subdomain ($0.25 each, max 100 inboxes, 500 messages each):

npx agentcash@latest fetch https://stableemail.dev/api/subdomain/inbox/create -m POST -b '{
  "subdomain": "yourname",
  "localPart": "support",
  "forwardTo": "team@company.com"
}'

Catch-All Forwarding

Forward all unmatched addresses on your subdomain:

npx agentcash@latest fetch https://stableemail.dev/api/subdomain/update -m POST -b '{"subdomain": "yourname", "catchAllForwardTo": "catch-all@company.com"}'

Manage Authorized Signers

Allow other wallets to send from your subdomain:

npx agentcash@latest fetch https://stableemail.dev/api/subdomain/signers -m POST -b '{"action": "add", "subdomain": "yourname", "walletAddress": "0x..."}'

Images in Emails

Host images on StableUpload or AgentUpload, then reference in HTML:

<img src="https://f.stableupload.dev/abc/photo.png" alt="Photo" />

Most email clients strip data URIs — always use hosted URLs.

Workflows

Quick Send

• (Optional) Check balance: npx agentcash@latest balance
• Send email via /api/send
• Confirm delivery via messageId

Set Up Professional Email

• Buy subdomain ($5)
• Wait for DNS verification (~5 min)
• Create inboxes for team members ($0.25 each)
• Set up catch-all forwarding
• Send from custom addresses ($0.005 each)

Programmatic Mailbox

• Buy inbox with no forwardTo ($1)
• Messages are retained automatically (90 days)
• List and read messages via API ($0.001 each)
• Delete messages when processed (free)

Cost Estimation