# Testmail — Full Technical Reference & Developer Guide

> Website: https://tempmail.codaipro.com
> API Base: https://api-testmail.codaipro.com
> Blog Feed: https://tempmail.codaipro.com/rss.xml
> Author: https://tempmail.codaipro.com/authors/pankaj-kumawat

---

## 1. System Overview & Architecture

Testmail is a high-density companion service and developer gateway built on top of `testmail.app`. It provisions on-demand temporary disposable mailboxes under the domain `inbox.testmail.app` and streams incoming messages in real time over Server-Sent Events (SSE).

### Key Architectural Tenets:
1. **Public Ephemeral Tier**: By default, emails displayed to web clients auto-purge after 10 minutes (`retention_minutes=10`) to ensure sensitive one-time passwords (OTPs) and activation tokens do not linger publicly.
2. **Admin Historical Archive**: When accessed via authorized admin endpoints (`retention_minutes=0`), historical retention filtering is disabled, allowing administrative review of the complete unpruned inbox.
3. **Open Developer Gateway**: The API is 100% free and open with unconstrained Cross-Origin Resource Sharing (`CORS: *`). Developers can call endpoints directly from frontend client apps, curl commands, or CI/CD test runners without authenticating or generating personal API keys.
4. **Client Attribution**: In-memory telemetry tracks consuming domains (`Origin` / `Referer`) and client tools (`User-Agent`) to distinguish official web traffic from automated developer scripts.

---

## 2. API Endpoints Reference

### Base URL
Production: `https://api-testmail.codaipro.com`
Local Development: `http://localhost:8000`

---

### Endpoint: Generate Disposable Address
- **Method**: `POST`
- **Path**: `/api/emails/generate`
- **Query Parameters**:
  - `tag` (string, optional): Custom tag for the mailbox (e.g. `signup`, `trial-01`). If omitted, a random 6-character alphanumeric tag is automatically created.
- **Request Body**: None
- **Response**: `201 Created`
```json
{
  "email": "demo.signup-01@inbox.testmail.app",
  "tag": "signup-01",
  "namespace": "demo"
}
```
- **Example cURL**:
```bash
curl -X POST "https://api-testmail.codaipro.com/api/emails/generate?tag=auth-check" \
  -H "Content-Type: application/json"
```

---

### Endpoint: List / Search Emails
- **Method**: `GET`
- **Path**: `/api/emails/`
- **Query Parameters**:
  - `tag` (string, optional): Filter by exact tag match.
  - `tag_prefix` (string, optional): Filter by tag prefix.
  - `from_contains` (string, optional): Case-insensitive substring match on sender address.
  - `subject_contains` (string, optional): Case-insensitive substring match on email subject.
  - `has_attachments` (boolean, optional): Set `true` for emails with attachments, `false` otherwise.
  - `limit` (integer, default `20`, max `100`): Maximum number of emails to retrieve.
  - `offset` (integer, default `0`): Pagination offset.
  - `timestamp_from` (integer, optional): Unix epoch timestamp in milliseconds.
  - `timestamp_to` (integer, optional): Unix epoch timestamp in milliseconds.
  - `retention_minutes` (integer, optional, default `10`): Retention cutoff in minutes. Set `0` for unexpired admin archive.
  - `livequery` (boolean, default `false`): Wait up to 60 seconds for a new email to arrive if none match immediately.
  - `pretty` (boolean, default `false`): Return formatted JSON.
- **Response**: `200 OK`
```json
{
  "result": "success",
  "message": null,
  "count": 1,
  "limit": 20,
  "offset": 0,
  "has_more": false,
  "next_offset": null,
  "prev_offset": null,
  "emails": [
    {
      "id": "msg-8f92a10c",
      "from": "support@example.com",
      "from_parsed": [{"address": "support@example.com", "name": "Example Support"}],
      "to": "demo.auth-check@inbox.testmail.app",
      "subject": "Confirm your account",
      "tag": "auth-check",
      "timestamp": 1788936000000,
      "has_attachments": false,
      "has_html": true,
      "text_preview": "Welcome! Please verify your email by clicking the link inside..."
    }
  ]
}
```

---

### Endpoint: Real-Time Server-Sent Events (SSE) Stream
- **Method**: `GET`
- **Path**: `/api/emails/stream`
- **Query Parameters**:
  - `client` (string, optional): Client identifier (e.g. `?client=official-web`).
- **Headers**:
  - `Accept: text/event-stream`
- **Events Emitted**:
  - `event: connected` — Emitted immediately upon connection.
    `data: {"message":"SSE connected","timestamp":1788936000000}`
  - `event: heartbeat` — Emitted every 30 seconds to keep HTTP connections alive through proxies and cloud firewalls.
    `data: {"timestamp":1788936030000}`
  - `event: new_email` — Broadcasts freshly received emails to all active subscribers.
    `data: { ...EmailSummaryModel JSON... }`
- **Concurrency**: Capped at 10 concurrent subscribers. Exceeding returns `429 Rate Limited`.

---

### Endpoint: Get Email Detail by ID
- **Method**: `GET`
- **Path**: `/api/emails/{id}`
- **Path Parameters**:
  - `id` (string, required): The unique identifier of the email.
- **Response**: `200 OK`
```json
{
  "id": "msg-8f92a10c",
  "from_addr": "support@example.com",
  "from_parsed": [{"address": "support@example.com", "name": "Example Support"}],
  "to_addr": "demo.auth-check@inbox.testmail.app",
  "subject": "Confirm your account",
  "timestamp": 1788936000000,
  "tag": "auth-check",
  "html": "<html><body><p>Click <a href=\"https://example.com/verify?token=xyz\">here</a></p></body></html>",
  "text": "Click here: https://example.com/verify?token=xyz",
  "headers": [
    {"key": "date", "line": "Date: Tue, 08 Sep 2026 12:00:00 GMT"},
    {"key": "message-id", "line": "Message-ID: <unique-id@example.com>"}
  ],
  "spam_score": 0.2,
  "spam_report": "0.2 ALL_TRUSTED Passed through trusted relays",
  "attachments": [],
  "links": [
    {
      "url": "https://example.com/verify?token=xyz",
      "display_text": "here",
      "context": "Click here",
      "is_verification": true
    }
  ]
}
```

---

### Endpoint: Extract Links & Verification Tokens
- **Method**: `GET`
- **Path**: `/api/emails/{id}/links`
- **Path Parameters**:
  - `id` (string, required): Email ID.
- **Response**: `200 OK`
```json
{
  "email_id": "msg-8f92a10c",
  "count": 1,
  "links": [
    {
      "url": "https://example.com/verify?token=xyz",
      "display_text": "here",
      "context": "Click here to confirm",
      "is_verification": true
    }
  ]
}
```

---

### Endpoint: Download RFC 822 Raw Email (.eml)
- **Method**: `GET`
- **Path**: `/api/emails/{id}/download`
- **Response**: `200 OK` with `Content-Type: message/rfc822` and header `Content-Disposition: attachment; filename="{id}.eml"`.

---

### Endpoint: Proxy Attachment Download
- **Method**: `GET`
- **Path**: `/api/emails/attachments/{id}/{filename}`
- **Response**: Binary stream of the specified attachment with original MIME type and content disposition headers.

---

### Endpoint: Tags Aggregation
- **Method**: `GET`
- **Path**: `/api/tags` (or alias `/api/emails/tags`)
- **Response**: `200 OK`
```json
{
  "tags": [
    {"tag": "auth-check", "count": 12},
    {"tag": "qa-trial", "count": 7}
  ]
}
```

---

### Endpoint: Real-Time Telemetry & Domain Consumption
- **Method**: `GET`
- **Path**: `/api/metrics`
- **Response**: `200 OK`
```json
{
  "uptime_seconds": 3600,
  "total_requests": 1420,
  "avg_latency_ms": 1.4,
  "active_sse_connections": 2,
  "sources": {
    "official_web": 980,
    "external_api": 440,
    "localhost_dev": 0
  },
  "status_breakdown": {
    "2xx": 1412,
    "4xx": 8
  },
  "top_domains": [
    {"domain": "tempmail.codaipro.com", "count": 980},
    {"domain": "Direct / Scripts", "count": 390},
    {"domain": "partner-app.com", "count": 50}
  ],
  "top_clients": [
    {"client": "Official Web App", "count": 980},
    {"client": "cURL", "count": 210},
    {"client": "Python / Scripts", "count": 180}
  ],
  "recent_requests": [ ... ]
}
```

---

### Endpoint: System Health & Uptime Ping
- `GET /health`: Returns JSON reporting service name, upstream reachability, and credential status.
- `GET /ping`: Returns `{"status":"pong","timestamp":1788936000000}`. Used by keep-alive pingers on hosts that idle-shutdown.

---

## 3. Standard Error Envelope

All API errors return consistent JSON envelopes:
```json
{
  "result": "fail",
  "error": {
    "type": "not_found | validation_error | rate_limited | upstream_error | internal_error",
    "message": "Human-readable description of error",
    "detail": "Technical diagnostics (only present when DEBUG=true)"
  }
}
```

---

## 4. Automation QA Recipes

### Python Integration Test Sample
```python
import requests
import time

BASE_URL = "https://api-testmail.codaipro.com"

# 1. Generate clean inbox
resp = requests.post(f"{BASE_URL}/api/emails/generate", params={"tag": "py-test"})
email_addr = resp.json()["email"]
print(f"Generated test address: {email_addr}")

# 2. Trigger your application's signup flow sending mail to email_addr
# (Your app logic here)

# 3. Poll for incoming confirmation email with livequery
emails_resp = requests.get(
    f"{BASE_URL}/api/emails/",
    params={"tag": "py-test", "livequery": "true", "limit": 1}
)
emails = emails_resp.json()["emails"]
assert len(emails) > 0, "No email received"

# 4. Extract verification URL
msg_id = emails[0]["id"]
links_resp = requests.get(f"{BASE_URL}/api/emails/{msg_id}/links")
verif_links = [l["url"] for l in links_resp.json()["links"] if l["is_verification"]]
print(f"Found verification link: {verif_links[0]}")
```