Inboxes Without an Account

Anonymous inboxes are temporary email addresses you can create and read with no Hooklistener account and no API key. They're made for AI agents and scripts that need to read one signup confirmation, login code or magic link, and for trying Hooklistener before signing up.

Creating an anonymous inbox

curl -X POST https://app.hooklistener.com/api/v1/anon/inboxes \
  -H "Content-Type: application/json" \
  -d '{"ttl_seconds": 3600}'

Response:

{
  "id": "0d6f1c2a-9b8e-4c3d-a1f2-6e5d4c3b2a19",
  "email_address": "[email protected]",
  "expires_at": "2026-10-12T11:00:00Z",
  "email_count": 0,
  "max_emails": 50,
  "emails_url": "https://app.hooklistener.com/api/v1/anon/inboxes/0d6f1c2a-…/emails",
  "wait_url": "https://app.hooklistener.com/api/v1/anon/inboxes/0d6f1c2a-…/emails/wait",
  "viewer_token": "Zk3q…",
  "claim_token": "hkic_…",
  "claim_url": "https://app.hooklistener.com/claim/inbox/0d6f1c2a-…?token=hkic_…"
}

• ttl_seconds is optional: 1 hour by default, from 60 seconds up to 24 hours.
• viewer_token reads the inbox's mail and claim_token lets a signed-in user keep it. Both are shown only once; keep them secret.
• Agents can add "client": "claude-code" (or codex, cursor…) to say which tool created the inbox. It's optional and only used for counting.

Sending email to it

Use email_address like any other address: sign up with it, or have your app email it. Plus-addresses (<address>[email protected]) land in the same inbox.

Waiting for an email

Record the time before you trigger the email, then wait with the viewer token as a bearer token:

API=https://app.hooklistener.com/api/v1
INBOX=$(curl -s -X POST $API/anon/inboxes -H "Content-Type: application/json" -d '{}')
ID=$(echo "$INBOX" | jq -r .id)
ADDRESS=$(echo "$INBOX" | jq -r .email_address)
VIEWER_TOKEN=$(echo "$INBOX" | jq -r .viewer_token)
SINCE=$(date -u +%Y-%m-%dT%H:%M:%SZ)

# ... sign up with $ADDRESS ...

curl -s -G $API/anon/inboxes/$ID/emails/wait \
  -H "Authorization: Bearer $VIEWER_TOKEN" \
  --data-urlencode "since=$SINCE" -d timeout=60 \
  | jq -r '.data.code'

The wait answers 200 with the full email as soon as one arrives after since, or 204 after timeout seconds (up to 60); call it again to keep waiting. Use .data.code for a one-time code and .data.verification_link for a magic or confirmation link.

Reading emails

All reads take the viewer token:

# The inbox: address, expiry and email count
curl $API/anon/inboxes/$ID -H "Authorization: Bearer $VIEWER_TOKEN"

# Emails, newest first
curl $API/anon/inboxes/$ID/emails -H "Authorization: Bearer $VIEWER_TOKEN"

# One email in full
curl $API/anon/inboxes/$ID/emails/$EMAIL_ID -H "Authorization: Bearer $VIEWER_TOKEN"

The email list and the wait take the same since, to, from and subject_contains filters as inboxes in an account, and emails have the same fields: code, verification_link, codes, links, text, bodies, headers and attachments. Each attachment's download_url points at the anonymous API and is read with the same viewer token.

Once the inbox expires, reads answer 410 Gone and mail to the address is refused.

Keeping the inbox

To keep the address and what it received, claim the inbox into an account before it expires. It becomes a regular inbox in the organization, with the same address and emails, and stops expiring.

• In the browser: open claim_url, sign in or create an account, name the inbox and confirm. Agents should hand this link to the user.
• With an API key: an agent that already has the user's key can claim it directly:

curl -X POST https://app.hooklistener.com/api/v1/anon/inboxes/$ID/claim \
  -H "Authorization: Bearer $HOOKLISTENER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"claim_token": "'$CLAIM_TOKEN'", "name": "Signup tests"}'

A claimed inbox counts toward the organization's inbox limit (1 on Free) and keeps its emails for the plan's retention window. After the claim, the viewer token no longer reads it; use the Email Inboxes API, the dashboard or the MCP server.

Unlike anonymous endpoints, an anonymous inbox does not move into the account when the user approves an agent's access request. Claim it with claim_url or the claim API.

Limits

	Anonymous inbox	Inbox in an account
Account or API key	Not needed	Needed
Lifetime	1 hour by default, up to 24 hours	Until you delete it
Emails	Up to 50 over its lifetime	Free: 10 per rolling 24 hours; paid plans: unlimited
Creation	10 per hour and 30 per day from one IP	Your plan's inbox limit
Reading	Viewer token	API key, dashboard, MCP server
Attachments	Yes	Yes
Rename, clear, delete	No	Yes
Forward to webhooks	No	Paid plans
Dashboard	Only after claiming	Yes

Creating more than the per-IP limit answers 429 Too Many Requests with a Retry-After header. Mail beyond 50 emails is refused; create a new inbox or claim this one.

Use cases

• AI agents testing a signup or login email for a user who has no Hooklistener account yet
• Quick checks: get an address in one request and see what your app sends
• Small CI suites that create an inbox per run without storing an API key
• Trying Hooklistener before signing up, then claiming the inbox to keep it

See the Anonymous Inboxes API for every route and error.