SMTP Migration Guides

Move SMTP sending from another provider to the Telnyx SMTP relay. This guide translates each provider’s settings into Telnyx equivalents, shows the configuration for common frameworks, and covers the differences that matter during cut-over. For connection details, enforced limits, and the replies the relay sends, see the SMTP Protocol Contract. The SMTP protocol contract page (linked throughout) is the authoritative list of replies and limits.

Telnyx SMTP settings

Every framework and provider below translates to these settings:

Setting	Value
Host	`smtp.telnyx.com`
Port	`587`
Encryption	STARTTLS, required before authentication and before any message is accepted. Implicit TLS (port 465) is not offered.
Auth mechanism	`AUTH PLAIN` or `AUTH LOGIN`
Username	`apikey` (the literal string, not an account name or key ID)
Password	A Telnyx API v2 key

The username is always the literal string apikey, not an email address or account login. The password carries the credential.

Framework guides

Nodemailer

const nodemailer = require("nodemailer");

const transport = nodemailer.createTransport({
  host: "smtp.telnyx.com",
  port: 587,
  secure: false,           // 587 = STARTTLS ("secure: true" means implicit-TLS 465, which Telnyx does not offer)
  requireTLS: true,        // refuse to continue unless STARTTLS succeeds
  auth: {
    user: "apikey",        // literal string
    pass: process.env.TELNYX_API_KEY,
  },
});

secure: false + port 587 is Nodemailer’s STARTTLS mode, but on its own it only upgrades if the server advertises STARTTLS. If something on the path strips that advertisement, Nodemailer carries on in plaintext. requireTLS: true makes it upgrade or abort, so the API key is never offered over an unencrypted connection. Do not set secure: true: that selects implicit-TLS port 465, which Telnyx does not offer. Nodemailer-specific pitfalls:

The block above opens a fresh connection per sendMail(), so the per-connection recipient limit only affects a single message with more than 50 To+Cc+Bcc recipients (452 4.5.3 Too many recipients on the 51st). That refusal is per recipient, so it doesn’t fail the send: the message is still submitted for the first 50, and the rest show up in info.rejected. Check it, or chunk before sending.
If you turn on pool: true, pooled connections are long-lived. Telnyx sessions expire 5 minutes after AUTH, and the 50-recipient limit counts across every message on the connection, so keep maxMessages × recipients-per-message at 50 or below.
Pass the Telnyx API key as-is; Nodemailer handles the AUTH encoding.

Verify the settings with swaks or openssl before switching traffic.

Django

settings.py:

EMAIL_HOST = "smtp.telnyx.com"
EMAIL_PORT = 587
EMAIL_USE_TLS = True       # STARTTLS. EMAIL_USE_SSL = False — 465 is not offered.
EMAIL_HOST_USER = "apikey"  # literal string
EMAIL_HOST_PASSWORD = "<TELNYX_V2_API_KEY>"

EMAIL_USE_TLS = True is Django’s STARTTLS mode. Never set EMAIL_USE_SSL = True for Telnyx.
EMAIL_BACKEND stays as-is (django.core.mail.backends.smtp.EmailBackend). send_mail() opens one connection per call, but the connection limits still apply in two common cases:
- one message whose To+Cc+Bcc exceeds 50 addresses gets 452 4.5.3 Too many recipients on the 51st RCPT. Django won’t raise: the message is still submitted for the first 50, and Django discards the list of refused recipients, so the rest are dropped silently;
- send_mass_mail(), or one explicitly opened connection (with get_connection() as conn:) reused across send_messages(), puts all messages on one connection. The 50-recipient limit counts across that whole connection, and the session expires 5 minutes after AUTH.
Chunk recipient lists before sending so each connection carries at most 50 recipients in total, and open a new connection per chunk. A connection left idle for more than 30 seconds between messages is closed with 421 Error: timeout exceeded.

Verify the settings with swaks or openssl before switching traffic.

Rails (ActionMailer)

config/environments/production.rb:

config.action_mailer.delivery_method = :smtp
config.action_mailer.smtp_settings = {
  address:              "smtp.telnyx.com",
  port:                 587,
  user_name:            "apikey",   # literal string
  password:             ENV["TELNYX_API_KEY"],
  authentication:       :plain,     # :login also works; :cram_md5 is not offered
  enable_starttls:      true,       # Rails 7+: STARTTLS or fail
}

enable_starttls: true (Rails 7+) requires STARTTLS and fails the delivery if the server doesn’t offer it. Don’t set enable_starttls_auto alongside it. On older Rails, enable_starttls_auto: true (the default) upgrades only when the server advertises STARTTLS, so it will not stop a downgrade.
authentication: :plain and :login are both accepted (after STARTTLS). :cram_md5 is not offered.
openssl_verify_mode default (peer verification) is correct — do not set :none.

Verify the settings with swaks or openssl before switching traffic.

Laravel

config/mail.php:

'smtp' => [
    'transport'     => 'smtp',
    'host'          => 'smtp.telnyx.com',
    'port'          => 587,
    'encryption'    => 'tls',      // Laravel 9/10; port 587 is what selects STARTTLS
    'username'      => 'apikey',   // literal string
    'password'      => env('TELNYX_API_KEY'),
    'timeout'       => 30,
    'require_tls'   => true,       // symfony/mailer >= 7.3: STARTTLS or fail
],

Under Symfony Mailer (Laravel 9+), the port decides the TLS mode, not the encryption value. Port 465 means implicit TLS, which Telnyx does not offer. Any other port means plaintext connect followed by STARTTLS when the server offers it. So the setting that matters is 'port' => 587. Newer skeletons replace encryption with 'scheme': leave it smtp, never smtps. On its own, that STARTTLS is opportunistic: it happens only if the server advertises it. 'require_tls' => true makes it upgrade-or-fail, like the other guides. It needs symfony/mailer 7.3 or later, which means Laravel 11+ (which passes mailer options through to Symfony Mailer). Laravel 9/10 have no equivalent setting. Verify the settings with swaks or openssl before switching traffic.

WordPress (wp_mail + WP Mail SMTP plugin)

WP Mail SMTP plugin settings (Other SMTP):

Plugin field	Value
SMTP Host	`smtp.telnyx.com`
Encryption	TLS
SMTP Port	587
Authentication	ON
SMTP Username	`apikey`
SMTP Password	Your Telnyx v2 API key. Prefer WP Mail SMTP’s `wp-config.php` constants (`define('WPMS_ON', true);` + `define('WPMS_SMTP_PASS', '…');`), which keep the key out of the database. That is the plugin’s own recommendation.

“Encryption: TLS” in WP Mail SMTP = STARTTLS (matches port 587). “SSL” would expect 465 — not offered.
From address must be on a verified domain: wp_mail’s From address must be on a verified Telnyx sending domain on the same account. The relay checks the envelope sender at MAIL FROM and the From: header at the end of DATA, with the same sender-domain rules as the Send Email API. An unverified domain gets 550 5.7.1 Domain is not verified. Complete DNS setup before sending email.; a domain that isn’t on the authenticated account gets 550 5.7.1 Sending domain <domain> is not available for this account. Set “From Email” to an address on your verified domain. The default wordpress@yourdomain passes only if the site domain is verified in Telnyx.
Plain wp_mail() without a plugin uses PHP mail() (local MTA) — that path never speaks to Telnyx; use the plugin.

Verify the settings with swaks or openssl before switching traffic.

Spring (Java)

application.properties:

spring.mail.host=smtp.telnyx.com
spring.mail.port=587
spring.mail.username=apikey
spring.mail.password=${TELNYX_API_KEY}
spring.mail.properties.mail.smtp.auth=true
spring.mail.properties.mail.smtp.starttls.enable=true
spring.mail.properties.mail.smtp.starttls.required=true

starttls.enable=true upgrades via STARTTLS; starttls.required=true fails the connection if STARTTLS isn’t negotiated, instead of continuing unencrypted. Telnyx refuses AUTH before STARTTLS with 538 5.7.11 Encryption required.
JavaMail’s default mail.smtp.auth mechanisms include PLAIN/LOGIN; no CRAM/DIGEST needed (not offered).

Verify the settings with swaks or openssl before switching traffic.

Client notes that apply to every framework

Command order: connect → EHLO → STARTTLS → EHLO again → AUTH PLAIN or AUTH LOGIN (apikey + API v2 key) → MAIL FROM → RCPT TO → DATA. Before STARTTLS, AUTH is refused with 538 5.7.11 Encryption required, and the connection stays usable: issue STARTTLS, send EHLO, and continue.
Connection limits: 50 recipients per connection, counted across every message on it; messages up to 25,000,000 bytes (SIZE 25000000 in EHLO); 30 seconds of idle time between commands; 300 seconds to transfer the message data; sessions expire 5 minutes after AUTH. The 51st recipient on one connection gets 452 4.5.3 Too many recipients. Most clients treat that as a partial success, not an error, so batch your recipient list across connections up front. A connection idle for more than 30 seconds gets 421 Error: timeout exceeded and is closed. After 5 minutes, the next MAIL, RCPT, or end of DATA is refused; close the connection and open a new one. The SMTP Protocol Contract lists the exact replies.
Rate limits and quotas are shared with the API: there is no separate SMTP limit. When a rate limit or quota is reached, the end of DATA is answered with 452 4.5.3 Mail quota exceeded, try again later. Retry later with backoff.
Content handling: Message data must be valid UTF-8. Send parts in other character sets with Content-Transfer-Encoding: quoted-printable or base64; 8-bit content in another character set is refused at the end of DATA with 554 5.6.0 Message content must be UTF-8; send other character sets as quoted-printable or base64. This is a check on the raw message when it is submitted, not a character-set conversion. Accepted content is delivered unchanged; Telnyx may re-encode it and add a DKIM signature. Don’t send mail you’ve already signed.
Set Message-ID and Date: The relay keeps the Message-ID header your message carries. If Message-ID or Date is missing, the relay does not add it, so set both on every message.
The 250 reply carries the message ID: 250 2.0.0 Ok: queued as <uuid>. The UUID is the Telnyx message ID used by the Email API, webhooks, and Email Detail Records. Log it on accept; it is your correlation handle for support.

Python smtplib

import smtplib
import ssl
from email.message import EmailMessage
from email.utils import formatdate, make_msgid

msg = EmailMessage()
msg["From"] = "[email protected]"
msg["To"] = "[email protected]"
msg["Subject"] = "Hello from Telnyx SMTP"
msg["Date"] = formatdate()                                  # the relay does not add Date
msg["Message-ID"] = make_msgid(domain="verified-domain.com")  # nor Message-ID
msg.set_content("Sent via smtp.telnyx.com:587")

with smtplib.SMTP("smtp.telnyx.com", 587, timeout=30) as smtp:
    smtp.starttls(context=ssl.create_default_context())   # mandatory; verifies the certificate
    smtp.login("apikey", "<TELNYX_V2_API_KEY>")   # literal username
    smtp.send_message(msg)   # ≤50 recipients per connection; open a new connection per batch

If you skip starttls(), smtplib never reaches the server’s 538 5.7.11. Telnyx doesn’t advertise AUTH before TLS, so login() fails locally with SMTPNotSupportedError: SMTP AUTH extension not supported by server. Both mean the same thing: call starttls() first. Pass ssl.create_default_context(): without a context, smtplib’s starttls() does not verify the server certificate or hostname. send_message() raises only if every recipient is refused. If some are (for example the 51st and later, 452 4.5.3), it returns them in a dict and still sends to the rest, so check the return value.

Verify the connection

Test the new settings before switching traffic. Both checks send a real message from a verified sending domain; a successful run ends with 250 2.0.0 Ok: queued as <uuid>. swaks. --tls makes swaks require STARTTLS. Without it, swaks doesn’t start TLS, and the relay doesn’t offer AUTH on an unencrypted connection.

swaks --server smtp.telnyx.com:587 --tls \
  --auth PLAIN --auth-user apikey --auth-password "$TELNYX_API_KEY" \
  --from [email protected] --to [email protected]

openssl. Build the AUTH PLAIN credential, then open a TLS session. -starttls smtp sends EHLO and STARTTLS for you, -crlf sends CRLF line endings, and -ign_eof stops openssl from treating lines that start with Q or R as its own commands. -verify_return_error and -verify_hostname smtp.telnyx.com make the connection fail if the relay’s certificate doesn’t verify — don’t send AUTH credentials over an unverified session.

printf '\0apikey\0%s' "$TELNYX_API_KEY" | openssl base64 -A
openssl s_client -connect smtp.telnyx.com:587 -starttls smtp -crlf -ign_eof -verify_return_error -verify_hostname smtp.telnyx.com

After the handshake, send EHLO again, then AUTH PLAIN <credential>, MAIL FROM, RCPT TO, and DATA. Include From, Date, and Message-ID headers in the message. The SMTP Protocol Contract has a complete session to paste.

Migration tables — from 13 providers

Settings names in each provider column are quoted from that provider’s own docs. Telnyx-side values are the ones the relay enforces; see the SMTP Protocol Contract. Full tables cover six providers, condensed translations cover seven more, and the quick reference has one row per provider.

Migrating from SendGrid

SendGrid SMTP: host smtp.sendgrid.net, “Set the port to 587”; username = literal apikey, password = Mail-Send-scoped API key.

SendGrid setting	Telnyx setting	Notes
Host `smtp.sendgrid.net`	`smtp.telnyx.com`
Port 587	587 unchanged	SendGrid also accepts 25/2525/465 — Telnyx offers 587 only
Username: literal string `apikey`	`apikey` — identical	No change
Password: SendGrid API key (Mail Send scope)	Telnyx API v2 key	Both are “API key as password”; swap the value, keep the shape
AUTH PLAIN/LOGIN, STARTTLS optional (plaintext accepted on 25/2525/587)	STARTTLS required before AUTH	Telnyx refuses AUTH before STARTTLS with `538 5.7.11`; set STARTTLS explicitly
X-SMTPAPI header (categories, templates, personalizations)	Not processed — use the API’s own fields	Telnyx delivers the header unchanged and doesn’t act on it; remove it and use the API for categories, templates, and personalization
30 MB message size (Mail Send v3)	25,000,000 bytes (`SIZE 25000000`)	If you relied on SendGrid’s 30 MB, audit attachments before switching
5k messages per SMTP connection, 10k concurrent connections	5-minute session lifetime after AUTH; 50 recipients per connection	Different shape: Telnyx limits each connection by time and recipient count, not message count — reconnect per batch

Migrating from Mailgun

Mailgun SMTP: regional hosts smtp.mailgun.org (US) and smtp.eu.mailgun.org (EU), one per Mailgun region; ports 25/465/587/2525; per-domain SMTP credentials, default login postmaster@yourdomain.

Mailgun setting	Telnyx setting	Notes
Host `smtp.mailgun.org` (US) / `smtp.eu.mailgun.org` (EU)	`smtp.telnyx.com`	One hostname; no region selection
Ports 25, 465, 587, 2525	587 only	The biggest mechanical change from Mailgun — firewalls/exit policies must allow 587
Per-domain SMTP credentials (`postmaster@yourdomain` + domain password)	`apikey` + Telnyx API v2 key	Credential model change: Mailgun credentials are per-domain and separate from API keys; Telnyx uses the same API v2 key for the API and SMTP. Delete the per-domain credential bookkeeping
AUTH, STARTTLS optional	STARTTLS required before AUTH	Mailgun allows non-TLS on 25/587/2525; Telnyx requires STARTTLS before AUTH and before accepting any message
`X-Mailgun-Recipient-Variables` (batch personalization)	Not processed over SMTP — use the API’s batch send	Telnyx delivers the header unchanged and doesn’t act on it
`X-Mailgun-Drop-Message` test mode	No SMTP test mode	Every message the relay accepts is submitted for delivery. Test with swaks against a mailbox you control
25 MB message size	25,000,000 bytes (`SIZE 25000000`)	About the same

Migrating from Amazon SES

SES SMTP: region-vended endpoints email-smtp.<region>.amazonaws.com; STARTTLS 25/587/2587, TLS Wrapper 465/2465; dedicated SMTP credentials (IAM-derived, per-region, “Your SMTP credentials aren’t identical to your AWS access keys”).

SES setting	Telnyx setting	Notes
Region-vended host `email-smtp.<region>.amazonaws.com`	`smtp.telnyx.com`	One hostname; no region selection
Ports 25/587/2587 (STARTTLS), 465/2465 (TLS Wrapper)	587 only	SES’s port matrix is the broadest; Telnyx publishes one port
Dedicated SMTP credentials (IAM user, access key ID + derived secret, per-region)	`apikey` + Telnyx API v2 key	The biggest change: no SMTP credential derivation, no per-region sets, no IAM policy to manage. The same API v2 key works for the API and SMTP
TLS mandatory (“The Amazon SES SMTP endpoint requires that all connections be encrypted using TLS”)	identical	Telnyx: STARTTLS mandatory
40 MB message size (v2 API & SMTP)	25,000,000 bytes (`SIZE 25000000`)	Downsize alert: SES’s 40 MB becomes 25 MB — audit large senders
50 recipients per message (To/CC/BCC)	50 recipients per connection	Same number, different unit: SES caps per message, Telnyx caps per connection — one RCPT list > 50 must be split across connections, not just across messages
454 Throttling (`Maximum sending rate exceeded`)	`452 4.5.3 Mail quota exceeded, try again later` at the end of `DATA`	Both are 4xx retry-later replies. SMTP sends share your Telnyx API rate limits and quotas
`X-SES-CONFIGURATION-SET` header	Not processed	Telnyx delivers the header unchanged and doesn’t act on it; remove it

Migrating from Postmark

Postmark SMTP: host smtp.postmarkapp.com (smtp-broadcasts.postmarkapp.com for bulk); ports 25/2525/587, no 465 (“Port 465 is not supported with Postmark SMTP”); Server API Token as both username and password, or per-stream SMTP Token pairs.

Postmark setting	Telnyx setting	Notes
Host `smtp.postmarkapp.com`	`smtp.telnyx.com`	Broadcasts and transactional share one host at Telnyx — no separate broadcasts endpoint
Ports 25/2525/587	587 only
Server API Token as both username and password, or SMTP Token Access Key + Secret Key pair	`apikey` (username) + API v2 key (password)	Credential shape change: Postmark’s same-token-both-fields model becomes two-field. Replace Postmark’s credentials: username `apikey`, password = your Telnyx API v2 key
`X-PM-MESSAGE-STREAM` (stream routing)	Not processed	Message Streams are Postmark-specific; Telnyx delivers the header unchanged and doesn’t act on it
`X-PM-Tag` / `X-PM-Metadata-*`	Not processed — use the API’s `tags` / `metadata` fields	Telnyx delivers the headers unchanged and doesn’t act on them
`X-PM-TrackOpens` / `X-PM-TrackLinks`	Not offered over SMTP	No open or click tracking is applied to SMTP mail; send through the API with `tracking_settings` for tracked sends
10 MB message size	25,000,000 bytes (`SIZE 25000000`)	Telnyx is 2.5× Postmark’s cap
”somewhat arbitrary, and informal” SMTP limits (self-policed 10 concurrent connections/IP)	Published, enforced connection limits	See the SMTP Protocol Contract
SMTPApiError synthetic bounce (failures logged as bounce with raw source)	`4xx`/`5xx` replies during the SMTP session, and the message ID in the `250`	Submission errors arrive as SMTP replies during the session

Migrating from Brevo (ex-Sendinblue)

Brevo SMTP: host smtp-relay.brevo.com; ports 587 (STARTTLS, default), 2525 (STARTTLS fallback), 465 (SSL); SMTP login = account email or [ID]@smtp-brevo.com, password = SMTP key (distinct from API keys; named keys, expiry, IP allowlists).

Brevo setting	Telnyx setting	Notes
Host `smtp-relay.brevo.com`	`smtp.telnyx.com`
Ports 587 / 2525 / 465	587 only	Brevo’s 2525 fallback exists for hosts blocking 587; Telnyx has no alternate port, so the network must allow outbound 587
SMTP login: account email or `[ID]@smtp-brevo.com`	`apikey` (literal)	Credential change: Brevo’s email-or-ID login becomes the literal-string username
SMTP key (named, standard 64-char or short 15-char variants, expiry, IP allow/block lists)	Telnyx API v2 key	Credential model change: Brevo’s SMTP keys are separate from its API keys; Telnyx uses the same API v2 key for the API and SMTP
20 MB total message (legacy documented cap; Brevo’s current SMTP pages don’t restate it)	25,000,000 bytes (`SIZE 25000000`)	Telnyx is larger
`535` top cause: “using the relay hostname as the username”	`535 5.7.8 Authentication credentials invalid`	Same failure class, same fix — username is `apikey`, never the hostname
Account suspension blocking SMTP (Brevo: bot attacks on unprotected forms, compromised account)	Telnyx account and domain status applies	A suspended sending domain is refused with `550 5.7.1 Domain is suspended.`

Migrating from Resend

Resend SMTP: host smtp.resend.com; ports 25/465/587/2465/2587 (recommended default 465); username = literal resend, password = full API key incl. re_ prefix; team-wide rate limit 10 req/s across all API keys; Resend does not provide SMTP server logs for debugging.

Resend setting	Telnyx setting	Notes
Host `smtp.resend.com`	`smtp.telnyx.com`
Ports 25/465/587 + 2465/2587 aliases (recommended default 465 implicit TLS)	587 only	Port change: Resend recommends 465; Telnyx offers 587 STARTTLS only. Clients configured for Resend’s default MUST change port and TLS mode
Username: literal string `resend`	`apikey` (literal)	Same literal-string model — swap the constant
Password: full API key including `re_` prefix	Telnyx API v2 key	Both are “full key as password”
Implicit TLS on 465 (client `secure: true` in Nodemailer terms)	STARTTLS on 587	Client config change: Nodemailer `secure: false` + port 587; do not carry over `secure: true`
Team-wide rate limit (10 req/s shared across all keys)	Account’s API rate limits and quotas	SMTP and API sends share them; a limit reached at the end of `DATA` returns `452 4.5.3 Mail quota exceeded, try again later`. See Rate Limits
No SMTP server logs	SMTP replies and the message ID	Every SMTP reply states the outcome. The `250` reply carries the Telnyx message ID; look the message up with `GET /v2/email_messages/{id}`
`Resend-Idempotency-Key` header	Not supported over SMTP	Telnyx delivers the header unchanged and doesn’t act on it. For deduplicated sends, use the API’s `Idempotency-Key` header

Other providers (Mailjet, MailPace, Loops, AgentMail, Cloudflare, SMTP.com, MailerSend)

Mailjet (in-v3.mailjet.com, API keypair as SMTP creds): host → smtp.telnyx.com; port → 587; username apikey; password = Telnyx key. Mailjet’s port-80/588 alternates have no equivalent.
MailPace (smtp.mailpace.com, per-domain token as username+password): username → literal apikey; password → Telnyx key. Unlike MailPace, Telnyx keeps your custom headers and your Message-ID: content is delivered unchanged.
Loops (smtp.loops.so, JSON-payload-in-DATA, template-only): there is no direct SMTP translation — Loops’ body is not MIME. Rebuild as normal MIME submissions against smtp.telnyx.com:587, or move to the API with templates.
AgentMail (smtp.agentmail.to, inbox address as username, API key as password): username → literal apikey. The username does not select the sender: any MAIL FROM address that passes the API’s sender-domain rules can send.
Cloudflare (smtp.mx.cloudflare.net, 465 implicit-TLS only): the port must change to 587 + STARTTLS. A client hard-wired to TLS-on-connect cannot be translated by settings alone, so configure STARTTLS explicitly. api_token username → apikey; Cloudflare API token → Telnyx key. Size goes up: Cloudflare’s 5 MiB default SIZE becomes 25,000,000 bytes. Telnyx allows 50 recipients per connection.
SMTP.com (per-account hosts, per-sender logins): host → smtp.telnyx.com; per-sender “channel” credentials → a Telnyx API v2 key. Telnyx accepts messages up to 25,000,000 bytes, so check your largest messages against that limit before switching.
MailerSend (smtp.mailersend.net, per-domain SMTP users): use smtp.telnyx.com:587 with STARTTLS; username/password → apikey + Telnyx key. MailerSend’s hard 5-message-per-connection cap and desktop-client refusal do not apply. Telnyx sessions still expire 5 minutes after AUTH, and the 50-recipient limit counts across the whole connection, so keep connections short-lived. MailerSend supports custom headers over SMTP on its Professional and Enterprise plans and strips them on lower plans (only X-MailerSend-Tags is preserved on all plans); Telnyx delivers your custom headers unchanged.

What never changes (every provider)

Accepted content is delivered unchanged; Telnyx may re-encode it and add a DKIM signature. Don’t send mail you’ve already signed. No open or click tracking is applied to SMTP mail.
Message data must be valid UTF-8. Send parts in other character sets as quoted-printable or base64. 8-bit content in another character set is refused at the end of DATA with 554 5.6.0 Message content must be UTF-8; send other character sets as quoted-printable or base64; Telnyx checks the raw message and does not convert character sets.
Your headers pass through. Custom headers are delivered unchanged; provider-specific processing headers (X-SMTPAPI, X-Mailgun-, X-PM-, X-SES-*) do nothing at Telnyx. The relay keeps your Message-ID, but it does not add Message-ID or Date when they are missing, so set both.
DKIM and domains: SMTP uses the same verified sending domains and DKIM setup as the API. There are no SMTP-specific DNS records.
From-domain authorization works identically to the API. The envelope sender (checked at MAIL FROM) and the From: header (checked at the end of DATA) must be on a verified sending domain on the authenticated account. Otherwise you get a 550 5.7.1 reply with the same wording as the API error (see the failure-mode quick reference).

Failure-mode quick reference

The replies you are most likely to see during cut-over. The SMTP Protocol Contract lists the replies the relay sends.

Stage	Reply	Meaning	What to do
Connect	`220 smtp.telnyx.com ESMTP email_submission`	Banner	—
AUTH	`538 5.7.11 Encryption required`	AUTH attempted before STARTTLS	Issue STARTTLS first; the connection stays usable
AUTH	`535 5.7.8 Authentication credentials invalid`	Wrong username or invalid API key	Username is the literal `apikey`; check the key is valid
AUTH	`535 5.7.1 Authorization failed: email send capability required`	The key is valid but is not permitted to send email	Use an API key that can send email
AUTH	`421 4.7.0 Temporary authentication failure, retry later`	Authentication temporarily unavailable, or AUTH temporarily refused after repeated failed attempts; the connection closes	Wait, then reconnect and authenticate with a valid key
MAIL / RCPT	`530 5.7.0 Authentication required`	`MAIL FROM` or `RCPT TO` on a connection that is not authenticated	STARTTLS, EHLO, and AUTH first
DATA	`503 Error: need MAIL command`	`DATA` without an accepted `MAIL FROM`, including on a connection that is not authenticated	Authenticate, then send `MAIL FROM` and `RCPT TO` before `DATA`
MAIL / DATA	`550 5.7.1 Domain is not verified. Complete DNS setup before sending email.`	Sender domain exists on the account but isn’t verified	Finish domain verification (same as the API)
MAIL / DATA	`550 5.7.1 Sending domain <domain> is not available for this account`	Sender domain isn’t on the authenticated account	Use a domain on this account, or the right account’s key
MAIL / DATA	`550 5.7.1 Domain is suspended.` / `550 5.7.1 Domain is in a degraded state.` / `550 5.7.1 Domain does not have an active DKIM key configured.` / `550 5.7.1 This domain is receive-only and cannot be used for sending. Verify a custom domain to send email.` / `550 5.7.1 Sender address does not match the domain's sending profile.`	Domain state denies sending — same wording as the API errors	Fix the domain state
MAIL / DATA	`550 5.7.1 Invalid sender address`	Envelope or `From:` address unparseable or domain-less, an empty `MAIL FROM:<>`, or a missing or duplicated `From:` header	Send from a valid address on your verified domain
MAIL / DATA	`451 4.3.0 Temporary submission failure, try again`	Sender check or submission temporarily unavailable. In rare cases, a message that gets this reply at the end of `DATA` has still been accepted	Retry later; a retry after `DATA` can deliver a duplicate
RCPT	`452 4.5.3 Too many recipients`	51st recipient on this connection	Split recipients across connections
DATA	`452 4.5.3 Mail quota exceeded, try again later`	A rate limit or quota was reached, or sending is suspended because of the sending domain’s reputation (the API’s `429`)	Retry later with backoff; for a reputation suspension, contact Telnyx support
MAIL	`552 Estimated message length <n> exceeds limit of 25000000`	Your client declared `SIZE=` above the limit	Shrink below 25,000,000 bytes
DATA	`552 Message too large`	Message exceeds `SIZE 25000000`	Shrink below 25,000,000 bytes
DATA	`552 5.3.4 Message size exceeds fixed maximum message size`	The message is too large to submit	Shrink the message
DATA	`554 5.6.0 Message content must be UTF-8; send other character sets as quoted-printable or base64`	The message data is not valid UTF-8, such as 8-bit content in another character set	Send valid UTF-8, or send parts in other character sets as quoted-printable or base64; don’t retry it unchanged
DATA	`554 5.6.0 Message content rejected`	Telnyx rejected the message for a reason other than its character encoding	Fix the message; don’t retry it unchanged
DATA	`535 5.7.1 Authorization failed on message submission`	Send authorization failed when the message was submitted	Check the API key; authenticate again
DATA	`250 2.0.0 Ok: queued as <uuid>`	Accepted; the UUID is the Telnyx message ID	Log it; the same ID appears in the Email API, webhooks, and Email Detail Records
Any	`421 Error: timeout exceeded`	No command within 30 seconds, or the message data not finished within 300 seconds of the `354`; the server closes the connection	Don’t hold idle connections; reconnect
QUIT	`221 Bye`	Session closed	—

What does not translate: the SMTP feature-header gap

Every provider ships some control headers over SMTP. Telnyx delivers custom headers unchanged but doesn’t act on any of them. If your integration relies on these, move that behavior to the API before cut-over:

Behavior you may have via headers today	Where it goes on Telnyx
Categories / tags (X-SMTPAPI, X-Mailgun-Tag, X-PM-Tag, X-Mailjet-Campaign, X-MailerSend-Tags)	`tags` field on `POST /v2/email_messages`
Custom metadata / unique args	`metadata` field on `POST /v2/email_messages`
Per-message open/click tracking toggles	`tracking_settings` on `POST /v2/email_messages`; SMTP mail is never tracked
Template rendering over SMTP (X-SMTPAPI template_id, X-Mailgun-Template-Name, X-MJ-TemplateID)	`template_id` + `template_variables` on `POST /v2/email_messages`
Scheduling over SMTP (X-SMTPAPI send_at, Deliver-By/Within)	`scheduled_at` on `POST /v2/email_messages` (the deprecated alias `send_at` is still accepted)
Recipient variables / personalization fan-out over one submission	`POST /v2/email_messages/batch`; see Batch Sending
Idempotency (Resend-Idempotency-Key)	`Idempotency-Key` header on the API
Sending-IP / IP-pool selection at SMTP time	Dedicated IP routing is set per domain, not per message

The SMTP-native behavior that carries over unchanged: the relay keeps your own Message-ID, and the final 250 reply carries the Telnyx message ID for log correlation: 250 2.0.0 Ok: queued as <uuid>. It is the same ID the Email API, webhooks, and Email Detail Records use. Capture it if your client can read the final reply line.

Behavioral differences to plan for

Behavior	What changes on Telnyx
TLS posture	STARTTLS is required before AUTH and before any message is accepted. SendGrid/Mailgun/Postmark/SMTP.com/Mailjet all accept plaintext submission somewhere; Telnyx rejects AUTH before STARTTLS with `538 5.7.11`. Clients configured for no encryption fail here — set STARTTLS explicitly.
Auth mechanisms	`AUTH PLAIN` and `AUTH LOGIN` only. CRAM-MD5 / DIGEST-MD5 (Postmark keeps these “for compatibility with older SMTP clients”) are not offered — use STARTTLS + PLAIN/LOGIN.
Credential semantics	Unknown or invalid key → `535 5.7.8 Authentication credentials invalid`. When authentication is temporarily unavailable, AUTH is refused with `421 4.7.0 Temporary authentication failure, retry later`, never accepted, and the connection closes. Repeated failed AUTH attempts can also be temporarily refused with that reply; wait and retry with a valid key.
From-domain gate	The envelope sender is checked at `MAIL FROM` and the `From:` header at the end of `DATA`. Both must be on a verified sending domain on the authenticated account, else `550 5.7.1` with the API’s wording. Same rules as the API.
Message size	25,000,000 bytes (`SIZE 25000000` in EHLO). Oversize → `552` at `MAIL` if your client declares `SIZE=`, otherwise during `DATA`. SES (40 MB) and Resend (40 MB) senders must check their largest messages.
Recipients	50 per connection (`452 4.5.3` on the 51st and later — a per-recipient refusal, so most clients still send to the first 50 without raising). SendGrid’s 1,000-recipient personalization blocks and Mailgun’s 1,000-recipient batches do not fit — chunk, or use the batch API.
Session limits	Sessions expire 5 minutes after AUTH; 30 seconds of idle time between commands and 300 seconds to transfer message data (`421 Error: timeout exceeded`). Long-lived pooled connections (PHPMailer keepalive, Nodemailer `pool: true`) must expect the relay to end them, and the 50-recipient limit counts across every message on the connection.
Suppressed recipients	Same handling as the API: suppressed recipients are not sent to. A `250` reply means Telnyx accepted the message, not that it was delivered.
Content and tracking	No open or click tracking on SMTP mail. Message data must be valid UTF-8; send other character sets as quoted-printable or base64, or the message is refused at the end of `DATA` with `554 5.6.0 Message content must be UTF-8; send other character sets as quoted-printable or base64`. Accepted content is delivered unchanged; Telnyx may re-encode it and add a DKIM signature. Use the API for tracked sends.
Rate limits and quotas	SMTP and API sends share the same rate limits and quotas. A limit or quota reached at `DATA` is `452 4.5.3 Mail quota exceeded, try again later`.

Cut-over playbook

Verify the sending domain first (POST /v2/email_domains → publish DNS records → verify). Telnyx generates its own DKIM keypair — the new DKIM record coexists with your old ESP’s; keep both live during parallel running.
Import suppressions before the first send (POST /v2/email_blocks/import; auto-detects SendGrid/Mailgun/SES CSV exports). Sending to addresses that bounced or complained at your old ESP is the fastest way to damage a new domain’s reputation.
Configure the SMTP client with the Telnyx SMTP settings, and set Message-ID and Date on every message.
Point a canary at smtp.telnyx.com:587 with STARTTLS and the literal username apikey. Verify with the swaks or openssl check. Confirm the 250 2.0.0 Ok: queued as <uuid> line and look the message up with GET /v2/email_messages/{id}.
Split traffic by percentage, keep the old ESP as fallback, compare delivery/bounce via GET /v2/email_events/stats, then ramp — the same parallel-running guidance as the API migration guide.
Watch the connection limits on day one: 50 recipients per connection and 5-minute sessions affect bulk-shaped SMTP jobs that “worked” against permissive providers. Chunk the RCPT list; move true bulk to the batch API.

Translation quick-reference (all providers)

One row per provider. Every row ends up with the same four settings: host smtp.telnyx.com, port 587 with STARTTLS, username the literal apikey, password your Telnyx API v2 key. The last column says what that means coming from each provider. (Loops has no row: its JSON-in-DATA submissions need a rebuild; see Other providers above.)

From	Old host	Old ports	Old username	What you change
SendGrid	`smtp.sendgrid.net`	25/2525/587/465	`apikey`	host → `smtp.telnyx.com`; port → 587 STARTTLS; username stays `apikey`; password → Telnyx key
Mailgun	`smtp.mailgun.org` / `smtp.eu.mailgun.org`	25/587/2525/465	`postmaster@domain`	host → `smtp.telnyx.com`; port → 587 STARTTLS; username → `apikey`; password → Telnyx key
SES	`email-smtp.<region>.amazonaws.com`	25/587/2587/465/2465	per-region SMTP creds	host → `smtp.telnyx.com`; port → 587 STARTTLS; username → `apikey`; password → Telnyx key; delete per-region credential maps
Postmark	`smtp.postmarkapp.com` / `smtp-broadcasts.postmarkapp.com`	25/2525/587	Server token / stream SMTP token	host → `smtp.telnyx.com`; port → 587 STARTTLS; username → `apikey`; password → Telnyx key
Resend	`smtp.resend.com`	25/465/587/2465/2587	`resend`	host → `smtp.telnyx.com`; port → 587 and TLS mode → STARTTLS (Resend’s default is 465 implicit TLS); username → `apikey`; password → Telnyx key
Brevo	`smtp-relay.brevo.com`	587/2525/465	account email / `[ID]@smtp-brevo.com`	host → `smtp.telnyx.com`; port → 587 STARTTLS; username → `apikey`; password → Telnyx key
Mailjet	`in-v3.mailjet.com`	25/80/587/588/2525/465	API key	host → `smtp.telnyx.com`; port → 587 STARTTLS; username → `apikey`; password → Telnyx key
MailPace	`smtp.mailpace.com`	25/587/2525/465	per-domain token	host → `smtp.telnyx.com`; port → 587 STARTTLS; username → `apikey`; password → Telnyx key
AgentMail	`smtp.agentmail.to`	465/587	inbox address	host → `smtp.telnyx.com`; port → 587 STARTTLS; username → `apikey`; password → Telnyx key
Cloudflare	`smtp.mx.cloudflare.net`	465 only	`api_token`	host → `smtp.telnyx.com`; port must change 465 → 587 and TLS mode → STARTTLS; username → `apikey`; password → Telnyx key
SMTP.com	per-account host	25/2525/2082/465	per-sender login	host → `smtp.telnyx.com`; port → 587 STARTTLS; username → `apikey`; password → Telnyx key
MailerSend	`smtp.mailersend.net`	see MailerSend’s docs	generated SMTP user	host → `smtp.telnyx.com`; port → 587 STARTTLS; username → `apikey`; password → Telnyx key

What you get that your old provider didn’t

STARTTLS before credentials and mail. STARTTLS is required before AUTH and before any message is accepted. Among the classic ESPs only SES and MailerSend match this posture. Of the providers in this guide, Cloudflare (TLS-on-connect only) and AgentMail (encryption required on both ports) do too. SendGrid, Mailgun, Postmark and SMTP.com all accept plaintext submission.
Published, enforced limits — Postmark describes its SMTP limits as “somewhat arbitrary, and informal.” Telnyx’s connection limits and replies are on the SMTP Protocol Contract. Rate limits and quotas are shared with the API; a limit reached at DATA returns 452 4.5.3.
Message-ID kept, never dropped — MailPace explicitly drops unsupported headers/Message-ID; Loops can’t accept arbitrary MIME at all. Telnyx keeps your headers and your Message-ID.
One pipeline: SMTP mail uses the same domains, suppressions, DKIM setup, events, and webhooks as API sends, and the message is traceable end to end from the message ID in the 250 reply.

Getting Started

Sending Email

Inboxes

Domains & Validation

Deliverability

Templates & Suppression

Events & Webhooks

For AI Agents

SMTP Migration Guides

Telnyx SMTP settings

Framework guides

Nodemailer

Django

Rails (ActionMailer)

Laravel

WordPress (wp_mail + WP Mail SMTP plugin)

Spring (Java)

Client notes that apply to every framework

Python smtplib

Verify the connection

Migration tables — from 13 providers

Migrating from SendGrid

Migrating from Mailgun

Migrating from Amazon SES

Migrating from Postmark

Migrating from Brevo (ex-Sendinblue)

Migrating from Resend

Other providers (Mailjet, MailPace, Loops, AgentMail, Cloudflare, SMTP.com, MailerSend)

What never changes (every provider)

Failure-mode quick reference

What does not translate: the SMTP feature-header gap

Behavioral differences to plan for

Cut-over playbook

Translation quick-reference (all providers)

What you get that your old provider didn’t

​Telnyx SMTP settings

​Framework guides

​Nodemailer

​Django

​Rails (ActionMailer)

​Laravel

​WordPress (wp_mail + WP Mail SMTP plugin)

​Spring (Java)

​Client notes that apply to every framework

​Python smtplib

​Verify the connection

​Migration tables — from 13 providers

​Migrating from SendGrid

​Migrating from Mailgun

​Migrating from Amazon SES

​Migrating from Postmark

​Migrating from Brevo (ex-Sendinblue)

​Migrating from Resend

​Other providers (Mailjet, MailPace, Loops, AgentMail, Cloudflare, SMTP.com, MailerSend)

​What never changes (every provider)

​Failure-mode quick reference

​What does not translate: the SMTP feature-header gap

​Behavioral differences to plan for

​Cut-over playbook

​Translation quick-reference (all providers)

​What you get that your old provider didn’t

Telnyx SMTP settings

Framework guides

Nodemailer

Django

Rails (ActionMailer)

Laravel

WordPress (wp_mail + WP Mail SMTP plugin)

Spring (Java)

Client notes that apply to every framework

Python smtplib

Verify the connection

Migration tables — from 13 providers

Migrating from SendGrid

Migrating from Mailgun

Migrating from Amazon SES

Migrating from Postmark

Migrating from Brevo (ex-Sendinblue)

Migrating from Resend

Other providers (Mailjet, MailPace, Loops, AgentMail, Cloudflare, SMTP.com, MailerSend)

What never changes (every provider)

Failure-mode quick reference

What does not translate: the SMTP feature-header gap

Behavioral differences to plan for

Cut-over playbook

Translation quick-reference (all providers)

What you get that your old provider didn’t