> For the complete documentation index, see [llms.txt](https://docs.sms4sats.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.sms4sats.com/api-reference/emails.md).

# Email Activations

Discover domains, create email activation orders, poll messages, reorder, and cancel safely.

Create a temporary email address for a target site, receive its code or message, and optionally reuse the same assigned address for another activation.

## 1. List available domains

<mark style="color:blue;">`GET`</mark> `/v2/emails/domains?site={hostname}`

`site` is required and must be a valid hostname such as `telegram.com`. Do not include a scheme, path, port, or IP address.

```bash
curl -sS 'https://api.sms4sats.com/v2/emails/domains?site=telegram.com'
```

```json
{
  "data": [
    { "name": "example.com", "priceSats": 1000 }
  ]
}
```

An empty `data` array means no qualifying domain is currently available.

## 2. Create an order

<mark style="color:green;">`POST`</mark> `/v2/emails`

Both JSON fields are required, trimmed strings of 1–255 characters:

| Field    | Meaning                                                      |
| -------- | ------------------------------------------------------------ |
| `site`   | Valid target hostname, matching the domain-discovery request |
| `domain` | Exact available email domain selected from `data[].name`     |

The protected v2 flow requires `X-SMS4SATS-Email-Capability: v1`. The exact value `v1` tells the server to mint and return an independent bearer capability for the new order.

```bash
curl -sS -X POST https://api.sms4sats.com/v2/emails \
  -H 'Content-Type: application/json' \
  -H 'X-SMS4SATS-Email-Capability: v1' \
  -d '{"site":"telegram.com","domain":"example.com"}'
```

Select a domain returned by discovery. Creation revalidates current provider availability and may return `409 EMAIL_DOMAIN_UNAVAILABLE` if inventory changed.

```json
{
  "status": "OK",
  "orderId": "<payment-hash>",
  "accessToken": "<opaque-token>",
  "payreq": "lnbc...",
  "priceSats": 1000,
  "orderStatus": "pending_payment",
  "fulfillmentType": "new",
  "reorderOfOrderId": null
}
```

Store `accessToken` securely and pay `payreq`.

{% hint style="warning" %}
Email creation and reorder do not accept idempotency keys. Do not blindly repeat either `POST` after an ambiguous network response; a successful retry can issue another invoice. Preserve each successful response and continue with its `orderId`.
{% endhint %}

## 3. Poll the order

<mark style="color:blue;">`GET`</mark> `/v2/emails/{orderId}`

```bash
curl -sS https://api.sms4sats.com/v2/emails/ORDER_ID \
  -H 'Authorization: Bearer ACCESS_TOKEN'
```

The snapshot includes `site`, `domain`, `email`, `priceSats`, `status`, `orderStatus`, timestamps, and eventually `code` and/or `message`.

```json
{
  "id": "<payment-hash>",
  "type": "email",
  "site": "telegram.com",
  "domain": "example.com",
  "fulfillmentType": "new",
  "reorderOfOrderId": null,
  "status": "waiting_for_email",
  "orderStatus": "waiting_for_email",
  "email": "assigned@example.com",
  "code": null,
  "message": null,
  "priceSats": 1000,
  "createdAt": "2026-09-30T19:00:00.000Z",
  "updatedAt": "2026-09-30T19:01:10.000Z",
  "paidAt": "2026-09-30T19:01:00.000Z",
  "expiresAt": "2026-09-30T19:21:00.000Z",
  "completedAt": null,
  "cancelledAt": null,
  "failedAt": null
}
```

Poll every 5–10 seconds and stop on `completed`, `cancelled`, `failed`, or `expired`.

## Reorder the same email

<mark style="color:green;">`POST`</mark> `/v2/emails/{orderId}/reorder`

Reorder is available only after the original assigned email has received a code or message. Authenticate with the **original order's** bearer token. The response creates a new order with its own `orderId`, `accessToken`, invoice, and price.

```bash
curl -sS -X POST https://api.sms4sats.com/v2/emails/ORIGINAL_ORDER_ID/reorder \
  -H 'Authorization: Bearer ORIGINAL_ACCESS_TOKEN'
```

## Cancel

<mark style="color:green;">`POST`</mark> `/v2/emails/{orderId}/cancel`

`DELETE /v2/emails/{orderId}` is a server-side alias. Browser clients must use `POST` because the API's CORS policy does not allow `DELETE`. Authenticate with the order's bearer token.

A paid email order becomes cancellable two minutes after payment while no code or message has arrived. Successful manual cancellation confirms the payment release. A completed order cannot be cancelled.

```bash
curl -sS -X POST https://api.sms4sats.com/v2/emails/ORDER_ID/cancel \
  -H 'Authorization: Bearer ACCESS_TOKEN'
```

## Email states

```
pending_payment → paid → waiting_for_email → code_received → completed
                                        ↘ cancelled / failed / expired
```

`code_received` is transitional; content fields may not be available yet. Continue polling until `completed`.