Skip to content
For the complete documentation index, see llms.txt. This page is also available as Markdown.

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. Invalid hostnames, including target sites rejected by the provider’s hostname validation, return 400 INVALID_SITE; they are not server errors.

curl -sS 'https://api.sms4sats.com/v2/emails/domains?site=telegram.com'
{
  "data": [
    { "name": "example.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.

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

Store accessToken securely and pay payreq.

3. Poll the order

GET /v2/emails/{orderId}

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

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.

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. Successful manual cancellation confirms the payment release. A completed order cannot be cancelled.

Email states

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

Last updated