Tempx API documentation

API keys — one key for MCP, SMTP and Resend capture

Most integrations start with one API key, created in the account at tempx.uk/account#mcp (the “API keys” tab). The key carries tmcp_ prefix, is scoped to exactly one inbox you select, and works across three surfaces at once. Keys are shown exactly once at creation, stored server-side only as a hash, and support read / search / wait / send permissions with an expiry of 1, 7, 30, 90 days or none. Revoking the key — or letting it expire — cuts off MCP, SMTP and Resend capture simultaneously.

Prefer not to hold a key at all? The MCP server also supports browser pairing via OAuth 2.1 (used by Claude and ChatGPT connectors): the user signs in at tempx.uk and approves one inbox — no secret is pasted anywhere.

Read an inbox over REST

The core integration surface: send mail to any address at a Tempx domain, then read the inbox back as JSON. Named inboxes need no account and no key — the name is the address. The API is intended for server-side calls; cross-origin browser calls are refused by design.

GET /api/inbox

List an inbox's messages with retention metadata.

Auth: None for named inboxes (?address=). Private random inboxes require Authorization: Bearer <mailbox token>. · Rate limit: 240 requests / minute

Parameters

• All Tempx mail domains are aliases of one inbox: the local part identifies it, so name@tempx.uk and name@a8bt.win return the same mail.
• Attachments are never inlined — each message's attachment entries carry ready-to-use, HMAC-signed download URLs that expire with the message. Follow them as-is; do not construct them.

# Named inbox: the local part IS the mailbox - no account, no key
curl -s "https://tempx.uk/api/inbox?address=ci-signup-8f3a1" | jq '.messages[0]'

# Private random inbox: omit ?address=, present the signed token instead
curl -s -H "Authorization: Bearer <token>" https://tempx.uk/api/inbox

Response: { address, retentionHours, messages[] } — each message: id, from, fromName, subject, preview (first ~140 chars of the text part), receivedAt, expiresAt, seen, attachments[] (with signed download/inline URLs).

DELETE /api/inbox

Clear the inbox: deletes all messages and their stored attachments immediately.

Auth: Same addressing as GET (?address= or Bearer token). · Rate limit: 60 requests / minute

Parameters

• Deletion is permanent and also allowed on public named inboxes — the same read authority grants delete, which is why private inboxes exist for anything sensitive.

curl -s -X DELETE "https://tempx.uk/api/inbox?address=ci-signup-8f3a1"

Response: { ok: true } on success; 429 with retry-after when rate-limited.

Create inboxes

Named inboxes need zero provisioning — mail to any valid name is accepted on first delivery, which is why test suites should derive unique names per run (ci-signup-<random>@tempx.uk) instead of creating anything. Programmatic anonymous creation exists for browser flows and is deliberately gated.

POST /api/mailbox

Create a private random inbox: unguessable address plus a signed bearer token.

Auth: Cloudflare Turnstile token (browser flows). Not for scripts. · Rate limit: 100 requests / hour

Parameters

• Intended for humans in the browser app. For tests and CI, derive named inboxes instead — nothing to create, nothing to tear down.

curl -s -X POST https://tempx.uk/api/mailbox \
  -H "content-type: application/json" \
  -d '{"turnstileToken":"<from the widget>"}'

Response: { address, token, expiresAt, retentionHours } — store the token; it is the only key to that inbox.

Security model: choose the right inbox

Two inbox kinds share one API, and the difference is who holds the key. Named inboxes are public by design — this is the classic public-inbox model, chosen for zero-friction testing, and it is documented in the app, the FAQ and the Terms. Private random inboxes are the security boundary for everything else.

Never point accounts that matter at a named inbox — password resets and two-factor mail sent to a guessable name can be read by strangers, and the Terms of Service prohibit using Tempx for exactly that. Opening, harvesting or enumerating inboxes belonging to other people is a misuse of the service and may be unlawful. Rate limits blunt bulk scraping: 240 reads/min per source, plus a distinct-address cap — roughly 150 different public inboxes per hour per source — that specifically blunts name-enumeration. Cloudflare bot management sits in front of everything.

Public stats

Aggregate, anonymous usage counters — handy for status pages.

GET /api/stats

Weekly aggregate counters (inboxes created, emails received).

Auth: None. · Rate limit: Cached at the edge

• Aggregate counts only — never per-address data.

curl -s https://tempx.uk/api/stats

Response: { weekly: { inboxesCreated, emailsReceived, … } }

SMTP capture gateway

For the sending side of email testing: point your application's mailer at the gateway and every message is captured into the credential's paired inbox — original recipients preserved, nothing ever relayed to a real person.

Stack-specific setup (Laravel, Rails, Django, Node, n8n) is on the integrations page; the concept is covered at /smtp-testing.

Resend-compatible capture endpoint

Apps already using the Resend SDK can capture their sends without touching the mailer: point the SDK's base URL at Tempx and swap the API key. Requests are parsed in Resend's send-email shape, and the message is captured into the key's inbox — with Resend-shaped success and error bodies, so the SDK parses the response natively. The same adapter contract is how future providers (SendGrid, Mailgun, Postmark) will be added.

POST /resend/emails

Capture one outgoing test message in Resend send-email format.

Auth: Authorization: Bearer tmcp_… (or the SDK's apiKey field set to the key). The send permission is required. · Rate limit: 30 requests / 5 minutes per key

Parameters

• SDK setup (Node): new Resend({ apiKey: process.env.TEMPX_KEY, baseUrl: "https://tempx.uk/resend" }). Everything else in the integration stays unchanged.
• The message is never delivered — from/to are preserved on the captured copy for assertions.
• A missing or wrong-scope key returns Resend-shaped errors: missing_api_key (401) and missing_scope (403).

curl -X POST https://tempx.uk/resend/emails \
  -H "Authorization: Bearer tmcp_YOUR_KEY" \
  -H "content-type: application/json" \
  -d '{"from":"app@yourdomain.test","to":"user@example.net",
       "subject":"Reset your password","html":"<p>Token: 123456</p>"}'

Response: Resend-shaped success: { id } for the captured message; provider-shaped error bodies on failure.

Setup walkthrough with Node and curl examples: the Resend testing guide on the blog, or the SMTP integration page for mailer-based setups.

MCP server for AI agents

Agents get their own inbox through the Model Context Protocol. Preferred auth is browser pairing (OAuth 2.1 with PKCE — the user approves one inbox, no secret is pasted); everywhere else, use an API key (tmcp_) as the Bearer token — the same key that also covers SMTP and Resend capture. Each key is scoped to exactly one inbox, expires on a chosen schedule, and can be revoked in one click.

Endpoint: https://tempx.uk/mcp (streamable HTTP). Claude Code connects with `claude mcp add --transport http tempx https://tempx.uk/mcp`; pairing guides for Claude, ChatGPT and Z.ai are on the Connect Claude page.

Limits and rules that apply to everything above

Automated abuse — inbox harvesting, ban evasion, bulk account creation — is prohibited by the Terms of Service and blocked by rate limits. Report abuse to abuse@tempx.uk.