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:
- Purchase a dedicated IP —
POST /email/dedicated_ips, with a requiredIdempotency-Keyheader. - Start warm-up —
POST /email/dedicated_ips/{id}/actions/start_warmup. - Poll until send-ready —
GET /email/dedicated_ips/{id}until warm-up is underway and DNS is confirmed. - Create a default IP pool —
POST /email/ip_poolswithis_default: true. - Add the IP to the pool —
POST /email/ip_pools/{id}/ips. - Send a test email —
POST /email_messagesvia the Telnyx SDK; a202withstatus: "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:
| Variable | Purpose |
|---|---|
TELNYX_API_KEY | Telnyx API key |
TELNYX_EMAIL_FROM | Sender address — must be on a verified Telnyx email domain |
TELNYX_EMAIL_TO | Recipient — use a mailbox you control |
DEMO_MODE | true simulates the flow; false runs against the live API |
WARMUP_POLL_INTERVAL_SECONDS | Polling interval for the send-ready check |
WARMUP_TIMEOUT_SECONDS | Upper bound on the warm-up wait |
PORT | Port 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
| Symptom | Cause | Fix |
|---|---|---|
400, code 10015, on IP purchase | Missing Idempotency-Key header | Add the header (the sample generates one automatically) |
429 with a waitlist body | No dedicated IP stock in the selected region | Try another region; don't retry in a loop |
403 on IP purchase | Account not verified / enterprise / legacy | Contact 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.