Documentación de la API

Resumen

Cada bandeja de destino necesita una clave API registrada. Después puedes enviar con créditos o pagar por correo.

• Créditos: GET/POST /v1/message con tu clave (plan gratis 300 correos; de pago $5 por 50,000).
• x402: paga $0.001 USDC por correo en Base mainnet sin comprar un paquete de créditos.
• MCP: POST /v1/mcp para agentes de IA (send_email, get_balance, ayudas de pago y registro).

Registro

Debes registrar un correo antes de enviar. La confirmación es un paso humano.

1. POST /v1/register con {"email":"you@example.com"}.
2. Abre el correo de confirmación de AWS SNS (a menudo de no-reply@sns.amazonaws.com).
3. Haz clic en Confirm subscription.
4. Copia la clave API de ese correo y guárdala en secreto. La API de registro no devuelve la clave.

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

Los agentes deben pedir al usuario que confirme el correo SNS y pegue la clave antes de llamar a las APIs de envío.

Enviar con créditos

GET /v1/message es el camino más simple:

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

O POST JSON:

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

Gratis: 300 correos, máx 10/min. De pago: 50,000 correos, máx 120/min. Sin cuota mensual.

Pagos máquina (x402)

xtuis acepta pago por correo vía el protocolo x402. Aún se requiere una clave API confirmada para saber a qué bandeja entregar.

• Precio: $0.001 USDC por correo (1000 unidades atómicas).
• Red: eip155:8453 (Base mainnet).
• Activo: USDC 0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913 (nombre EIP-712 "USD Coin", versión "2").

1. Envía tu solicitud de correo sin pago — POST https://api.xtuis.com/v1/x402/message con JSON {"key":"YOUR_KEY","subject":"...","body":"..."}. En esta primera llamada no envíes PAYMENT-SIGNATURE.
2. La API responde con HTTP 402 y un encabezado PAYMENT-REQUIRED que indica a tu wallet cuánto USDC pagar ($0.001 en Base).
3. Firma el pago con tu wallet y reintenta la misma solicitud con el encabezado PAYMENT-SIGNATURE (base64) y X-Xtuis-Key: YOUR_KEY.
4. Si el pago se liquida, recibes HTTP 200, se envía el correo y la respuesta incluye el encabezado 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"}'

También puedes POST /v1/message con "rail":"x402" en el mismo flujo de pago.

Servidor MCP

JSON-RPC sobre HTTP. initialize funciona sin clave; tools/list y tools/call requieren tu clave.

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

• send_email — envía una notificación usando créditos
• get_balance — créditos y plan de la clave
• get_machine_payment_instructions — endpoints y encabezados x402 / MPP
• get_registration_instructions — cómo registrar y pedir al usuario la clave 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"}'

Guía para agentes de IA

Después de llamar a register, muestra al usuario una solicitud de confirmación clara. Mensaje sugerido:

Empecé el registro de xtuis para tu correo. Revisa tu bandeja por un correo de confirmación de AWS SNS, haz clic en "Confirm subscription", luego pega tu clave API aquí para que pueda enviar notificaciones.