telnyx-email-domains-curl
Manage email sending domains, verify DNS records (SPF, DKIM, DMARC, MX), check domain health, and configure domain-level webhooks for delivery events.
team-telnyx · AI review on file
Installation
Read the source and dependencies before running a command. Copying does not install or execute anything.
npx skills add team-telnyx/ai --skill telnyx-email-domains-curlAbout this skill
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_domainssucceeds. Create it, retrieve its generated DNS records, publish those records, trigger verification, and check health untilusable_for_sendingistrue. - Call
GET /v2/email_domains/{domain_id}/dns_recordsto 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, andmx. 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
403with code10008. - 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, andunsubscribe_trackingdefault tofalse,false, andtrue, 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=trueto delete a verified custom domain. Delete returns200with the deleted domain, not204. - 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
.metashape.
Reference Use Rules
Do not invent request fields, DNS values, event names, response fields, or status enums.
- Read references/api-details.md for complete request/response schemas and every enum.
- Before constructing list filters or pagination, read List query parameters.
- Before branching on DNS or health, read DNS and verification semantics and Response schemas.
- Before subscribing to events, read Webhook event allowlist. The allowlist is explicit and has no default-to-all behavior.
- Before retrying failures, read Errors and retry behavior.
Core Tasks
Provision and verify a custom domain
1. Create a domain
POST /v2/email_domains
| Parameter | Type | Required | Description |
|---|