TestTau docs

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

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

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

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
Schema size	~50 KiB
Errors returned per request	first 20