Skip to content
OpenAgentSkill
Browsing is open · Catalog captured 2026-11-21 · Automatic updates and account services are paused.
Productivity

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-curl

About 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:

HTTPMeaningAction
400Invalid list query or malformed inputFix the query; do not retry unchanged.
401Missing or invalid API keyFix authentication.
403Shared domain is read-only (10008) or access is insufficientUse an owned custom domain or correct permissions.
404Domain or webhook not found (10001)Re-list resources and verify both IDs.
422Request validation or state transition failed (10015 and related codes)Inspect every error and source.pointer; correct the request or state.
429Rate limitHonor Retry-After when present and back off.
500Unexpected service errorRetry 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 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

ParameterTypeRequiredDescription
Read the complete source ↗