> ## 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.
# Deliverability and Domain Warm-up
> Build and protect your email sender reputation with Telnyx — domain warm-up, authentication, list hygiene, bounce handling, and complaint monitoring.
Good deliverability is the difference between email that reaches the inbox and email that lands in spam — or never arrives. This guide covers the practices that matter most for Telnyx Email API senders.
## Verify your sending domain
The single most important deliverability step is domain verification. Recipient providers (Gmail, Outlook, Yahoo) check SPF, DKIM, and DMARC records before accepting mail.
1. **Register your domain** via `POST /v2/email_domains`.
2. **Publish the DNS records** Telnyx generates for you — ownership (TXT) and DKIM (TXT on `._domainkey.`) are required — plus MX when `inbound_enabled` is true; SPF and DMARC are strongly recommended. Fetch the exact values from `GET /v2/email_domains/{domain_id}/dns_records` and publish them as-is.
3. **Verify** with `POST /v2/email_domains/{domain_id}/verify` after DNS propagates (usually 5–15 minutes; can take up to 48 hours).
4. **Use a shared domain** for a controlled onboarding test — it needs no DNS setup, but requires `onboarding@` as the sender and the account owner's verified email address as every recipient.
**Two separate background workers watch your DNS, on different schedules.** Initial verification retries every **30 minutes** after registration, so a domain whose records propagate late will verify on its own without another API call. Once verified, a distinct **drift monitor** re-checks the published records every **6 hours** and transitions the domain to `degraded` if they stop matching. A record you delete or change after verification is therefore detected within hours, not immediately. You can always force an immediate check with `POST /v2/email_domains/{domain_id}/verify`.
Unverified domains cannot send. A send from an unverified domain returns `403` with error code `10007` and a domain-not-verified detail — verify the domain first.
### DKIM signing
Telnyx attempts to DKIM-sign every outbound message using the key generated for your domain at registration time. DKIM signatures let receiving servers verify the message wasn't tampered with in transit.
**DKIM signing is best-effort for custom domains, not guaranteed.** The outbound MTA fails *open* for custom sending domains: if no key is available or the signing operation errors, the message is still sent — unsigned — rather than being rejected. A verified custom domain with a correctly published DKIM record signs reliably, but you should not assume every delivered message carried a valid DKIM signature.
The shared sending domain `mail.telnyx.com` **requires** successful DKIM signing. If signing fails for a shared-domain send, the message is rejected rather than sent unsigned. This does not affect custom domains.
Verify real-world signing with a seed test to a mailbox you control and inspect the received headers, or monitor DMARC aggregate reports.
* **Dynamic DKIM**: Telnyx generates a DKIM keypair automatically during domain registration. No manual key generation is needed.
* **Key rotation**: Keys are generated **at provisioning time**. There is no automatic rotation schedule and no customer-facing rotation endpoint in the current service. Key storage is append-only — creating a new key retires the previous one to a `retiring` state — but that path is operator-initiated, not scheduled. If a key is ever rotated, the DKIM DNS record's `value` changes and you must republish it; the drift monitor will transition the domain to `degraded` until the published record matches. See [Domains & DKIM](/docs/messaging/email/domains) for details.
### SPF
Publish the SPF record Telnyx generates exactly as specified:
```txt theme={null}
yourdomain.com TXT "v=spf1 include:spf.telnyx.com ~all"
```
If you send through multiple providers, add the `include:spf.telnyx.com` directive to your existing SPF record rather than creating a second one — multiple SPF records invalidate each other.
### DMARC
DMARC tells receiving servers what to do when SPF and/or DKIM fail. DMARC is **advisory** — it is not required for verification — but publishing it is strongly recommended.
Telnyx generates a recommended DMARC record for your domain, and it is returned alongside your other records by `GET /v2/email_domains/{domain_id}/dns_records`. The service default is:
```txt theme={null}
_dmarc.yourdomain.com TXT "v=DMARC1; p=none; rua=mailto:dmarc@telnyx.com"
```
The default aggregate-report address is `dmarc@telnyx.com`, which routes reports to Telnyx. Publish the generated value as-is if you want Telnyx to receive them. If you'd rather collect reports yourself, point `rua` at your own mailbox instead — for example `rua=mailto:dmarc@yourdomain.com`, or list both addresses comma-separated. Always publish the record returned by the API rather than hand-authoring one, so the policy tags stay aligned with what Telnyx expects.
* `p=none` is a monitoring-only policy — collect reports without affecting delivery.
* Move to `p=quarantine` or `p=reject` only after reports show alignment is high.
## Manage your sender reputation
Every sending domain builds a reputation with receiving providers. High reputation → inbox. Low reputation → spam folder or rejection.
### Warm up your sending domain
Inbox providers build reputation for both the sending IP and the authenticated domain. Telnyx manages the shared sending infrastructure; you build your domain reputation through recipient quality, consistent volume, and wanted email.
Warm up when you:
* Send from a new domain or subdomain.
* Move an established domain to Telnyx or change sending providers.
* Resume sending after a long inactive period.
* Increase your normal volume substantially.
Low-volume transactional senders may warm naturally as real usage grows. Do not generate artificial traffic just to follow a schedule.
#### Before you increase volume
* Send from a dedicated subdomain, such as `mail.example.com`, that you do not use for employee email.
* Keep transactional and marketing traffic on separate subdomains when possible.
* Verify the domain and publish the SPF, DKIM, and DMARC records returned by Telnyx.
* Start with recipients who explicitly opted in and recently engaged with your product.
* Remove invalid addresses and honor all bounces, complaints, and unsubscribes.
* Configure [webhooks or event polling](/docs/messaging/email/webhooks-events) before the first production send.
* Register your authenticated domain with [Google Postmaster Tools](https://postmaster.google.com/) and use any other mailbox-provider reporting available to you. Provider-reported spam rates are not the same as Telnyx complaint events.
#### Conservative starting schedule
There is no universal warm-up schedule. Mailbox providers evaluate Gmail, Microsoft, Yahoo, and other traffic independently, so review each provider before advancing. Use this as a starting point for a new domain with a clean, opted-in audience:
These are reputation-based ceilings, not Telnyx account quotas. If your account's sending quota is lower, the lower limit applies. See [Rate Limits & Quotas](/docs/messaging/email/rate-limits).
In this schedule, one message means one recipient delivery. Every address in `to`, `cc`, and `bcc` counts toward the daily ceiling for that recipient's mailbox provider. It does not mean one API request. The Email API rejects the same normalized recipient address appearing more than once across those fields.
| Stage | Suggested maximum | What to do |
| ------------- | --------------------------------------------------- | ----------------------------------------------------------------------------------------------- |
| Days 1–2 | 100–500 messages per major mailbox provider per day | Send only to your most recently engaged recipients. Spread sends throughout the day. |
| Days 3–4 | Up to 2× the previous successful daily volume | Increase only where delivery signals remain healthy. |
| Days 5–7 | Increase by 50–100% per day | Hold volume for providers showing increased deferrals or filtering. |
| Week 2 onward | Increase by 20–50% per day | Continue toward normal volume. A high-volume domain may take 3–6 weeks to establish reputation. |
A schedule is a ceiling, not a promise. Do not increase volume simply because another day passed. Hold or reduce it when delivery signals worsen.
If your normal traffic is below these amounts, send only real, wanted traffic appropriate to that sending stream. Never purchase recipients, send to fake addresses, or create synthetic engagement to warm a domain.
#### Migrating an established domain
An established domain may retain some reputation history, but a new sending provider introduces new infrastructure and a changed sending pattern. Keep the previous provider available during the transition, then move a small portion of wanted traffic to Telnyx and increase it gradually. Preserve your recognizable From address and authentication alignment throughout the migration.
#### Decide whether to increase, hold, or pause
Review delivery events by mailbox provider at least daily during warm-up:
`GET /v2/email_events` does not provide a mailbox-provider filter. Group events using the domain in `payload.recipient` and, when present, `payload.mx_hostname`. Multiple recipient domains can belong to the same provider—for example, Outlook, Hotmail, and Live are all Microsoft traffic.
| Signal | Action |
| ---------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Delivery is stable; complaints and hard bounces remain low | Continue the planned increase. |
| `email.deferred` events or provider throttling increase | Hold at the current volume or reduce it until performance normalizes. |
| Hard bounces rise | Pause new volume, validate the source of your addresses, and remove invalid recipients. |
| Provider-reported spam rate approaches 0.1%, or `email.complained` events increase | Pause the ramp and investigate consent, targeting, content, and frequency. Gmail and Yahoo require senders to remain below 0.3%, but you should operate well below that limit. |
A receiving server accepting a message means it was delivered to that server, not necessarily placed in the inbox. Provider reputation tools and controlled inbox-placement tests can supply additional visibility.
Use provider-reported spam rates and Telnyx complaint events together. Google's thresholds refer to the spam rate reported in Google Postmaster Tools, while Yahoo calculates its spam rate from mail delivered to the inbox. Telnyx's `complaint_rate` is the percentage of delivered recipients for whom Telnyx received an individual feedback report. Reporting coverage still differs by provider, so the metrics are not directly comparable.
#### Avoid these warm-up mistakes
* Sending your full audience on the first day.
* Warming with purchased, scraped, old, or unengaged lists.
* Sending only to Gmail while assuming other mailbox providers are warming too.
* Retrying permanent failures or suppressed recipients.
* Mixing risky marketing campaigns with password resets, receipts, or other transactional mail.
* Increasing volume while deferrals, bounces, or complaints are getting worse.
### Keep bounce rates low
* **Hard bounces** (permanent failures like `5.1.1 User unknown`): Remove the recipient immediately. High hard-bounce rates destroy reputation.
* **Soft bounces** (temporary failures like `4.2.1 Mailbox full`): Telnyx retries deferred deliveries automatically. Do not resubmit the message in response to an `email.deferred` event.
**`email.bounced` is broader than "the receiver permanently rejected it."** Four distinct outcomes publish the same event: an ordinary bounce, a queue expiration (retries exhausted), an administrative bounce, and an asynchronous out-of-band bounce. The per-recipient `status` and `error_evidence.code` tell you which actually happened — expiration resolves the recipient to `expired` (code `30005`), an administrative bounce to `failed`, and the others to `bounced` (code `30001`). Don't infer "invalid address" from the event type alone; read the evidence. See [Webhooks & Events](/docs/messaging/email/webhooks-events) and the [30xxx taxonomy](/docs/messaging/email/error-codes#asynchronous-delivery-errors-30xxx).
#### What actually gets auto-suppressed
Telnyx does **not** suppress every bounced recipient. Auto-suppression is deliberately conservative so a transient or sender-side failure doesn't permanently block a valid address:
| Outcome | Auto-suppressed? | Reason recorded |
| ---------------------------------------------------------------------------------- | -------------------------------------------------------- | ---------------- |
| Spam complaint (feedback loop report) | **Yes**, always | `spam_complaint` |
| Queue expiration (retries exhausted) | **Yes** | `hard_bounce` |
| Bounce or OOB with a `5.1.x` or `5.2.x` enhanced code (bad or unavailable mailbox) | **Yes** | `hard_bounce` |
| Bounce or OOB with no enhanced code but a 5xx SMTP status | **Yes** (fallback) | `hard_bounce` |
| Bounce or OOB with a `5.7.x` enhanced code (security/policy) | **No** — sender-side policy, the address may be valid | — |
| Bounce or OOB with any other enhanced code | **No** — not on the suppression allowlist | — |
| Administrative bounce | **No** — operator-initiated, not a deliverability signal | — |
So a recipient can bounce, be recorded with `status: "bounced"`, and still **not** be added to your suppression list. Check the [suppression list](/docs/messaging/email/suppressions) rather than assuming a bounce implies suppression, and remove invalid addresses from your own source of truth regardless.
### Handle complaints
When Telnyx receives an individual spam feedback report from a participating mailbox provider, Telnyx:
1. Records an `email.complained` event.
2. Auto-suppresses the recipient (added to suppression list).
3. Fires a webhook if configured.
Not every mailbox provider supplies individual feedback reports, so `email.complained` events may not capture every user spam report. Monitor provider dashboards in addition to Telnyx events. Treat a provider-reported spam rate approaching 0.1% as a signal to stop increasing volume and investigate. Gmail and Yahoo require senders to remain below 0.3%, but operating close to that limit puts deliverability at risk.
### Monitor sending volume
Sudden spikes in volume trigger spam filters. Use `scheduled_at` to schedule sends across time windows rather than blasting everything at once. See [Scheduled sending](/docs/messaging/email/rate-limits#scheduled-sending).
## Content best practices
### Include a plain-text alternative
Provide a plain-text version for accessibility and email clients that prefer it. Keep the HTML and plain-text versions consistent:
```json theme={null}
{
"html_body": "Welcome!
Thanks for signing up.
",
"text_body": "Welcome! Thanks for signing up."
}
```
### Use a recognizable from name
Recipients who recognize the sender don't mark mail as spam. Use a consistent `from` address and name:
```json theme={null}
{
"from": {
"email": "notifications@yourdomain.com",
"name": "YourApp Notifications"
}
}
```
### Include an unsubscribe link
Every marketing email must include a visible, working unsubscribe link. Telnyx supports RFC 8058 one-click unsubscribe — when a recipient clicks unsubscribe in their email client, Telnyx:
1. Records an `email.unsubscribed` event.
2. Auto-suppresses the recipient.
3. Fires a webhook if configured.
### Keep content clear and recognizable
* Use an honest subject line that matches the message content.
* Avoid deceptive formatting, misleading links, and artificial urgency.
* Use accessible layouts, descriptive link text, and alt text for meaningful images.
* Keep branding and sender identity consistent so recipients recognize the message.
* Test rendering across the email clients your recipients use.
## Tracking and monitoring
Telnyx provides delivery events across the message lifecycle. Key events for deliverability monitoring:
| Event | When | Webhook event type |
| -------------- | ---------------------------------------------------------------------------------- | -------------------- |
| `queued` | Message accepted and queued for delivery | `email.queued` |
| `sent` | Accepted by the Telnyx outbound MTA for delivery | `email.sent` |
| `delivered` | Receiving server accepted the message | `email.delivered` |
| `bounced` | Terminal non-delivery — ordinary bounce, queue expiry, admin bounce, or OOB bounce | `email.bounced` |
| `expired` | Retries exhausted before delivery (recipient status; publishes `email.bounced`) | `email.bounced` |
| `deferred` | Temporary failure, MTA will retry | `email.deferred` |
| `complained` | Telnyx received an individual provider feedback report | `email.complained` |
| `opened` | Recipient opened the message (tracking pixel) | `email.opened` |
| `clicked` | Recipient clicked a tracked link | `email.clicked` |
| `unsubscribed` | Recipient unsubscribed | `email.unsubscribed` |
Delivery webhooks are **recipient-scoped**: one recipient produces one callback with its own `recipient_id` and its own status. A send to five addresses produces five `email.delivered` callbacks, not one. See [Webhooks & Events](/docs/messaging/email/webhooks-events).
### Webhooks
Configure webhooks on your sending domain to receive delivery events in real time. See [Webhooks & Events](/docs/messaging/email/webhooks-events).
### Event polling
Poll delivery events with `GET /v2/email_events` — useful for agents and services without a public webhook URL:
```bash curl theme={null}
curl "https://api.telnyx.com/v2/email_events?email_id=EMAIL_ID" \
-H "Authorization: Bearer ***"
```
The message filter parameter is `email_id`, not `message_id` or `email_message_id`. Unrecognized query parameters are **silently ignored**, so a wrong name returns every event for the account rather than an error.
## Message size limits
Oversized messages are rejected before sending, and large messages hurt deliverability regardless. Three ceilings apply:
| Limit | Value | Failure |
| -------------------------------------------------- | ------ | ------- |
| Message body (`html_body` + `text_body`, decoded) | 1 MB | `422` |
| Total message (decoded body + decoded attachments) | 25 MB | `422` |
| HTTP request body | 150 MB | `413` |
Attachments are base64-encoded in transit, so a 25 MB message occupies roughly 33 MB on the wire — Telnyx measures the **decoded** size. Keep production messages far below these ceilings: large images inflate spam scores and slow rendering. Host images and link to them rather than attaching them. See [Error Codes](/docs/messaging/email/error-codes#request-and-message-size-limits) for the full breakdown.
## Shared domains
If you don't want to manage DNS, use a Telnyx shared domain as a restricted onboarding option:
* **Pre-verified** — no DNS setup required.
* **From-address restricted** — use `onboarding@`.
* **Recipient restricted** — every recipient must match the account owner's verified email address.
* **Read-only** — you can't modify or delete a shared domain.
* **Ideal for controlled onboarding tests** to the account owner's verified address.
Register a custom domain when you need your own `from` address, control over sender authentication and domain reputation, and higher sending volume. See [Domains & DKIM](/docs/messaging/email/domains).