Send Your First Email

Email API is in invite-only beta. Access is limited to accounts with the email.beta_access capability enabled. Contact us to request access.

Send your first email using the Telnyx Email API: add a sending domain, verify it at your DNS provider, and send a message with a single POST request.

Prerequisites

A Telnyx account (free to create)
An API key from API Keys in the portal (the Auth section)

All requests use the production base URL https://api.telnyx.com/v2 and an Authorization header with the Bearer authentication scheme. Replace YOUR_API_KEY in the examples with your key.

1. Add a sending domain

Emails must be sent from a domain you control so recipients can authenticate the sender (SPF, DKIM, and DMARC). Add your domain with one request:

curl

curl -X POST https://api.telnyx.com/v2/email_domains \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "domain": "example.com"
  }'

The 201 response returns the domain with a status of pending and an id you’ll use in the next steps. Save that id.

Telnyx also provides shared sending domains as a restricted zero-setup option. Shared domains are visible to all accounts in GET /email_domains (look for "type": "shared") and need no DNS setup, but sends must use onboarding@<shared-domain> as the from address and every recipient must match the verified email address of the account owner. Use a custom domain for arbitrary recipients, your own from address, and control over sender authentication and domain reputation.

Trial accounts are restricted to the account owner’s verified email address as the recipient, even with a custom domain. Sending to any other recipient returns 403 with code 10007. Upgrade the account to send to arbitrary recipients.

2. Verify the domain

DNS records are generated for every domain you add. Fetch them and add them at your registrar.

Fetch the DNS records

curl

curl https://api.telnyx.com/v2/email_domains/{domain_id}/dns_records \
  -H "Authorization: Bearer YOUR_API_KEY"

The response includes records for ownership (TXT), SPF (TXT), DKIM (TXT), MX, and DMARC (TXT), each with host, value, and a required flag.

Add the records at your DNS provider

Add each record’s host and value at your registrar or DNS host. Ownership and DKIM are required. MX is required only when inbound_enabled is true; SPF and DMARC are optional but recommended for deliverability.

Trigger verification

curl

curl -X POST https://api.telnyx.com/v2/email_domains/{domain_id}/verify \
  -H "Authorization: Bearer YOUR_API_KEY"

A 200 returns the updated domain. Sending is enabled only when data.status is verified; the same 200 can also report pending (records not yet observed) or failed (a required record is missing or wrong). Inspect the verification map, wait for propagation, and retry.

3. Send your first email

With a verified domain, send a message with a minimal payload — from, to, subject, and text_body:

curl

curl -X POST https://api.telnyx.com/v2/email_messages \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Idempotency-Key: 8e03978e-40d5-43e8-bc93-6894a57f9326" \
  -d '{
    "from": "sender@example.com",
    "to": ["recipient@example.com"],
    "subject": "Hello from Telnyx",
    "text_body": "This is a test email."
  }'

Replace the placeholders:

from: an address on a domain you’ve verified. For a shared domain, use only onboarding@<shared-domain>.
to: the recipient address (an array, even for a single recipient). Shared-domain sends are limited to the account owner’s verified email address. Trial accounts are limited to the account owner’s verified email address on any domain, including custom domains.

The optional Idempotency-Key header makes retries safe. Generate a unique UUID v4 for each logical send, then reuse the same key and request body if a network error leaves the result uncertain. Do not put the key in the JSON body.

4. Check the result

A successful send returns 202 Accepted with the created message:

{
  "data": {
    "record_type": "email_message",
    "id": "b0c7e8cb-6227-4c74-9f32-c7f80c30934b",
    "status": "queued",
    "from": {
      "email": "sender@example.com"
    },
    "to": [
      {
        "email": "recipient@example.com"
      }
    ],
    "subject": "Hello from Telnyx",
    "created_at": "2026-07-06T12:00:00.000000Z"
  }
}

The status: "queued" means your message is on its way. Save the id to look it up and track delivery. If this request is retried after a successful send, Telnyx returns the original status and response body with Idempotent-Replayed: true in the response headers. The first response does not include that header. Retrieve the message:

curl

curl https://api.telnyx.com/v2/email_messages/{id} \
  -H "Authorization: Bearer YOUR_API_KEY"

List events for the message — queued, sent, delivered, bounced, opened, clicked, and more as delivery progresses:

curl

curl https://api.telnyx.com/v2/email_messages/{id}/events \
  -H "Authorization: Bearer YOUR_API_KEY"

You’ve sent your first email. To go further — HTML bodies, attachments, scheduling, idempotency, and tracking — see the Send Email guide.

Getting Started

Domains & DNS

Sending Email

Receiving Email

Email Validations

Templates

Events & Webhooks

Suppressions

Deliverability

Send Your First Email

Prerequisites

1. Add a sending domain

2. Verify the domain

3. Send your first email

4. Check the result

​Prerequisites

​1. Add a sending domain

​2. Verify the domain

​3. Send your first email

​4. Check the result

Prerequisites

1. Add a sending domain

2. Verify the domain

3. Send your first email

4. Check the result