> ## Documentation Index
> Fetch the complete documentation index at: https://developers.telnyx.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Send Your First Email

> Send your first email with the Telnyx Email API — add a sending domain, verify DNS, and POST to the /email_messages endpoint.

<Callout type="info">
  **Email API is in invite-only beta.** Access is limited to accounts with the `email.beta_access` capability enabled. [Contact us](mailto:support@telnyx.com) to request access.
</Callout>

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](https://telnyx.com/sign-up) (free to create)
* An API key from [API Keys](https://portal.telnyx.com/#/app/api-keys) in the portal (the **Auth** section)

<Callout type="info">
  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.
</Callout>

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

```bash curl theme={null}
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`.

<Callout type="tip">
  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.
</Callout>

<Callout type="warning">
  **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.
</Callout>

## 2. Verify the domain

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

<Steps>
  <Step title="Fetch the DNS records">
    ```bash curl theme={null}
    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.
  </Step>

  <Step title="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.
  </Step>

  <Step title="Trigger verification">
    ```bash curl theme={null}
    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.
  </Step>
</Steps>

## 3. Send your first email

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

```bash curl theme={null}
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:

```json theme={null}
{
  "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:

```bash curl theme={null}
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:

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

<Callout type="tip">
  You've sent your first email. To go further — HTML bodies, attachments, scheduling, idempotency, and tracking — see the [Send Email](/docs/messaging/email/send-email) guide.
</Callout>