AI Email Service — API Docs

Receive-only email addresses for AI agents. No sending. Ever.

Overview

This service provides receive-only email addresses that AI agents can use to:

• Sign up for services (GitHub, Stripe, Slack, etc.)
• Receive verification codes and OTPs
• Get password reset links
• Read account notifications

Quick Start

1. Get an API Key

POST /v1/api-key/create
Content-Type: application/json

{ "wallet_address": "0x..." }  // optional

Returns: { "api_key": "ak_..." }

2. Create a Mailbox

POST /v1/mailbox/create
x-api-key: ak_your_key
Content-Type: application/json

{ "payment": "trial" }  // or "checkout" or "crypto"

Returns your email address, status, and expiry info.

3. Use the Email Address

Sign up for any service using your new email. When they send a verification email, read it via the API.

4. Read Messages

GET /v1/mailbox/{id}/messages
x-api-key: ak_your_key

5. Extract Verification Codes

GET /v1/mailbox/{id}/codes
x-api-key: ak_your_key

Auto-extracts OTP codes, verification codes, and confirmation links from your emails.

Authentication

All requests (except POST /v1/api-key/create and GET /health) require an API key.

Pass it as a header: x-api-key: ak_your_key or Authorization: Bearer ak_your_key

Endpoints

Pricing

• Free trial: 1 mailbox, 24 hours, 1 per IP address. Limited features.
• Paid: $10/year per mailbox. Full features. Persistent address.
• Bulk: 10+ mailboxes = $8/year each. 100+ = $5/year each.

Trial vs Paid

Webhooks

Get notified instantly when emails arrive. Create webhook subscriptions to receive real-time POST requests to your URL.

Webhook Payload

POST https://your-server.com/webhook
Content-Type: application/json
x-webhook-signature: sha256=a1b2c3d4e5...

{
  "event": "message.received",
  "mailbox_id": "mbx_abc123",
  "email": "agent-x7k@aiemailservice.com",
  "message": {
    "id": "msg_xyz789",
    "from": "noreply@github.com",
    "subject": "Verify your email address",
    "text": "Your verification code is 847291",
    "extracted_codes": ["847291"],
    "received_at": "2026-02-14T12:00:00Z"
  }
}

Signature Verification

If you set a secret when creating the webhook, every request includes an x-webhook-signature header. Verify it with HMAC-SHA256:

const crypto = require('crypto');
const signature = crypto.createHmac('sha256', secret).update(rawBody).digest('hex');
const expected = req.headers['x-webhook-signature'].replace('sha256=', '');
if (signature !== expected) throw new Error('Invalid signature');

CLI Tool

Manage your mailboxes from the command line. Install globally via npm:

npm install -g https://aiemailservice.com/aiemailservice-1.0.0.tgz

Commands

aiemailservice init              # Save your API key locally
aiemailservice create            # Create a new mailbox
aiemailservice list              # List all mailboxes
aiemailservice messages <id>     # List messages in a mailbox
aiemailservice read <id> <msgId> # Read a specific message
aiemailservice wait <id>         # Long-poll for new messages
aiemailservice codes <id>        # Extract verification codes
aiemailservice delete <id>       # Delete a mailbox
aiemailservice status <id>       # Check mailbox status

Add --json to any command for machine-readable JSON output.

MCP Server

Connect AI agents (Claude, OpenAI, etc.) natively using the Model Context Protocol server:

npm install -g https://aiemailservice.com/aiemailservice-mcp-1.0.0.tgz

The MCP server exposes 10 tools that let AI agents create mailboxes, read messages, extract codes, manage webhooks, and more — all through their native tool-calling interface. No HTTP plumbing required.

Multi-Agent Sharing

Your API key is stateless and portable. Any agent or machine with the key can access the same mailboxes — no device-specific tokens, no local state to sync.

• One key = full access from anywhere. Pure REST API, no sessions, no cookies.
• Up to 5 mailboxes per key. Need isolation? Create separate API keys (they're free).
• Works across CI pipelines, cloud functions, local dev, multiple agents — simultaneously.

Example: Full Signup Flow

// 1. Create API key
const key = await fetch('/v1/api-key/create', { method: 'POST' }).then(r => r.json());

// 2. Create mailbox
const mailbox = await fetch('/v1/mailbox/create', {
  method: 'POST',
  headers: { 'x-api-key': key.api_key, 'Content-Type': 'application/json' },
  body: JSON.stringify({ payment: 'trial' })
}).then(r => r.json());

console.log('My email:', mailbox.email);
// → agent-abc123@mailpulse.co

// 3. Sign up for GitHub using mailbox.email
// ... (your browser automation here)

// 4. Wait for verification email (paid only)
const result = await fetch(
  `/v1/mailbox/${mailbox.mailbox_id}/wait?from=noreply@github.com&timeout=30`,
  { headers: { 'x-api-key': key.api_key } }
).then(r => r.json());

// 5. Get the verification code
console.log('Code:', result.message.extracted_codes[0]);
// → 847291

// 6. Enter the code to complete signup