API 文档

xtuis.com 是通过一次 HTTP 请求向自己发送邮件的通知服务。无需 SMTP，无需 SDK。

概述

每个收件邮箱都需要已注册的 API 密钥。之后可用额度发送，也可以按封付费。

额度：使用密钥调用 GET/POST /v1/message（免费 300 封；付费 $5 共 50,000 封）。
x402：在 Base 主网上每封支付 $0.001 USDC，无需购买额度包。
MCP：POST /v1/mcp 面向 AI 代理（send_email、get_balance、支付与注册指引）。

注册

发送前必须注册邮箱。确认步骤需人工完成。

向 /v1/register POST {"email":"you@example.com"}。
打开 AWS SNS 确认邮件（常见发件人 no-reply@sns.amazonaws.com）。
点击 Confirm subscription。
从该邮件复制 API 密钥并妥善保管。注册接口不会返回密钥。

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

代理应提示用户确认 SNS 邮件，并把密钥粘贴回来，再调用发送接口。

使用额度发送

最简单的方式是 GET /v1/message：

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

或 POST JSON：

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

免费：300 封，每分钟最多 10 封。付费：50,000 封，每分钟最多 120 封。无月费。

机器支付（x402）

xtuis 通过 x402 协议接受按封付费。仍需要已确认的 API 密钥，以便知道投递到哪个邮箱。

价格：每封 $0.001 USDC（1000 atomic units）。
网络：eip155:8453（Base 主网）。
资产：USDC 0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913（EIP-712 名称为 "USD Coin"，版本 "2"）。

先发送未付费的邮件请求 — POST https://api.xtuis.com/v1/x402/message，JSON 为 {"key":"YOUR_KEY","subject":"...","body":"..."}。第一次请求不要带 PAYMENT-SIGNATURE。
API 返回 HTTP 402 和 PAYMENT-REQUIRED 头，其中包含钱包需要支付的金额（Base 上 $0.001 USDC）。
用钱包签名该付款，然后重试同一请求，并加上头 PAYMENT-SIGNATURE（base64）和 X-Xtuis-Key: YOUR_KEY。
付款成功后返回 HTTP 200，邮件会发出，响应中包含 PAYMENT-RESPONSE 头。

# 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"}'

也可向 /v1/message POST 并设置 "rail":"x402" 走相同付费流程。

MCP 服务

HTTP 上的 JSON-RPC。initialize 可不带密钥；tools/list 与 tools/call 需要密钥。

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

send_email — 使用额度发送一封通知
get_balance — 查看密钥额度与套餐
get_machine_payment_instructions — x402 / MPP 端点与请求头
get_registration_instructions — 如何注册并请用户提供 SNS 确认后的密钥

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"}'

给 AI 代理的指引

调用 register 后，应向用户展示清晰的确认请求。建议文案：

我已为你的邮箱开始 xtuis 注册。请查收 AWS SNS 确认邮件，点击 "Confirm subscription"，然后把 API 密钥粘贴给我，以便发送通知。

返回首页