Boring on purpose.
Documented on purpose.

One inbox, two directions.

terriblemail exposes a tenant-scoped JSON API at https://api.terriblemail.com. Each server-generated inbox address can receive mail and can also be selected as the sender for outbound mail. Replies return to that same inbox.

Send your first message.

1. Create and verify an account.Sign up, verify your email, and open the dashboard.
2. Create an inbox.The service generates a readable address such as quiet-lantern-k7m2qd9x@terriblemail.com.
3. Create an API key.Select the send scope. The plaintext key is shown once.
4. Send.The from address must be an enabled inbox owned by the authenticated account.

curl https://api.terriblemail.com/v1/emails \
  -H 'Authorization: Bearer tm_live_REPLACE_ME' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: welcome-user-1842' \
  -d '{
    "from": "quiet-lantern-k7m2qd9x@terriblemail.com",
    "to": ["person@example.com"],
    "subject": "Hello from a tiny script",
    "text": "It worked."
  }'

A successful first request returns 201 Created. Repeating the same request with the same idempotency key within 24 hours returns the original message with 200 OK instead of sending twice.

Scoped Bearer keys.

Send the key on every protected REST or MCP request:

Authorization: Bearer tm_live_REPLACE_ME

Keys are displayed once and stored as SHA-256 hashes. A key may have an expiry, a per-minute ceiling, a recipient allowlist, and independent readable and writable inbox lists. Empty inbox lists mean all inboxes on the account.

The service also enforces an account send ceiling by plan: Free 10, Developer 200, and Growth 1,000 requests per minute. A lower per-key limit wins. Use recipient and inbox restrictions for scripts and agents that do not need account-wide access.

Endpoints at a glance.

Protected operations accept and return JSON. Unknown request fields are rejected. Unless an endpoint says otherwise, authenticate with a Bearer key and grant the required scope.

{
  "filename": "invoice.pdf",
  "content_type": "application/pdf",
  "content_base64": "JVBERi0xLjQK...",
  "disposition": "attachment",
  "content_id": "optional-inline-id"
}

{
  "id": "msg_...",
  "status": "sent",
  "provider_id": "...",
  "created_at": "2026-07-18T12:00:00Z"
}

curl 'https://api.terriblemail.com/v1/messages?inbox_id=inb_123&direction=inbound&limit=25' \
  -H 'Authorization: Bearer tm_live_REPLACE_ME'

{
  "data": [{ "id": "msg_...", "direction": "inbound", "status": "received" }],
  "has_more": false,
  "next_cursor": "opaque-older-position",
  "after_cursor": "opaque-newer-position"
}

{
  "url": "https://private-object-store.example/...",
  "expires_at": "2026-07-18T12:05:00Z"
}

{
  "name": "Support agent",
  "webhook_url": "https://example.com/hooks/terriblemail"
}

Signed inbound delivery.

Set webhook_url while creating an inbox. terriblemail posts one of three event types when SES accepts mail for that inbox:

{
  "id": "evt_...",
  "type": "message.received",
  "created_at": "2026-07-18T12:00:00Z",
  "data": { "message": { "id": "msg_...", "status": "received" } }
}

Verify the signature

The Terriblemail-Signature header has the form t=UNIX_SECONDS,v1=HEX_DIGEST. Compute HMAC-SHA256 with the inbox's one-time webhook secret over the exact string timestamp + "." + raw_request_body, compare the digest in constant time, and reject timestamps outside your replay window.

expected = HMAC_SHA256(webhook_secret, timestamp + "." + raw_body)
constant_time_compare(hex(expected), v1)

Return any 2xx response only after accepting the event. Delivery failures are retried by the inbound queue, so deduplicate by the stable event id. Webhook destinations must remain public HTTPS; private, loopback, link-local, unsafe DNS, and unsafe redirects are rejected.

Give an agent a mailbox.

The stateless Streamable HTTP endpoint is https://api.terriblemail.com/mcp. It uses JSON-RPC 2.0, negotiates MCP protocol version 2025-11-25, authenticates every call with the same Bearer keys as REST, and has no server-side session or SSE stream.

{
  "mcpServers": {
    "terriblemail": {
      "url": "https://api.terriblemail.com/mcp",
      "headers": {
        "Authorization": "Bearer tm_live_REPLACE_ME"
      }
    }
  }
}

tools/list advertises only operations granted by the key, and tools/call authorizes the operation again. Read and write inbox restrictions apply exactly as they do to REST. Clients should ask the user before consequential or sensitive sends.

Hard stops, not surprise invoices.

• Outbound units are recipient deliveries. One request to five recipients consumes five send units. Estimated MIME bytes are also charged once per recipient copy.
• There are no overages. Recipient, outbound-data, inbound-message, inbound-data, inbox, and API-key limits are hard stops.
• Paid and free periods differ. Paid usage follows the Stripe subscription item's period; Free uses UTC calendar months.
• Plus-addressing belongs to the base inbox. Mail to address+tag@terriblemail.com routes to and consumes quota for address@terriblemail.com.
• The first accepted over-quota inbound message remains visible. Its raw MIME can be recovered while retained, then inbound receipt is suspended until the quota period ends or a larger plan takes effect.
• Downgrades do not delete resources. Excess newer inboxes and keys are disabled; an upgrade can re-enable retained resources.
• Content retention defaults to 30 days. Parsed bodies, headers, attachments, raw pointers, and raw objects expire or are scrubbed. Remaining message metadata defaults to 90 days. Deployments may configure both periods.

Current allowance numbers are published on the pricing page and returned by GET /v1/usage.

Consistent JSON failures.

{
  "error": {
    "code": "invalid_request",
    "message": "from must be an enabled inbox address owned by this account"
  }
}

Do not automatically retry permanent 4xx failures. For transient 429 or 5xx responses, use bounded exponential backoff. Always reuse the same idempotency key when retrying a send whose result is unknown.

Use the spec when code needs the answer.

This page is the complete human-readable guide. The canonical machine-readable contract is the OpenAPI 3.1 document, which includes request schemas, response schemas, parameter bounds, and required scopes.