Deliverability and Domain Warm-up

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.

Register your domain via POST /v2/email_domains.
Publish the DNS records Telnyx generates for you — ownership (TXT) and DKIM (TXT on <selector>._domainkey.<domain>) 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.
Verify with POST /v2/email_domains/{domain_id}/verify after DNS propagates (usually 5–15 minutes; can take up to 48 hours).
Use a shared domain for a controlled onboarding test — it needs no DNS setup, but requires onboarding@<shared-domain> 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 for details.

SPF

Publish the SPF record Telnyx generates exactly as specified:

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:

_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 before the first production send.
Register your authenticated domain with Google Postmaster Tools 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. 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 and the 30xxx taxonomy.

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

Records an email.complained event.
Auto-suppresses the recipient (added to suppression list).
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.

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:

{
  "html_body": "<h1>Welcome!</h1><p>Thanks for signing up.</p>",
  "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:

{
  "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:

Records an email.unsubscribed event.
Auto-suppresses the recipient.
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.

Webhooks

Configure webhooks on your sending domain to receive delivery events in real time. See Webhooks & Events.

Event polling

Poll delivery events with GET /v2/email_events — useful for agents and services without a public webhook URL:

curl

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 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@<shared-domain>.
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.

Getting Started

Domains & DNS

Sending Email

Receiving Email

Email Validations

Templates

Events & Webhooks

Suppressions

Deliverability

Deliverability and Domain Warm-up

Verify your sending domain

DKIM signing

SPF

DMARC

Manage your sender reputation

Warm up your sending domain

Before you increase volume

Conservative starting schedule

Migrating an established domain

Decide whether to increase, hold, or pause

Avoid these warm-up mistakes

Keep bounce rates low

What actually gets auto-suppressed

Handle complaints

Monitor sending volume

Content best practices

Include a plain-text alternative

Use a recognizable from name

Include an unsubscribe link

Keep content clear and recognizable

Tracking and monitoring

Webhooks

Event polling

Message size limits

Shared domains

​Verify your sending domain

​DKIM signing

​SPF

​DMARC

​Manage your sender reputation

​Warm up your sending domain

​Before you increase volume

​Conservative starting schedule

​Migrating an established domain

​Decide whether to increase, hold, or pause

​Avoid these warm-up mistakes

​Keep bounce rates low

​What actually gets auto-suppressed

​Handle complaints

​Monitor sending volume

​Content best practices

​Include a plain-text alternative

​Use a recognizable from name

​Include an unsubscribe link

​Keep content clear and recognizable

​Tracking and monitoring

​Webhooks

​Event polling

​Message size limits

​Shared domains

Verify your sending domain

DKIM signing

SPF

DMARC

Manage your sender reputation

Warm up your sending domain

Before you increase volume

Conservative starting schedule

Migrating an established domain

Decide whether to increase, hold, or pause

Avoid these warm-up mistakes

Keep bounce rates low

What actually gets auto-suppressed

Handle complaints

Monitor sending volume

Content best practices

Include a plain-text alternative

Use a recognizable from name

Include an unsubscribe link

Keep content clear and recognizable

Tracking and monitoring

Webhooks

Event polling

Message size limits

Shared domains