Mail Forwarding API Reference

https://mail.thc.org/docs
Admin
This document outlines the wire contract for the Mail Forwarding API, detailing its routes, methods,...
Tokens:44,669
Snippets:333
Trust Score:9.7
Update:3 months ago
Show doc for...
Tokens:
Raw
### Start Alias Creation (Query Mode A)

Source: https://mail.thc.org/docs

This is the query string format for starting an alias creation request in normal domain mode. The 'domain' parameter is optional.

```plain text
name=research
domain=thc.org
to=alice@example.org
```

--------------------------------

### Start Alias Creation (Query Mode B)

Source: https://mail.thc.org/docs

This is the query string format for starting an alias creation request in full address mode. 'name' and 'domain' are forbidden in this mode.

```plain text
address=research@thc.org
to=alice@example.org
```

--------------------------------

### Subscribe Handle

Source: https://mail.thc.org/docs

Starts handle creation. Requires the handle and destination email in the query.

```APIDOC
## GET /api/handle/subscribe

### Description
Starts handle creation.

### Method
GET

### Endpoint
/api/handle/subscribe

### Parameters
#### Query Parameters
- **handle** (string) - Required - The handle to create.
- **to** (string) - Required - The destination email address.

### Rules
- `handle` must be a valid local part.
- `to` must be a valid mailbox.
- `to` cannot already be an alias.
- `to` cannot use an exact active managed domain.
- The handle cannot already exist.
- The handle cannot collide with an active alias local part.

### Response
#### Success Response (200)
- **ok** (boolean) - Indicates if the operation was successful.
- **action** (string) - The action performed, e.g., "handle_subscribe".
- **handle** (string) - The created handle.
- **to** (string) - The destination email address.
- **confirmation** (object) - Confirmation details.
  - **sent** (boolean) - Indicates if the confirmation email was sent.
  - **ttl_minutes** (integer) - The time-to-live for the confirmation in minutes.

#### Response Example (Success)
```json
{
  "ok": true,
  "action": "handle_subscribe",
  "handle": "alice",
  "to": "alice@example.org",
  "confirmation": {
    "sent": true,
    "ttl_minutes": 10
  }
}
```

#### Response Example (Failures)
```json
{
  "error": "invalid_params",
  "field": "handle"
}
```

```json
{
  "error": "invalid_params",
  "field": "to"
}
```

```json
{
  "ok": false,
  "error": "alias_taken"
}
```
```

--------------------------------

### Subscribe Handle

Source: https://mail.thc.org/docs

Starts the process of creating a handle. Requires the handle name and the destination email address. The destination cannot already be an alias.

```bash
handle=alice
to=alice@example.org
```

--------------------------------

### Confirm Handle Intent API Aliases

Source: https://mail.thc.org/docs

Alternative GET and POST endpoints for confirming handle intents, all routing to the same confirmation service.

```bash
GET  /api/handle/unsubscribe/confirm
POST /api/handle/unsubscribe/confirm
GET  /api/handle/domain/disable/confirm
GET  /api/handle/domain/enable/confirm
```

--------------------------------

### Start Alias Creation with Confirmation

Source: https://mail.thc.org/docs

Initiates the alias creation process by sending a 6-digit confirmation token to the destination email. The alias is not created until this token is confirmed.

```sh
BASE='https://mail.thc.org/api'

curl -sS --get "$BASE/forward/subscribe" \
  --data-urlencode 'name=research' \
  --data-urlencode 'domain=thc.org' \
  --data-urlencode 'to=alice@example.org'
```

--------------------------------

### Common Admin Domain Errors

Source: https://mail.thc.org/docs

Examples of common error responses when managing domains.

```json
{ "error": "domain_not_found", "id": 10 }
```

```json
{ "error": "domain_taken", "name": "example.com" }
```

```json
{ "error": "invalid_params", "reason": "empty_patch" }
```

--------------------------------

### Acceptable Alias Names and Handles

Source: https://mail.thc.org/docs

Examples of valid local parts for alias names and handles, adhering to specific formatting rules.

```plaintext
research
root.ops
build-01
a_b
```

--------------------------------

### DNS Status Check Response Example

Source: https://mail.thc.org/docs

This is an example of the JSON response from the DNS status check API. It indicates the status of UI and email approval lanes, with ACTIVE meaning the lane passed and PENDING meaning DNS is not yet observed as complete. The 'missing' field details what the checker is still looking for.

```json
{
  "target": "example.com",
  "normalized_target": "example.com",
  "summary": {
    "has_ui": true,
    "has_email": true,
    "overall_status": "PENDING"
  },
  "ui": {
    "status": "ACTIVE",
    "missing": []
  },
  "email": {
    "status": "PENDING",
    "missing": [
      {
        "key": "MX",
        "expected": {
          "host": "mail.example.net",
          "priority": 10
        },
        "found": []
      }
    ]
  }
}
```

--------------------------------

### Admin API Token Creation Response

Source: https://mail.thc.org/docs

Example response upon successfully creating an API token. The plaintext token is included only once in this response.

```json
{
  "ok": true,
  "created": true,
  "token": "64_chars_here",
  "token_type": "api_key",
  "item": {
    "id": 50,
    "owner_email": "alice@example.org",
    "status": "active",
    "created_at": "2026-06-19T12:00:00.000Z",
    "expires_at": "2026-07-19T12:00:00.000Z",
    "revoked_at": null,
    "revoked_reason": null,
    "created_ip": "203.0.113.10",
    "user_agent": "curl/8",
    "last_used_at": null,
    "automatic_renew": 0,
    "active": true
  }
}
```

--------------------------------

### New Admin Domain Default Values

Source: https://mail.thc.org/docs

New admin-created domains start with these default values for DNS approval gates.

```text
active_mx = 0
active_ui = 0
```

--------------------------------

### Create Admin Domain using cURL

Source: https://mail.thc.org/docs

Example of creating a new domain using a cURL command. Ensure to replace placeholders like `$COOKIE_JAR`, `$CSRF`, and `$BASE` with actual values.

```sh
curl -sS -c "$COOKIE_JAR" -b "$COOKIE_JAR" \
  -X POST "$BASE/admin/domains" \
  -H "X-CSRF-Token: $CSRF" \
  -H 'Content-Type: application/json' \
  -d '{"name":"example.com","active":1,"visible":1}'
```

--------------------------------

### Initiate Alias Removal with Confirmation

Source: https://mail.thc.org/docs

Starts the alias removal process by sending a confirmation token to the current 'goto' owner of the alias. The alias is not removed until this token is confirmed.

```sh
BASE='https://mail.thc.org/api'

curl -sS --get "$BASE/forward/unsubscribe" \
  --data-urlencode 'alias=research@thc.org'
```

--------------------------------

### Successful Domain Ban Creation Response

Source: https://mail.thc.org/docs

Example response after successfully creating a domain ban. It indicates the ban was created and shows the number of aliases that were also disabled.

```json
{
  "ok": true,
  "created": true,
  "item": {
    "id": 30,
    "ban_type": "domain",
    "ban_value": "bad.example",
    "reason": "abuse",
    "created_at": "2026-06-19T12:00:00.000Z",
    "expires_at": null,
    "revoked_at": null,
    "revoked_reason": null,
    "active": true
  },
  "disabled_aliases": 4,
  "message": "Ban created. Also, 4 matching aliases were disabled."
}
```

--------------------------------

### Example Public Mail Domain API Endpoint

Source: https://mail.thc.org/docs

This is an example of a public mail domain API endpoint. It is typically accessed via DNS and proxying.

```plaintext
https://your-domain/api
```

--------------------------------

### Successful Alias Creation Confirmation Response

Source: https://mail.thc.org/docs

Example response indicating successful alias creation after confirmation. 'created: true' signifies the alias was successfully registered.

```json
{
  "ok": true,
  "confirmed": true,
  "intent": "subscribe",
  "created": true,
  "address": "research@thc.org",
  "goto": "alice@example.org"
}
```

--------------------------------

### Accepted Domain Targets

Source: https://mail.thc.org/docs

Examples of valid domain names accepted as targets, including normalization of case and trailing dots.

```plaintext
example.com
mail.example.com
Example.COM.
```

--------------------------------

### Get Activity Log

Source: https://mail.thc.org/docs

Retrieves a log of recent activities, including alias mutations and subscription confirmations.

```APIDOC
## GET /api/activity

### Description
Retrieves a log of recent activities, blending API-key alias mutations with confirmed email-token mutations for the owner email. Supports pagination.

### Method
GET

### Endpoint
/api/activity

### Parameters
#### Query Parameters
- **limit** (integer) - Optional - The maximum number of items to return (default: 50).
- **offset** (integer) - Optional - The number of items to skip (default: 0).

### Response
#### Success Response (200)
- **items** (array) - A list of activity objects.
  - **type** (string) - The type of activity (e.g., "alias_create", "confirm_subscribe").
  - **occurred_at** (string) - The timestamp when the activity occurred.
  - **route** (string) - The API route associated with the activity.
  - **intent** (string|null) - The intent of the activity, if applicable.
  - **alias** (string) - The email alias involved in the activity.
- **pagination** (object) - Pagination details.
  - **limit** (integer) - The limit used for this request.
  - **offset** (integer) - The offset used for this request.

#### Response Example
```json
{
  "items": [
    {
      "type": "alias_create",
      "occurred_at": "2026-06-19T12:00:00.000Z",
      "route": "/api/alias/create",
      "intent": null,
      "alias": "research@thc.org"
    },
    {
      "type": "confirm_subscribe",
      "occurred_at": "2026-06-18T12:00:00.000Z",
      "route": "/api/forward/confirm",
      "intent": "subscribe",
      "alias": "old@thc.org"
    }
  ],
  "pagination": {
    "limit": 50,
    "offset": 0
  }
}
```
```

--------------------------------

### Public Domains Response

Source: https://mail.thc.org/docs

Example JSON response when listing public domains. It contains an array of domain strings.

```json
["thc.org"]
```

--------------------------------

### GET /api/credentials/confirm

Source: https://mail.thc.org/docs

Preview only. This endpoint allows previewing the result of a pending API credentials action without executing it.

```APIDOC
## GET /api/credentials/confirm

### Description
Preview only. It does not create, list, or destroy keys. This endpoint allows previewing the result of a pending API credentials action without executing it.

### Method
GET

### Endpoint
/api/credentials/confirm

### Parameters
#### Query Parameters
- **token** (string) - Required - The confirmation token received via email.

### Response
#### Success Response (200)
- **ok** (boolean) - Indicates if the request was successful.
- **pending** (boolean) - Indicates if the action is pending confirmation.
- **mutation_required** (boolean) - Indicates if a mutation (execution) is required.
- **action** (string) - The type of action pending.
- **email** (string) - The email address associated with the action.
- **days** (integer) - The validity period in days (for create action).
- **automatic_renew** (boolean) - Indicates if automatic renewal is enabled (for create action).
- **confirm_via** (object) - Details on how to confirm the action.
  - **method** (string) - The HTTP method for confirmation.
  - **path** (string) - The endpoint path for confirmation.

#### Response Example (Create Action Preview)
```json
{
  "ok": true,
  "pending": true,
  "mutation_required": true,
  "action": "create",
  "email": "alice@example.org",
  "days": 30,
  "automatic_renew": false,
  "confirm_via": {
    "method": "POST",
    "path": "/api/credentials/confirm"
  }
}
```
```

--------------------------------

### Alias Creation Confirmation Response

Source: https://mail.thc.org/docs

Example response after initiating alias creation. 'sent: true' indicates the confirmation email was sent. 'sent: false' with 'reason: "cooldown"' means a pending request exists.

```json
{
  "ok": true,
  "action": "subscribe",
  "alias_candidate": "research@thc.org",
  "to": "alice@example.org",
  "confirmation": {
    "sent": true,
    "ttl_minutes": 10
  }
}
```

--------------------------------

### Unacceptable Alias Names and Handles

Source: https://mail.thc.org/docs

Examples of invalid local parts for alias names and handles that violate the specified formatting rules.

```plaintext
.research
research.
two..dots
bad space
bad/slash
```

--------------------------------

### Create Domain Ban using cURL

Source: https://mail.thc.org/docs

Example of creating a domain ban using cURL. The `disable_matching_aliases` flag is used here, which is not supported for IP bans.

```sh
curl -sS -c "$COOKIE_JAR" -b "$COOKIE_JAR" \
  -X POST "$BASE/admin/bans" \
  -H "X-CSRF-Token: $CSRF" \
  -H 'Content-Type: application/json' \
  -d '{"ban_type":"domain","ban_value":"bad.example","reason":"abuse","disable_matching_aliases":true}'
```

--------------------------------

### Error Response for Unsupported Ban Parameter

Source: https://mail.thc.org/docs

Example error response when attempting to use a parameter that is not supported for a specific ban type, such as `disable_matching_aliases` for IP bans.

```json
{
  "error": "invalid_params",
  "field": "disable_matching_aliases",
  "reason": "not_supported_for_ip_bans"
}
```

--------------------------------

### Request an API Key

Source: https://mail.thc.org/docs

Use this endpoint to initiate the API key creation process. An email confirmation will be sent, and the key is displayed only once upon successful POST confirmation.

```bash
BASE='https://mail.thc.org/api'

curl -sS -X POST "$BASE/credentials/create" \
  -H 'Content-Type: application/json' \
  -d '{"email":"alice@example.org","days":30,"automatic_renew":false}'
```

--------------------------------

### Get Session

Source: https://mail.thc.org/docs

Retrieves the current user's session information. Requires a valid access cookie.

```APIDOC
## GET /api/auth/session

### Description
Retrieves the current authenticated user's session details. This endpoint requires a valid `__Host-access` cookie.

### Method
GET

### Endpoint
/api/auth/session

### Response
#### Success Response (200)
- **ok** (boolean) - Indicates success.
- **authenticated** (boolean) - True if the user is authenticated.
- **user** (object) - Basic user information.
- **session** (object) - Session details including expiry times.

#### Response Example
```json
{
  "ok": true,
  "authenticated": true,
  "user": {
    "id": 7,
    "username": "admin",
    "email": "admin@example.org",
    "is_admin": true
  },
  "session": {
    "session_family_id": "family-id",
    "access_expires_at": "2026-06-19T12:10:00.000Z",
    "refresh_expires_at": "2026-07-19T12:00:00.000Z"
  }
}
```
```

--------------------------------

### Subscribe to a Handle

Source: https://mail.thc.org/docs

Use this endpoint to reserve a handle. A confirmation email will be sent to the specified 'to' address.

```bash
BASE='https://mail.thc.org/api'

curl -sS --get "$BASE/handle/subscribe" \
  --data-urlencode 'handle=alice' \
  --data-urlencode 'to=alice@example.org'
```

--------------------------------

### Automatic Renewal Toggle Success Response

Source: https://mail.thc.org/docs

Example of a successful response after toggling automatic renewal for an API key.

```json
{
  "ok": true,
  "action": "api_credentials_automatic_renew",
  "updated": true,
  "automatic_renew": true,
  "item": {
    "id": 12,
    "owner_email": "alice@example.org",
    "automatic_renew": 1,
    "active": true
  }
}
```

--------------------------------

### POST /api/credentials/create

Source: https://mail.thc.org/docs

Requests an API key creation token by email. This endpoint initiates the process of generating a new API key.

```APIDOC
## POST /api/credentials/create

### Description
Requests an API key creation token by email. This endpoint initiates the process of generating a new API key.

### Method
POST

### Endpoint
/api/credentials/create

### Parameters
#### Request Body
- **email** (string) - Required - The email address for which to request an API key.
- **days** (integer) - Required - The number of days the API key will be valid (1-9999).
- **automatic_renew** (boolean) - Optional - Whether the API key should automatically renew. Accepts booleans and common boolean strings (`true`, `false`, `1`, `0`, `yes`, `no`, `on`, `off`). `automaticRenew` is an accepted alias.

### Request Example
```json
{
  "email": "alice@example.org",
  "days": 30,
  "automatic_renew": false
}
```

### Response
#### Success Response (200)
- **ok** (boolean) - Indicates if the request was successful.
- **action** (string) - The action performed.
- **email** (string) - The email address associated with the request.
- **days** (integer) - The validity period of the API key in days.
- **automatic_renew** (boolean) - Indicates if automatic renewal is enabled.
- **confirmation** (object) - Confirmation details.
  - **sent** (boolean) - Whether the confirmation email was sent.
  - **ttl_minutes** (integer) - The time-to-live for the confirmation in minutes.

#### Response Example (Confirmation Pending)
```json
{
  "ok": true,
  "action": "api_credentials_create",
  "email": "alice@example.org",
  "days": 30,
  "automatic_renew": false,
  "confirmation": {
    "sent": false,
    "ttl_minutes": 15,
    "reason": "cooldown",
    "status": "PENDING",
    "expires_at": "2026-06-19T12:15:00.000Z",
    "last_sent_at": "2026-06-19T12:00:00.000Z",
    "next_allowed_send_at": "2026-06-19T12:01:00.000Z",
    "send_count": 1,
    "remaining_attempts": 2
  }
}
```
```

--------------------------------

### Unsubscribe Alias

Source: https://mail.thc.org/docs

Starts alias removal by emailing the current alias owner. Requires the alias to be specified in the query.

```APIDOC
## GET /api/forward/unsubscribe

### Description
Starts alias removal by emailing the current alias owner.

### Method
GET

### Endpoint
/api/forward/unsubscribe

### Parameters
#### Query Parameters
- **alias** (string) - Required - The email alias to unsubscribe.

### Response
#### Success Response (200)
- **ok** (boolean) - Indicates if the operation was successful.
- **action** (string) - The action performed, e.g., "unsubscribe".
- **alias** (string) - The email alias that was unsubscribed.
- **sent** (boolean) - Indicates if the confirmation email was sent.
- **ttl_minutes** (integer) - The time-to-live for the unsubscribe action in minutes.

#### Response Example (Success)
```json
{
  "ok": true,
  "action": "unsubscribe",
  "alias": "research@thc.org",
  "sent": true,
  "ttl_minutes": 10
}
```

#### Response Example (Failures)
```json
{
  "error": "alias_not_found",
  "alias": "research@thc.org"
}
```

```json
{
  "error": "alias_inactive",
  "alias": "research@thc.org"
}
```
```

--------------------------------

### Rejected Domain Targets

Source: https://mail.thc.org/docs

Examples of invalid domain targets that include schemes, IP addresses, or malformed domain names.

```plaintext
https://example.com
http://example.com
127.0.0.1
::1
example..com
-bad.example
bad-.example
```

--------------------------------

### Create a Handle with an API Key

Source: https://mail.thc.org/docs

Create a new handle associated with an API key. The handle must be unique and will be linked to the owner email of the API key.

```bash
curl -sS -X POST "$BASE/handle/create" \
  -H "X-API-Key: $API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"handle":"alice"}'
```

--------------------------------

### GET /api/admin/protected

Source: https://mail.thc.org/docs

A simple probe endpoint to verify admin access. It returns a confirmation message if the user is authenticated as an administrator.

```APIDOC
## GET /api/admin/protected

### Description
A basic endpoint to test administrator access. It confirms that the authenticated user has administrator privileges.

### Method
GET

### Endpoint
/api/admin/protected

### Parameters
#### Headers
- **X-CSRF-Token** (string) - Required - The CSRF token obtained after authentication.

### Response
#### Success Response (200)
- **message** (string) - A confirmation message indicating successful access.

### Response Example
```json
{
  "message": "This user is an administrator"
}
```
```

--------------------------------

### Sign In

Source: https://mail.thc.org/docs

Authenticates a user via email/username and password. Returns user and session information upon success.

```APIDOC
## POST /api/auth/sign-in

### Description
Authenticates a user using their identifier (email or username) and password. Returns user and session details upon successful authentication.

### Method
POST

### Endpoint
/api/auth/sign-in

### Request Body
- **identifier** (string) - Required - The user's email address or username.
- **password** (string) - Required - The user's password.

### Request Example
```json
{
  "identifier": "admin@example.org",
  "password": "CorrectHorseBatteryStaple1"
}
```

### Response
#### Success Response (200)
- **ok** (boolean) - Indicates success.
- **action** (string) - The action performed ('sign_in').
- **authenticated** (boolean) - True if authentication was successful.
- **user** (object) - User details.
- **session** (object) - Session details including expiry times.

#### Response Example
```json
{
  "ok": true,
  "action": "sign_in",
  "authenticated": true,
  "user": {
    "id": 7,
    "username": "admin",
    "email": "admin@example.org",
    "email_verified_at": "2026-06-19T12:00:00.000Z",
    "is_active": 1,
    "is_admin": true,
    "created_at": "2026-06-19T12:00:00.000Z",
    "updated_at": "2026-06-19T12:00:00.000Z",
    "last_login_at": "2026-06-19T12:00:00.000Z"
  },
  "session": {
    "session_family_id": "family-id",
    "access_expires_at": "2026-06-19T12:10:00.000Z",
    "refresh_expires_at": "2026-07-19T12:00:00.000Z"
  }
}
```

#### Failure
- `auth_failed`: Authentication failed due to invalid credentials.
```

--------------------------------

### GET /api/admin/protected Response

Source: https://mail.thc.org/docs

This is a minimal JSON response from the `/api/admin/protected` endpoint, serving as a simple probe to verify administrator access.

```json
{
  "message": "This user is an administrator"
}
```

--------------------------------

### Get CSRF Token

Source: https://mail.thc.org/docs

Obtain a CSRF token required for authenticated requests. This token is an HMAC-SHA256 of the session family ID.

```json
{
  "ok": true,
  "csrf_token": "base64url-hmac"
}
```

--------------------------------

### Preview of Create Action Confirmation

Source: https://mail.thc.org/docs

This JSON response is a preview of the 'create' action confirmation. It indicates that the action is pending and requires confirmation, detailing the parameters that will be applied.

```json
{
  "ok": true,
  "pending": true,
  "mutation_required": true,
  "action": "create",
  "email": "alice@example.org",
  "days": 30,
  "automatic_renew": false,
  "confirm_via": {
    "method": "POST",
    "path": "/api/credentials/confirm"
  }
}
```

--------------------------------

### Get Alias Statistics

Source: https://mail.thc.org/docs

Retrieves statistics related to email aliases, including totals, active counts, and domain-specific breakdowns.

```APIDOC
## GET /api/alias/stats

### Description
Retrieves statistics for email aliases.

### Method
GET

### Endpoint
/api/alias/stats

### Response
#### Success Response (200)
- **totals** (integer) - Total number of aliases.
- **active** (integer) - Number of active aliases.
- **created_last_7d** (integer) - Number of aliases created in the last 7 days.
- **modified_last_24h** (integer) - Number of aliases modified in the last 24 hours.
- **by_domain** (array) - Statistics broken down by domain.
  - **domain** (string) - The domain name.
  - **total** (integer) - Total aliases for the domain.
  - **active** (integer) - Active aliases for the domain.

#### Response Example
```json
{
  "totals": 10,
  "active": 9,
  "created_last_7d": 2,
  "modified_last_24h": 1,
  "by_domain": [
    {
      "domain": "thc.org",
      "total": 7,
      "active": 7
    }
  ]
}
```
```

--------------------------------

### Admin Domain Creation Success Response

Source: https://mail.thc.org/docs

The expected JSON response upon successful creation of a domain.

```json
{
  "ok": true,
  "created": true,
  "item": {
    "id": 10,
    "name": "example.com",
    "active": 1,
    "active_mx": 0,
    "active_ui": 0,
    "visible": 1
  }
}
```

--------------------------------

### Create an alias with email confirmation

Source: https://mail.thc.org/docs

Initiates the alias creation process by sending a confirmation token to the destination email address. The alias is not created until the token is confirmed.

```APIDOC
## POST /forward/subscribe

### Description
Starts the alias creation flow by sending a confirmation token to the destination email.

### Method
GET

### Endpoint
/forward/subscribe

### Parameters
#### Query Parameters
- **name** (string) - Required - The name of the alias (e.g., 'research').
- **domain** (string) - Required - The domain for the alias (e.g., 'thc.org').
- **to** (string) - Required - The destination email address (e.g., 'alice@example.org').

### Request Example
```sh
BASE=\'https://mail.thc.org/api\' 

curl -sS --get \"$BASE/forward/subscribe\" \
  --data-urlencode 'name=research' \
  --data-urlencode 'domain=thc.org' \
  --data-urlencode 'to=alice@example.org'
```

### Response
#### Success Response (200)
- **ok** (boolean) - Indicates if the request was successful.
- **action** (string) - The action performed ('subscribe').
- **alias_candidate** (string) - The proposed alias address.
- **to** (string) - The destination email address.
- **confirmation** (object) - Contains confirmation details.
  - **sent** (boolean) - True if the confirmation email was sent.
  - **ttl_minutes** (integer) - The time-to-live for the confirmation token in minutes.

#### Response Example
```json
{
  "ok": true,
  "action": "subscribe",
  "alias_candidate": "research@thc.org",
  "to": "alice@example.org",
  "confirmation": {
    "sent": true,
    "ttl_minutes": 10
  }
}
```
```

--------------------------------

### Public Stats Response

Source: https://mail.thc.org/docs

Example JSON response for the public stats endpoint, showing counts for domains, aliases, and forwarded emails.

```json
{
  "domains": 4,
  "aliases": 1200,
  "forwarded": 980000
}
```

--------------------------------

### Create an Alias Using an API Key

Source: https://mail.thc.org/docs

Create a new email alias directly using an API key. The `X-API-Key` header is required for authentication. The `goto` field in the response indicates the owner email bound to the API key.

```bash
BASE='https://mail.thc.org/api'
API_KEY='0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef'

curl -sS -X POST "$BASE/alias/create" \
  -H "X-API-Key: $API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"alias_handle":"research","alias_domain":"thc.org"}'
```

--------------------------------

### Create a handle

Source: https://mail.thc.org/docs

Creates a handle associated with an API key.

```APIDOC
## POST /handle/create

### Description
Creates a new handle associated with the provided API key.

### Method
POST

### Endpoint
/handle/create

### Parameters
#### Headers
- **X-API-Key** (string) - Required - The API key for authentication.

#### Request Body
- **handle** (string) - Required - The handle to create (e.g., "alice").

### Request Example
```json
{
  "handle": "alice"
}
```

### Response
#### Success Response (200)
- **ok** (boolean) - Indicates if the request was successful.
- **created** (boolean) - Indicates if the handle was created.
- **handle** (string) - The created handle.
- **goto** (string) - The owner email address associated with the handle.

#### Response Example
```json
{
  "ok": true,
  "created": true,
  "handle": "alice",
  "goto": "alice@example.org"
}
```
```

--------------------------------

### Enable a Domain for a Handle

Source: https://mail.thc.org/docs

Re-enable a previously disabled domain for a handle. This action can be confirmed using the general confirmation endpoint.

```bash
curl -sS --get "$BASE/handle/domain/enable" \
  --data-urlencode 'handle=alice' \
  --data-urlencode 'domain=thc.org'
```

--------------------------------

### Confirm Handle Subscription

Source: https://mail.thc.org/docs

Confirm the handle subscription using the token received via email. This completes the handle creation process.

```bash
TOKEN='123456'

curl -sS -X POST "$BASE/handle/confirm" \
  -H 'Content-Type: application/json' \
  -d "{\"token\":\"$TOKEN\"}"
```

--------------------------------

### Request an API key

Source: https://mail.thc.org/docs

API keys are created through email confirmation. The key is shown once at POST confirmation time.

```APIDOC
## POST /credentials/create

### Description
Requests the creation of API credentials, which are then confirmed via email.

### Method
POST

### Endpoint
/credentials/create

### Parameters
#### Request Body
- **email** (string) - Required - The email address to associate with the API key.
- **days** (integer) - Required - The number of days the API key will be valid.
- **automatic_renew** (boolean) - Required - Whether the API key should automatically renew.

### Request Example
```json
{
  "email": "alice@example.org",
  "days": 30,
  "automatic_renew": false
}
```

### Response
#### Success Response (200)
- **ok** (boolean) - Indicates if the request was successful.
- **action** (string) - The action performed.
- **email** (string) - The email address used for the request.
- **days** (integer) - The validity period of the key in days.
- **automatic_renew** (boolean) - Indicates if automatic renewal is enabled.
- **confirmation** (object) - Confirmation details.
  - **sent** (boolean) - Indicates if the confirmation email was sent.
  - **ttl_minutes** (integer) - The time-to-live for the confirmation in minutes.

#### Response Example
```json
{
  "ok": true,
  "action": "api_credentials_create",
  "email": "alice@example.org",
  "days": 30,
  "automatic_renew": false,
  "confirmation": {
    "sent": true,
    "ttl_minutes": 15
  }
}
```
```

--------------------------------

### GET /api/stats

Source: https://mail.thc.org/docs

Retrieves public statistics related to domains, aliases, and forwarded emails. The response is a JSON object containing these counts.

```APIDOC
## GET /api/stats

### Description
Returns public counters for domains, aliases, and forwarded emails.

### Method
GET

### Endpoint
/api/stats

### Request Example
```sh
curl -sS "$BASE/stats"
```

### Response
#### Success Response (200)
- **domains** (integer) - Count of visible EMAIL-valid domains.
- **aliases** (integer) - Count of active aliases and handle expansions.
- **forwarded** (integer) - Total count of forwarded emails.

#### Response Example
```json
{
  "domains": 4,
  "aliases": 1200,
  "forwarded": 980000
}
```
```

--------------------------------

### GET /api/domains

Source: https://mail.thc.org/docs

Lists all publicly available and EMAIL-valid domains that can be used for creating aliases. The response is a JSON array of domain strings.

```APIDOC
## GET /api/domains

### Description
Lists public EMAIL-valid domains.

### Method
GET

### Endpoint
/api/domains

### Request Example
```sh
curl -sS "$BASE/domains"
```

### Response
#### Success Response (200)
- **domains** (array of strings) - A list of available domains.

#### Response Example
```json
["thc.org"]
```
```

--------------------------------

### Create a handle with email confirmation

Source: https://mail.thc.org/docs

Reserves a local part across all managed domains. Requires confirmation via email.

```APIDOC
## POST /handle/subscribe

### Description
Creates a new email handle, reserving the local part across all managed domains. An email confirmation is sent to the provided destination.

### Method
GET

### Endpoint
/handle/subscribe

### Parameters
#### Query Parameters
- **handle** (string) - Required - The desired local part for the handle.
- **to** (string) - Required - The email address where confirmation should be sent and to which the handle will eventually route.

### Request Example
```bash
BASE='https://mail.thc.org/api'

curl -sS --get "$BASE/handle/subscribe" \
  --data-urlencode 'handle=alice' \
  --data-urlencode 'to=alice@example.org'
```

### Response
#### Success Response (200)
- **ok** (boolean) - Indicates if the request was successful.
- **action** (string) - The action performed, e.g., 'handle_subscribe'.
- **handle** (string) - The created handle.
- **to** (string) - The destination email address.
- **confirmation** (object) - Information about the confirmation email.
  - **sent** (boolean) - Whether the confirmation email was sent.
  - **ttl_minutes** (integer) - The time-to-live for the confirmation token in minutes.

#### Response Example
```json
{
  "ok": true,
  "action": "handle_subscribe",
  "handle": "alice",
  "to": "alice@example.org",
  "confirmation": {
    "sent": true,
    "ttl_minutes": 10
  }
}
```
```

--------------------------------

### Get CSRF Token

Source: https://mail.thc.org/docs

Retrieves a CSRF token required for authenticated requests. This token is HMAC-SHA256 of the session family id using AUTH_CSRF_SECRET.

```APIDOC
## GET /api/auth/csrf

### Description
Retrieves a CSRF token required for authenticated requests.

### Method
GET

### Endpoint
/api/auth/csrf

### Response
#### Success Response (200)
- **ok** (boolean) - Indicates if the request was successful.
- **csrf_token** (string) - The generated CSRF token.

### Response Example
```json
{
  "ok": true,
  "csrf_token": "base64url-hmac"
}
```
```

--------------------------------

### Compatibility Routes

Source: https://mail.thc.org/docs

These routes are compatibility duplicates for domains and stats due to controller registration. Avoid using these doubled prefixes in new clients.

```plaintext
/api/api/domains
/api/api/stats
```

--------------------------------

### Get Public Stats

Source: https://mail.thc.org/docs

Use this cURL command to retrieve public statistics for the mail forwarding service. The response is a JSON object with counters.

```sh
curl -sS "$BASE/stats"
```

--------------------------------

### Confirm Alias Action (Token Query)

Source: https://mail.thc.org/docs

Executes a pending alias creation or deletion confirmation using a token. The token is provided as a query parameter.

```bash
token=123456
```

--------------------------------

### Error Response for API Token Status Conflict

Source: https://mail.thc.org/docs

Example error response when the provided `status` and `revoked` parameters conflict, indicating an invalid request.

```json
{
  "error": "invalid_params",
  "reason": "status_revoked_conflict"
}
```

--------------------------------

### Admin Route Headers and Methods

Source: https://mail.thc.org/docs

Admin routes require an access session with 'is_admin = 1'. Mutations must use POST, PATCH, or DELETE methods. Ensure you include the 'X-CSRF-Token' header with a valid token.

```text
X-CSRF-Token: <csrf_token>
```

```text
POST
PATCH
DELETE
```

--------------------------------

### API Key Destruction Success Response

Source: https://mail.thc.org/docs

Example of a successful response after destroying an API key. 'notification_sent' indicates if an email notification was successfully dispatched.

```json
{
  "ok": true,
  "action": "api_credentials_destroy",
  "destroyed": true,
  "notification_sent": true
}
```

--------------------------------

### Preview Pending API Key Request

Source: https://mail.thc.org/docs

Preview the details of a pending API key request without issuing the key. This requires a token received during the initial request.

```bash
TOKEN='123456'

curl -sS --get "$BASE/credentials/confirm" \
  --data-urlencode "token=$TOKEN"
```

--------------------------------

### Minimal cURL Admin Session Flow

Source: https://mail.thc.org/docs

This script demonstrates a complete cURL flow for establishing an admin session. It includes signing in, retrieving a CSRF token, and making a request to an admin endpoint. It uses a temporary file for cookie management.

```sh
BASE='https://mail.thc.org/api'
COOKIE_JAR="$(mktemp)"

curl -sS -c "$COOKIE_JAR" -b "$COOKIE_JAR" \
  -X POST "$BASE/auth/sign-in" \
  -H 'Content-Type: application/json' \
  -d '{"identifier":"admin@example.org","password":"CorrectHorseBatteryStaple1"}'

CSRF="$(
  curl -sS -c "$COOKIE_JAR" -b "$COOKIE_JAR" "$BASE/auth/csrf" |
  sed -n 's/.*"csrf_token":"\([^"']\*\)".*/\1/p'
)"

curl -sS -c "$COOKIE_JAR" -b "$COOKIE_JAR" "$BASE/admin/me"
```

--------------------------------

### Successful Alias Removal Confirmation Response

Source: https://mail.thc.org/docs

Example response indicating successful alias removal after confirmation. 'removed: true' signifies the alias has been deactivated.

```json
{
  "ok": true,
  "confirmed": true,
  "intent": "unsubscribe",
  "removed": true,
  "address": "research@thc.org"
}
```

--------------------------------

### Get Session Response

Source: https://mail.thc.org/docs

Retrieves current authenticated user and session details using a valid access cookie. Requires a valid access cookie.

```json
{
  "ok": true,
  "authenticated": true,
  "user": {
    "id": 7,
    "username": "admin",
    "email": "admin@example.org",
    "is_admin": true
  },
  "session": {
    "session_family_id": "family-id",
    "access_expires_at": "2026-06-19T12:10:00.000Z",
    "refresh_expires_at": "2026-07-19T12:00:00.000Z"
  }
}
```

--------------------------------

### Unsubscribe from a Handle

Source: https://mail.thc.org/docs

Initiate the process to unsubscribe from a handle. A confirmation email will be sent.

```bash
BASE='https://mail.thc.org/api'

curl -sS --get "$BASE/handle/unsubscribe" \
  --data-urlencode 'handle=alice'
```

--------------------------------

### GET /api/forward/subscribe

Source: https://mail.thc.org/docs

Initiates the process of creating an email alias by sending a confirmation token. Supports both normal and full address modes for specifying the alias.

```APIDOC
## GET /api/forward/subscribe

### Description
Starts an alias creation request and sends a confirmation token. Supports specifying the alias via `name` and `domain` or a full `address`.

### Method
GET

### Endpoint
/api/forward/subscribe

### Parameters
#### Query Parameters
- **name** (string) - Optional. The local part of the alias address (e.g., 'research'). Mutually exclusive with `address`.
- **domain** (string) - Optional. The domain of the alias address (e.g., 'thc.org'). If omitted, `DEFAULT_ALIAS_DOMAIN` is used. Mutually exclusive with `address`.
- **address** (string) - Optional. The full alias address (e.g., 'research@thc.org'). Mutually exclusive with `name` and `domain`.
- **to** (string) - Required. The destination email address for the alias (e.g., 'alice@example.org').

### Request Example (Normal Mode)
```plaintext
name=research
domain=thc.org
to=alice@example.org
```

### Request Example (Full Address Mode)
```plaintext
address=research@thc.org
to=alice@example.org
```

### Response
#### Success Response (200)
- **ok** (boolean) - Indicates success.
- **action** (string) - The action performed, typically 'subscribe'.
- **alias_candidate** (string) - The proposed alias address.
- **to** (string) - The destination email address.
- **confirmation** (object) - Confirmation details.
  - **sent** (boolean) - Whether the confirmation email was sent.
  - **ttl_minutes** (integer) - Time-to-live for the confirmation token in minutes.

#### Response Example
```json
{
  "ok": true,
  "action": "subscribe",
  "alias_candidate": "research@thc.org",
  "to": "alice@example.org",
  "confirmation": {
    "sent": true,
    "ttl_minutes": 10
  }
}
```

### Error Handling
Common failures include `invalid_params`, `invalid_domain`, `alias_taken`, and specific reasons for invalid parameters like `destination_cannot_be_an_existing_alias` or `destination_cannot_use_managed_domain`.
```

--------------------------------

### Set Base URL for API Calls

Source: https://mail.thc.org/docs

Defines the base URL for making API requests. This is a common setup for shell scripts interacting with the API.

```sh
BASE='https://mail.thc.org/api'
```

--------------------------------

### Confirm handle creation

Source: https://mail.thc.org/docs

Confirms the creation of a handle using a token sent via email.

```APIDOC
## POST /handle/confirm

### Description
Confirms the creation or unsubscription of an email handle using a token received via email.

### Method
POST

### Endpoint
/handle/confirm

### Parameters
#### Request Body
- **token** (string) - Required - The confirmation token received via email.

### Request Example
```bash
TOKEN='123456'

curl -sS -X POST "$BASE/handle/confirm" \
  -H 'Content-Type: application/json' \
  -d "{\"token\":\"$TOKEN\"}"
```

### Response
#### Success Response (200)
- **ok** (boolean) - Indicates if the request was successful.
- **created** (boolean) - True if a new handle was created.
- **updated** (boolean) - True if an existing handle was updated (e.g., unsubscribed).
- **handle** (string) - The handle that was confirmed.
- **goto** (string) - The destination email address for the handle (if created).
- **active** (boolean) - The active status of the handle (if updated).

#### Response Example
```json
{
  "ok": true,
  "created": true,
  "handle": "alice",
  "goto": "alice@example.org"
}
```
```

--------------------------------

### Create API Key Confirmation Success

Source: https://mail.thc.org/docs

Successful confirmation response after executing the 'create' action. It confirms the API key creation, provides the new API key, its expiration, and renewal status.

```json
{
  "ok": true,
  "action": "api_credentials_confirm",
  "confirmed": true,
  "email": "alice@example.org",
  "token": "64_chars_here",
  "token_type": "api_key",
  "expires_in_days": 30,
  "automatic_renew": false
}
```

--------------------------------

### Pagination Parameters

Source: https://mail.thc.org/docs

Defines the 'limit' and 'offset' parameters for paginating list routes, including their valid ranges and default values.

```plaintext
limit: integer, 1..200
offset: integer, >=0

Defaults:
limit=50
offset=0
```

--------------------------------

### UI DNS Verification Request Success Response

Source: https://mail.thc.org/docs

Example of the success response shape from the DNS Checker for a UI verification request, including status and expiry.

```json
{
  "id": 10,
  "target": "example.com",
  "type": "UI",
  "status": "PENDING",
  "expires_at": "2026-06-19T13:00:00.000Z"
}
```

--------------------------------

### Confirm Alias Creation via Token (JSON POST)

Source: https://mail.thc.org/docs

Confirms the alias creation using a 6-digit token received via email. This command uses curl with a JSON POST request.

```sh
BASE='https://mail.thc.org/api'
TOKEN='123456'

curl -sS -X POST "$BASE/forward/confirm" \
  -H 'Content-Type: application/json' \
  -d '{"token":"123456"}'
```
Tokens:
Raw