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

GET /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.

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

{
  "data": [
    { "name": "examplemail.com", "priceSats": 1000 }
  ]
}

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

2. Create an order

POST /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.

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":"examplemail.com"}'

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

{
  "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.

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.

3. Poll the order

GET /v2/emails/{orderId}

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.

{
  "id": "<payment-hash>",
  "type": "email",
  "site": "telegram.com",
  "domain": "examplemail.com",
  "fulfillmentType": "new",
  "reorderOfOrderId": null,
  "status": "waiting_for_email",
  "orderStatus": "waiting_for_email",
  "email": "[email protected]",
  "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

POST /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.

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

Cancel

POST /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. Manual cancellation confirms the hold release before returning success; provider-side cancellation is best-effort. A completed order cannot be cancelled.

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 means the provider reported a code or message but Lightning settlement did not complete. The content fields may not be returned yet. Continue polling until completed.