/telnyx-email-domains-curl

name: telnyx-email-domains-curl
description: >-
  Manage email sending domains, verify DNS records (SPF, DKIM, DMARC, MX),
  check domain health, and configure domain-level webhooks for delivery
  events.
metadata:
  author: telnyx
  product: email
  language: curl

Telnyx Email Domains — curl

Installation

# curl is pre-installed on macOS, Linux, and Windows 10+.
# A JSON formatter such as `python3 -m json.tool` is optional.

Setup

export TELNYX_API_KEY="YOUR_API_KEY_HERE"
export TELNYX_API_BASE="https://api.telnyx.com/v2"

# Set these from API responses after creating or listing resources.
export EMAIL_DOMAIN_ID="123e4567-e89b-12d3-a456-426614174000"
export EMAIL_WEBHOOK_ID="123e4567-e89b-12d3-a456-426614174003"

Every request requires:

-H "Authorization: Bearer $TELNYX_API_KEY"

Mutation requests with JSON also require:

-H "Content-Type: application/json"

Use `--fail-with-body --silent --show-error` in automation so non-2xx responses fail the command without hiding the Telnyx error body.

Error Handling

Error responses use an `errors` array:

{
  "errors": [
    {
      "code": "10015",
      "title": "Validation Failed",
      "detail": "domain is invalid",
      "source": {"pointer": "/data/attributes/domain"}
    }
  ]
}

Common cases:

| HTTP | Meaning | Action | |------|---------|--------| | `400` | Invalid list query or malformed input | Fix the query; do not retry unchanged. | | `401` | Missing or invalid API key | Fix authentication. | | `403` | Shared domain is read-only (`10008`) or access is insufficient | Use an owned custom domain or correct permissions. | | `404` | Domain or webhook not found (`10001`) | Re-list resources and verify both IDs. | | `422` | Request validation or state transition failed (`10015` and related codes) | Inspect every error and `source.pointer`; correct the request or state. | | `429` | Rate limit | Honor `Retry-After` when present and back off. | | `500` | Unexpected service error | Retry only safe reads or carefully reconciled mutations. |

Do not retry a create blindly after a transport timeout; first list domains and check whether the resource was created. `verify` and GET operations are safe to repeat. Before retrying DELETE or PATCH, retrieve the current state. Use bounded exponential backoff with jitter for transient `429` and `5xx` failures.

Important Notes

• All 13 reachable operations use the Telnyx v2 REST API and Bearer

authentication.

• A custom domain is not ready merely because `POST /v2/email_domains` succeeds.

Create it, retrieve its generated DNS records, publish those records, trigger verification, and check health until `usable_for_sending` is `true`.

• Call `GET /v2/email_domains/{domain_id}/dns_records` to retrieve the exact DNS

records you need to publish. The response includes the record type, host, value, and priority for each record.

• The OpenAPI DNS-purpose enum includes `ownership`, `spf`, `dkim`, `dmarc`, and

`mx`. SPF, DKIM, and DMARC are authentication-related purposes; MX supports inbound routing when required. Publish the exact API-returned values rather than constructing DNS records from examples.

• Webhooks are configured at the domain level through

`POST /v2/email_domains/{domain_id}/webhooks`, not per message.

• Domain IDs and webhook IDs are UUIDs returned by the API, not domain names.

Operational Caveats

• **Shared versus custom domains:** Telnyx-managed shared domains are

pre-provisioned and readable/usable by accounts. Custom domains require customer DNS setup and verification. Non-owners cannot update, verify, or delete a shared domain; those attempts return `403` with code `10008`.

• **DNS is API-generated:** The API does not expose customer-facing

create/update/delete operations for individual generated DNS records. Publish records at the authoritative DNS provider, then call the verify operation.

• **Tracking defaults live on the domain:** `open_tracking`, `click_tracking`,

and `unsubscribe_tracking` default to `false`, `false`, and `true`, respectively. A send may override these defaults without changing the domain.

• **Health is the readiness signal:** Do not infer deliverability from one DNS

record. Check the aggregate health response and the relevant usability boolean.

• **Verification reflects DNS propagation:** A successful verify request means

the check ran, not that every record passed. Wait and use bounded backoff before checking again; never tight-loop verification.

• **Verified deletion requires intent:** Pass `force=true` to delete a verified

custom domain. Delete returns `200` with the deleted domain, not `204`.

• **Pagination differs by resource:** Domain lists support offset or cursor

pagination. Webhook lists support offset pagination only. Treat cursors as opaque and inspect the returned `.meta` shape.

Reference Use Rules

Do not invent request fields, DNS values, event names, response fields, or status enums.

• Read [references/api-details.md](references/api-details.md) for complete

request/response schemas and every enum.

• Before constructing list filters or pagination, read

[List query parameters](references/api-details.md#list-query-parameters).

• Before branching on DNS or health, read

[DNS and verification semantics](references/api-details.md#dns-and-verification-semantics) and [Response schemas](references/api-details.md#response-schemas).

• Before subscribing to events, read

[Webhook event allowlist](references/api-details.md#webhook-event-allowlist). The allowlist is explicit and has no default-to-all behavior.

• Before retrying failures, read

[Errors and retry behavior](references/api-details.md#errors-and-retry-behavior).

Core Tasks

Provision and verify a custom domain

1. Create a domain

`POST /v2/email_domains`

| Parameter | Type | Required | Description | |-----------|------|----------|-----------