API documentation

Overview

Every destination inbox needs a registered API key. After that you can send with credits or pay per email.

• Credits: GET/POST /v1/message with your key (free tier 300 emails; paid $5 for 50,000).
• x402: pay $0.001 USDC per email on Base mainnet without buying a credit pack.
• MCP: POST /v1/mcp for AI agents (send_email, get_balance, payment + registration helpers).

Registration

You must register an email before sending. Confirmation is a human step.

1. POST /v1/register with {"email":"you@example.com"}.
2. Open the AWS SNS confirmation email (often from no-reply@sns.amazonaws.com).
3. Click Confirm subscription.
4. Copy the API key from that email and keep it secret. The register API does not return the key.

curl -X POST "https://api.xtuis.com/v1/register" \
  -H "Content-Type: application/json" \
  -d '{"email":"you@example.com"}'

Agents should tell the user to confirm the SNS email and paste the key back before calling send APIs.

Send with credits

GET /v1/message is the simplest path:

curl "https://api.xtuis.com/v1/message?key=YOUR_KEY&subject=Hello&body=World"

Or POST JSON:

curl -X POST "https://api.xtuis.com/v1/message" \
  -H "Content-Type: application/json" \
  -d '{"key":"YOUR_KEY","subject":"Hello","body":"World"}'

Free: 300 emails, max 10/min. Paid: 50,000 emails, max 120/min. No monthly fee.

Machine payments (x402)

xtuis accepts pay-per-email via the x402 protocol. A confirmed API key is still required so delivery knows which inbox to use.

• Price: $0.001 USDC per email (1000 atomic units).
• Network: eip155:8453 (Base mainnet).
• Asset: USDC 0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913 (EIP-712 name "USD Coin", version "2").

1. Send your email request without payment — POST https://api.xtuis.com/v1/x402/message with JSON {"key":"YOUR_KEY","subject":"...","body":"..."}. Do not send PAYMENT-SIGNATURE on this first call.
2. The API responds with HTTP 402 and a PAYMENT-REQUIRED header. That header tells your wallet how much USDC to pay ($0.001 on Base).
3. Sign the payment with your wallet, then retry the same request with header PAYMENT-SIGNATURE (base64) and X-Xtuis-Key: YOUR_KEY.
4. If payment settles, you get HTTP 200, the email is sent, and the response includes a PAYMENT-RESPONSE header.

# Challenge (no payment)
curl -i -X POST "https://api.xtuis.com/v1/x402/message" \
  -H "Content-Type: application/json" \
  -d '{"key":"YOUR_KEY","subject":"Hello","body":"Paid via x402"}'

# Paid retry (after signing PAYMENT-REQUIRED)
curl -i -X POST "https://api.xtuis.com/v1/x402/message" \
  -H "Content-Type: application/json" \
  -H "X-Xtuis-Key: YOUR_KEY" \
  -H "PAYMENT-SIGNATURE: <base64>" \
  -d '{"key":"YOUR_KEY","subject":"Hello","body":"Paid via x402"}'

You can also POST /v1/message with "rail":"x402" on the same paid flow.

MCP server

JSON-RPC over HTTP. initialize works without a key; tools/list and tools/call require your key.

POST https://api.xtuis.com/v1/mcp
Authorization: Bearer YOUR_KEY
# or: X-Xtuis-Key: YOUR_KEY

• send_email — send one notification using credits
• get_balance — credits and plan for the key
• get_machine_payment_instructions — x402 / MPP endpoints and headers
• get_registration_instructions — how to register and ask the user for the SNS key

curl -s -X POST "https://api.xtuis.com/v1/mcp" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_KEY" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

Guidance for AI agents

After calling register, show the user a clear confirmation request. Suggested message:

I started xtuis registration for your email. Please check your inbox for an AWS SNS confirmation email, click "Confirm subscription", then paste your API key here so I can send notifications.