REST & Streaming API Reference

Generate Disposable Address

Instantly provisions an isolated disposable email address routed to your namespace. Defaults to a random 6-character tag if none is supplied.

{
  "email": "demo.qa-trial@inbox.testmail.app",
  "tag": "qa-trial",
  "namespace": "demo"
}

Query & Search Messages

Retrieves inbox messages matching tag, sender, subject, and attachment criteria. Includes livequery mode for synchronous long-polling in CI/CD pipelines. A private mailbox needs its recovery key in the X-Mailbox-Key header — a key in the query string would end up in every access log.

{
  "result": "success",
  "count": 1,
  "limit": 10,
  "offset": 0,
  "has_more": false,
  "emails": [
    {
      "id": "msg-8f92a10c",
      "from": "auth@example.com",
      "to": "demo.qa-trial@inbox.testmail.app",
      "subject": "Security Code: 839210",
      "tag": "qa-trial",
      "timestamp": 1788936000000,
      "has_attachments": false,
      "has_html": true,
      "text_preview": "Your one-time authentication code is 839210..."
    }
  ]
}

Fetch Email Details by ID

Retrieves the complete payload of an email, including rendered HTML body, plain text content, raw headers, spam score, and metadata. An email ID is not a credential: when the message belongs to a private mailbox, its recovery key is required.

{
  "id": "msg-8f92a10c",
  "from_addr": "auth@example.com",
  "to_addr": "demo.qa-trial@inbox.testmail.app",
  "subject": "Security Code: 839210",
  "timestamp": 1788936000000,
  "html": "<p>Your security code is <b>839210</b></p>",
  "text": "Your security code is 839210",
  "spam_score": 0.1,
  "attachments": [],
  "links": []
}

Extract Verification Links & Tokens

Deep-parses HTML anchors and raw plain text to extract all clickable URLs, activation tokens, and OTP codes automatically.

{
  "email_id": "msg-8f92a10c",
  "count": 1,
  "links": [
    {
      "url": "https://myapp.com/verify?token=abc88921",
      "display_text": "Verify Email Address",
      "context": "Please verify your account by clicking the link below",
      "is_verification": true
    }
  ]
}

Server-Sent Events (SSE) Live Stream

Subscribes to real-time email delivery events over a persistent HTTP connection with automatic keep-alive heartbeats every 15 seconds.

event: connected
data: {"message":"SSE connected","timestamp":1788936000000}

event: new_email
data: {"id":"msg-8f92a10c","subject":"Security Code: 839210","tag":"qa-trial","from":"auth@example.com"}

Download Raw RFC 822 (.eml)

Streams the complete untouched RFC 822 MIME message container suitable for archival or offline inspection.

[Binary RFC 822 Stream: msg-8f92a10c.eml]

Stream Attachment File

Directly proxies binary attachments associated with a message with correct Content-Type and Content-Disposition headers.

[Binary Content-Disposition: attachment; filename="invoice.pdf"]

List Active Tags & Email Counts

Returns all recent active tags across the namespace along with message counts, ordered by inbound volume.

{
  "tags": [
    { "tag": "qa-trial", "count": 24 },
    { "tag": "auth-check", "count": 12 },
    { "tag": "ci-runner-8", "count": 5 }
  ]
}

API Telemetry & Consumption

Reports live aggregate platform metrics including total request counts, average latency, active SSE streams, and uptime. The public response is an allowlist of aggregates; the request feed, consumer domains and per-endpoint counters need the admin key. Paths are stored as route templates, so a message ID never leaks through telemetry.

{
  "uptime_seconds": 86400,
  "total_requests": 28490,
  "avg_latency_ms": 1.4,
  "active_sse_connections": 14,
  "sources": {
    "official_web": 19200,
    "external_api": 9290
  }
}

Health Check & Upstream Probe

Returns the deployment state, credential configuration, and the cached upstream reachability flag. The upstream mail API is never called from this endpoint, so an anonymous health check cannot spend upstream quota. /health/live and /health/ready are available for hosting platforms.

{
  "status": "healthy",
  "service": "testmail-dashboard-api",
  "api_key_configured": true,
  "namespace": "demo",
  "demo_mode": false,
  "upstream_reachable": true
}