TestTau docs

One place for public disposable mail, signed-in private sender mail, webhook capture, schema assertions, and automation endpoints.

Public vs private

Public mail	Send to `<name>@mail.testtau.com`. Anyone who knows the inbox name can open it. Use this for anonymous QA, smoke tests, and throwaway signups.
Private mail	Sign in, register one sender address, and create an API key. Mail from that sender is stored separately and requires `Authorization: Bearer <key>` to read.
Public hooks	Send requests to `https://hook.testtau.com/<hookId>`. Anyone who knows the hook id can inspect captures.
Private hooks	Sign in and create one private hook. Sending to the capture URL is open, but inspecting, replaying, configuring, wiping, and API reads require the hook key.

Mail

Send mail to any address at mail.testtau.com; read it in the browser or wait for it from CI.

Quick start

checkout-qa@mail.testtau.com
https://mail.testtau.com/i/checkout-qa

Wait from automation

The wait endpoint long-polls for up to 15 seconds and returns the newest matching message.

curl "https://mail.testtau.com/i/checkout-qa/api/wait?timeout=15000&subject=Verify&text=884201"

Supported filters are from, to, subject, preview, text, hasAttachments, and after (epoch milliseconds).

Signed-in private sender mail

Free accounts can register one sender email and generate a mail API key. When TestTau receives mail from that sender, it stores the message in a private inbox instead of the anonymous public inbox.

Public inbox	Anyone with the inbox URL can read and delete messages. Best for random QA and smoke tests.
Private sender inbox	Mail from your registered sender is stored separately and requires `Authorization: Bearer <key>`.

# Sender: you@example.com
login-smoke@mail.testtau.com

# Browser viewer
https://mail.testtau.com/private/i/login-smoke

# Paste the key in the browser. TestTau stores it in tab session storage
# and sends it as an Authorization header, not in the URL.

# API
curl -H "Authorization: Bearer $TESTTAU_KEY" \
  "https://mail.testtau.com/private/i/login-smoke/api/list"

Mail API

curl "https://mail.testtau.com/i/checkout-qa/api/quota"
curl "https://mail.testtau.com/i/checkout-qa/api/list"
curl "https://mail.testtau.com/i/checkout-qa/api/message/<messageId>"
curl "https://mail.testtau.com/i/checkout-qa/api/message/<messageId>/json"
curl -X DELETE "https://mail.testtau.com/i/checkout-qa/api/message/<messageId>"
curl -X DELETE "https://mail.testtau.com/i/checkout-qa/api/all"

The message JSON endpoint returns the parsed email content: sender, recipient, subject, preview, plain text, HTML, attachment metadata, and download links for the raw .eml plus each attachment.

{
  "id": "01...",
  "fromAddr": "sender@example.com",
  "toAddr": "checkout-qa@mail.testtau.com",
  "subject": "Verify your email",
  "textBody": "Your code is 884201",
  "htmlBody": "<p>Your code is <strong>884201</strong></p>",
  "attachments": [
    {
      "id": "01...",
      "filename": "receipt.pdf",
      "contentType": "application/pdf",
      "sizeBytes": 12000,
      "downloadUrl": "/i/checkout-qa/api/message/01.../attachment/01..."
    }
  ],
  "links": {
    "raw": "/i/checkout-qa/api/message/01.../raw"
  }
}

Mail limits

Message size	25 MiB
Attachment size	5 MiB
Attachments per message	10
Stored messages per inbox	100
Signed-in private senders	1 sender email per account
HTTP API rate limit	120 requests/minute per IP
Inbound sender limit	100 messages/hour per sender address
Inbound domain limit	500 messages/hour per sender domain
Retention	48 h

Hooks

Send any HTTP request to https://hook.testtau.com/<hookId> and inspect it live at https://hook.testtau.com/_/<hookId>.

Quick start

curl -X POST https://hook.testtau.com/my-hook-id \
  -H 'content-type: application/json' \
  -d '{"event":"hello"}'

Signed-in private hooks

Free accounts can create one private hook. External services can send to the hook URL, but reading captures, changing config, replaying, wiping, and assertion APIs require Authorization: Bearer <key>.

# Send a capture
curl -X POST https://hook.testtau.com/private/<hookId> \
  -H 'content-type: application/json' \
  -d '{"event":"private"}'

# Browser inspector
https://hook.testtau.com/private/_/<hookId>

# Paste the key in the browser. TestTau stores it in tab session storage
# and sends it as an Authorization header, not in the URL.

# Read captures
curl -H "Authorization: Bearer $TESTTAU_HOOK_KEY" \
  "https://hook.testtau.com/private/_/<hookId>/api/list"

What is captured

Method, full path, query string, and headers.
Client IP and country from Cloudflare.
Full request body up to 1 MiB.
Schema assertion status when configured.

Config, replay, and assertions

Open the inspector to change the response status/body, replay a captured request against another URL, or attach a JSON Schema. Schema failures can either be recorded in the inspector or rejected immediately with 422.

{
  "type": "object",
  "required": ["event", "user_id"],
  "properties": {
    "event": { "type": "string" },
    "user_id": { "type": "string" }
  },
  "additionalProperties": false
}

CI gating

START=$(date +%s%3N)
curl -fsS "https://hook.testtau.com/_/<hookId>/api/assert?since=$START&min_count=1"

The assert endpoint returns 200 when all matching captures passed and 422 when captures are missing or failed validation.

Hook limits

Body size	1 MiB
Retention	48 h
Capture rate limit	120 requests/minute per IP
Hook id rate limit	300 requests/minute per hook id
Signed-in private hooks	1 private hook per account
Schema size	~50 KiB
Errors returned per request	first 20