Voice AI

Provision, Warm Up, and Route a Dedicated Email Sending IP with the Telnyx API

Every email you send through a shared IP inherits someone else's reputation. If your transactional messages — appointment reminders, lab results, invoices — share an IP with unrelated bulk mailers, mailbox providers judge your mail by senders you never chose. For a hospital network, that's not a deliverability metric; it's patients missing appointments because a reminder landed in spam.

The fix is a dedicated sending IP: an address whose reputation you control end to end. But a dedicated IP isn't a switch you flip. It arrives with zero reputation, and you have to warm it up — ramp volume gradually so mailbox providers learn to trust it — and then route every outbound message through it consistently.

This post walks through a working sample that does all of it in six API calls. It's Python and Flask, it runs in simulation mode by default so you can watch the flow without spending anything, and it's structured so you can lift the provisioning logic into your own service.

What the App Does

The sample, provision-and-route-email-dedicated-ips, is a Flask app with a /run endpoint and a CLI entrypoint that execute the same flow:

  1. Purchase a dedicated IP — POST /email/dedicated_ips, with a required Idempotency-Key header.
  2. Start warm-up — POST /email/dedicated_ips/{id}/actions/start_warmup.
  3. Poll until send-ready — GET /email/dedicated_ips/{id} until warm-up is underway and DNS is confirmed.
  4. Create a default IP pool — POST /email/ip_pools with is_default: true.
  5. Add the IP to the pool — POST /email/ip_pools/{id}/ips.
  6. Send a test email — POST /email_messages via the Telnyx SDK; a 202 with status: "queued" proves the routing path is live.

One implementation note worth knowing up front: the telnyx PyPI SDK (verified at 4.189.0) does not yet expose dedicated_ips or ip_pools resources, so the sample calls those endpoints with requests against https://api.telnyx.com/v2. The email send uses the SDK. When the SDK catches up, you swap five HTTP calls for typed clients — the flow doesn't change.

DEMO_MODE=true (the default) simulates the entire flow — no billed IP purchase, no real email. Set DEMO_MODE=false to run against the live API.

How It Works

1. Purchase the dedicated IP

The purchase call takes a region and IP version, and it requires an Idempotency-Key header — omit it and the API returns 400 with code 10015. The sample generates a UUID per run:

import uuid
import requests

resp = requests.post(
    "https://api.telnyx.com/v2/email/dedicated_ips",
    headers={
        "Authorization": f"Bearer {TELNYX_API_KEY}",
        "Idempotency-Key": str(uuid.uuid4()),
        "Content-Type": "application/json",
    },
    json={"region": "ewr-nj1", "ip_version": "ipv4"},
)
ip = resp.json()["data"]
# ip["status"] == "provisioning"

The response comes back with status: "provisioning" — the IP exists as a billed resource before it can carry mail.

2. Start the warm-up lifecycle

Warm-up is the deliberate, gradual ramp of sending volume that teaches mailbox providers to trust a new IP. Telnyx models it as an explicit action on the IP resource:

requests.post(
    f"https://api.telnyx.com/v2/email/dedicated_ips/{ip['id']}/actions/start_warmup",
    headers={"Authorization": f"Bearer {TELNYX_API_KEY}"},
)

The lifecycle is enforced server-side. The sample calls start_warmup a second time on purpose, and the API answers 422 — you cannot restart a warm-up that's already running. That's the kind of guard you want when the state being protected is months of accumulated reputation.

3. Poll until the IP is send-ready

Provisioning and DNS confirmation don't complete instantly, so the sample polls the IP resource on an interval bounded by a timeout:

import time

deadline = time.time() + WARMUP_TIMEOUT_SECONDS
while time.time() < deadline:
    data = requests.get(
        f"https://api.telnyx.com/v2/email/dedicated_ips/{ip['id']}",
        headers={"Authorization": f"Bearer {TELNYX_API_KEY}"},
    ).json()["data"]
    if data["status"] == "warming_up" and data.get("dns_confirmed"):
        break  # ready to route mail
    time.sleep(WARMUP_POLL_INTERVAL_SECONDS)

Because provisioning state and DNS confirmation live on Telnyx's side, this loop is also the recovery path: if your service reboots mid-warm-up, it re-polls and resumes where the IP actually is, rather than losing its place in the lifecycle.

4. Create the default IP pool

A pool is how routing decisions get made: with a default pool in place, outbound email routes through infrastructure you own without per-message configuration:

pool = requests.post(
    "https://api.telnyx.com/v2/email/ip_pools",
    headers={"Authorization": f"Bearer {TELNYX_API_KEY}"},
    json={"name": "default", "is_default": True},
).json()["data"]

5. Add the IP to the pool

requests.post(
    f"https://api.telnyx.com/v2/email/ip_pools/{pool['id']}/ips",
    headers={"Authorization": f"Bearer {TELNYX_API_KEY}"},
    json={"dedicated_ip_id": ip["id"]},
)

6. Send the test email

The send uses the SDK, and the response is the proof the whole flow exists for:

import telnyx

client = telnyx.Client(api_key=TELNYX_API_KEY)
message = client.email_messages.create(
    from_=EMAIL_FROM,       # must be on a verified Telnyx email domain
    to=[EMAIL_TO],          # API requires an array — a bare string returns 422
    subject="Dedicated IP routing verification",
    text_body="Queued through the new dedicated IP pool.",
)
payload = message.model_dump(exclude_none=True)
# HTTP 202 — payload["status"] == "queued", payload["id"] is the message UUID
assert payload["status"] == "queued" and payload["id"]

A 202 with status: "queued" means the message was accepted and routed through the pool backed by your dedicated IP. The full flow, end to end:

POST /email/dedicated_ips            → provisioning
POST .../actions/start_warmup        → warming_up
GET  /email/dedicated_ips/{id}       → warming_up + dns_confirmed
POST /email/ip_pools                 → default pool
POST /email/ip_pools/{id}/ips        → IP routed through pool
POST /email_messages                 → 202, queued

Setup

git clone https://github.com/team-telnyx/telnyx-code-examples.git
cd telnyx-code-examples/provision-and-route-email-dedicated-ips

python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

cp .env.example .env
# edit .env with your credentials

The sample reads seven environment variables:

VariablePurpose
TELNYX_API_KEYTelnyx API key
TELNYX_EMAIL_FROMSender address — must be on a verified Telnyx email domain
TELNYX_EMAIL_TORecipient — use a mailbox you control
DEMO_MODEtrue simulates the flow; false runs against the live API
WARMUP_POLL_INTERVAL_SECONDSPolling interval for the send-ready check
WARMUP_TIMEOUT_SECONDSUpper bound on the warm-up wait
PORTPort for the Flask server

Run it as a one-shot CLI:

python app.py run

Or start the server and hit the endpoint:

python app.py
curl -X POST http://localhost:5000/run

If you'd rather drive it by hand, the same call works over curl:

curl -X POST https://api.telnyx.com/v2/email/dedicated_ips \
  -H "Authorization: Bearer $TELNYX_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"region": "ewr-nj1", "ip_version": "ipv4"}'

Note: the Telnyx CLI does not yet cover email dedicated IPs or IP pools — use the REST calls in this sample. For full API discovery, point your agent or your browser at llms-full.txt.

Teardown and Cost

Dedicated IPs are billed at $14/month per IP as an MRC from the moment of purchase, so release the IP when you're done experimenting:

curl -X DELETE "https://api.telnyx.com/v2/email/dedicated_ips/{ip_id}" \
  -H "Authorization: Bearer $TELNYX_API_KEY"

A released IP stops carrying mail and enters a 30-day quarantine. Removing a pool's last IP — or deleting a pool that still has IPs — returns 409 unless you pass force=true and drain=true. Details are in the Dedicated IPs guide.

Troubleshooting

SymptomCauseFix
400, code 10015, on IP purchaseMissing Idempotency-Key headerAdd the header (the sample generates one automatically)
429 with a waitlist bodyNo dedicated IP stock in the selected regionTry another region; don't retry in a loop
403 on IP purchaseAccount not verified / enterprise / legacyContact Telnyx to enable dedicated IPs

Build On It

The sample is deliberately small: one flow, six calls, two knobs for the polling loop. The natural next steps are scheduling warm-up volume ramps as code, adding per-tenant pools, and wiring the poll loop into your orchestrator's health checks instead of a script. The primitives are all there — dedicated IPs, the warm-up lifecycle, IP pools, and email sends are first-class resources in Telnyx's AI Communications Infrastructure, which means your sending reputation becomes something you can provision, route, and tear down like everything else you run.

Ready to build with low-latency voice AI?

Join developers building the future of real-time conversations