TestTau#

TestTau gives agents disposable mail and webhook endpoints for tests:

• Public mail: send to <inbox>@mail.testtau.com, inspect at https://mail.testtau.com/i/<inbox>.
• Public hooks: send to https://hook.testtau.com/<hookId>, inspect at https://hook.testtau.com/_/<hookId>.
• Private mail and hooks: use the user's TestTau Account page to create an API key, then send reads/config requests with Authorization: Bearer <key>.

Use a unique name per task, for example agent-<purpose>-<short-random>. Valid names start with a lowercase letter or number and may contain lowercase letters, numbers, ., _, +, or -.

Public Disposable Mail#

Use public mail when the inbox can be readable by anyone who knows the name.

1. Choose an inbox name, such as agent-login-7k3p.
2. Tell the system under test to email agent-login-7k3p@mail.testtau.com.
3. Wait for the message:

bash

curl -fsS "https://mail.testtau.com/i/agent-login-7k3p/api/wait?timeout=15000&subject=Verify"

1. Read parsed JSON:

bash

curl -fsS "https://mail.testtau.com/i/agent-login-7k3p/api/message/<messageId>/json"

Important fields include fromAddr, toAddr, subject, textBody, htmlBody, preview, attachments, and links.raw.

Private Mail#

Use private mail when the test email must not be visible in a public inbox.

1. Ask the user for their TestTau private inbox name and API key, or direct them to https://testtau.com/account.
2. Send mail to <privateInbox>@mail.testtau.com.
3. Read with a bearer token:

bash

curl -fsS \
  -H "Authorization: Bearer $TESTTAU_MAIL_KEY" \
  "https://mail.testtau.com/private/i/<privateInbox>/api/wait?timeout=15000&subject=Verify"

Never put private keys in URLs. Use Authorization: Bearer.

Public Webhook Capture#

Use public hooks when captured requests can be visible to anyone with the hook id.

bash

HOOK_ID="agent-webhook-7k3p"
curl -fsS -X POST "https://hook.testtau.com/$HOOK_ID" \
  -H "content-type: application/json" \
  -d '{"event":"agent.test","ok":true}'

curl -fsS "https://hook.testtau.com/_/$HOOK_ID/api/list"

Open https://hook.testtau.com/_/<hookId> for the live inspector.

Private Hooks#

Use private hooks when inspection, replay, config, wipe, and assertions must require an API key.

bash

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

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

Schema Assertions#

For webhook contract tests, configure a JSON Schema and use the assert endpoint as a CI gate.

bash

START="$(date +%s%3N)"

curl -fsS -X PUT "https://hook.testtau.com/_/<hookId>/api/config" \
  -H "content-type: application/json" \
  -d '{"schema":"{\"type\":\"object\",\"required\":[\"event\"]}","schemaFailMode":"capture"}'

# Trigger the system under test here.

curl -fsS "https://hook.testtau.com/_/<hookId>/api/assert?since=$START&min_count=1"

For private hooks, add -H "Authorization: Bearer $TESTTAU_HOOK_KEY" to config, list, request, replay, wipe, and assert calls.

Limits And Safety#

• Public captures are disposable and should not receive production secrets, PII, or credentials.
• Public mail and hooks are name-based; anyone with the name can inspect them.
• Signed-in private tools require bearer tokens for reads and management.
• Current free private limits: 100 private mail messages per account period and 1,000 private hook captures per account period.
• Mail retention is 48 hours, public inbox storage is 100 messages, mail attachments are capped at 5 MB, and hook request bodies are capped at 1 MiB.

When Done#

Return the exact inbox or hook id used, the inspect URL, and the message/request id if one was captured. If a wait timed out, report that explicitly and include the URL the user can open manually.