Email API: Send Transactional Email on One Platform

Your voice agent just wrapped a call. It confirmed the order, answered two questions, and now it needs to send the receipt with the invoice attached. That last step is the one that used to require a different vendor, a different API key, and a different invoice of your own.

The Telnyx Email API is in beta, on the same carrier-owned platform that already runs your SMS API, Voice API, and WhatsApp. Same key, same dashboard, same bill. Your agents can talk, text, and email without leaving the platform, and act on what happens next, because bounces, opens, and clicks arrive as webhooks they are already listening to.

This guide covers what it is, why we built it, and how to send your first email in five minutes.

What is an email API?

An email API is a REST interface that lets you send email programmatically. Instead of connecting to an SMTP server and managing delivery yourself, you POST a JSON payload and the API handles routing, delivery, tracking, and bounce processing.

Developers use an email API instead of SMTP for the control it gives. You get delivery receipts, open and click tracking, templates, suppression management, and deliverability tooling, all through a single interface. SMTP gives you a pipe. An email API gives you a pipeline.

Why we built Email API

Every SaaS app sends transactional email. Most teams use a separate vendor for it, with a separate API key, a separate invoice, and a separate dashboard. That is one more vendor to manage, one more contract to renew, one more integration to maintain.

Telnyx already runs SMS, voice and WhatsApp on one platform. Email was the last primitive you needed a second vendor for. So we built it into the same infrastructure, on the same MTA stack, with the same API key.

Deliverability is built into the platform, not a separate tool you have to buy. Telnyx generates SPF, DKIM, and DMARC records for your sending domain, verifies them, and monitors for DNS drift so a silent change at your DNS provider does not tank your inbox placement. Two-tier suppression checks catch bounces and spam complaints at both the API and inject time, eliminating the check-to-send race.

The API works from any language via HTTP. No SDK install required.

Getting started: from zero to first email in 5 minutes

Step 1: Set up your sending domain

Bring your own domain and verify via the API, or use a shared domain to get started immediately. Telnyx generates five DNS records: ownership, SPF, DKIM, MX, and DMARC. Publish them at your DNS provider and trigger verification. Telnyx verifies the records and monitors for drift going forward.

Step 2: Send your first email

curl -X POST https://api.telnyx.com/v2/email_messages \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "from": {"email": "[email protected]", "name": "Acme"},
    "to": [{"email": "[email protected]", "name": "Ada"}],
    "subject": "Welcome to Acme",
    "html_body": "<h1>Welcome, Ada!</h1><p>Thanks for signing up.</p>",
    "text_body": "Welcome, Ada! Thanks for signing up."
  }'

Two things to note: from is an object with email and name, not a string. Use html_body, not html.

Step 3: Add a Liquid template

Create a template with Liquid variables for dynamic, personalized content:

curl -X POST https://api.telnyx.com/v2/email_templates \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "name": "Welcome Email",
    "subject": "Welcome to {{company_name}}",
    "html_body": "<h1>Welcome, {{first_name}}!</h1><p>Thanks for signing up.</p>"
  }'

Templates render server-side. Preview without sending by calling the render endpoint with your variables:

curl -X POST https://api.telnyx.com/v2/email_templates/$TEMPLATE_ID/render \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "template_variables": {
      "first_name": "Ada",
      "company_name": "Acme"
    }
  }'

Full template CRUD. No visual editor or SDK required.

Step 4: Set up webhooks

Real-time notifications for every event. Webhooks are Ed25519 cryptographically signed using the telnyx-signature-ed25519 and telnyx-timestamp headers, with automatic retry on non-2xx responses.

Webhooks are configured per sender domain, not per message, using POST /v2/email_domains/{domain_id}/webhooks:

curl -X POST https://api.telnyx.com/v2/email_domains/$DOMAIN_ID/webhooks \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "url": "https://yourapp.com/webhooks/email",
    "events": ["email.sent", "email.delivered", "email.bounced", "email.failed"]
  }'

For services without a public webhook URL, use the event polling API via GET /v2/email_events. Poll for events on your schedule. This is a differentiator, most email providers do not offer polling alongside webhooks.

Step 5: Batch send

Send up to 50 messages in a single API call. The batch endpoint always returns 207 Multi-Status, with per-message success and error arrays:

curl -X POST https://api.telnyx.com/v2/email_messages/batch \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "messages": [
      {
        "from": {"email": "[email protected]", "name": "Acme"},
        "to": [{"email": "[email protected]", "name": "Ada"}],
        "subject": "Your receipt",
        "html_body": "<p>Thanks for your order, Ada.</p>"
      },
      {
        "from": {"email": "[email protected]", "name": "Acme"},
        "to": [{"email": "[email protected]", "name": "Bob"}],
        "subject": "Your receipt",
        "html_body": "<p>Thanks for your order, Bob.</p>"
      }
    ]
  }'

Each message in the batch gets its own status. One call, one round trip, up to 50 messages.

Step 6: Or let your coding agent write it

If you would rather not write the requests yourself, there is an official agent skill for Email API on GitHub. It teaches Claude Code, Cursor, Windsurf, and any other agent that supports the Agent Skills specification how to call these endpoints correctly, instead of guessing from stale training data.

Add the Telnyx skills marketplace, then install the plugin for your language:

/plugin marketplace add team-telnyx/ai
/plugin install telnyx-email@telnyx

The telnyx-email-curl skill covers sending, batch sends, scheduled delivery, templates, email validation, and delivery event tracking. It also encodes the things that are easy to get wrong: that scheduled_at fails open and sends immediately if the timestamp is invalid or in the past, that batch send always returns 207 even when every message succeeds, that Idempotency-Key is only honored on specific endpoints, and that a 429 may signal a reputation suspension rather than a throughput limit. The skill is curl-based, which works as a reference for any language since the API is pure HTTP. Browse the full set at github.com/team-telnyx/ai.

Feature deep-dive

Liquid templates

Reusable templates with Liquid variables for dynamic, personalized content. Server-side rendering with preview without sending. Full template CRUD via POST, GET, PUT, PATCH, DELETE on /v2/email_templates. No visual editor or SDK required. Create, render, and send from any language.

Deliverability, built in

Telnyx generates SPF, DKIM, and DMARC DNS records for your sending domain. You publish them at your DNS provider. Telnyx verifies and monitors for drift. Per-provider throttling shapes sends for Gmail, Outlook, and other major receivers. Domain reputation enforcement: poor reputation is rejected before send with a 429, and a warning band triggers automatic throttling. The domain health summary endpoint gives you a single view of your sending reputation.

Deliverability built in, not bolted on. Not a separate tool, not an add-on.

Suppression management

Automatic suppression of hard bounces, spam complaints, unsubscribes, and invalid addresses. Two-tier check at API and inject time eliminates the race between checking and sending. Soft-bounce escalation triggers suppression after a configurable threshold.

CSV import and export with auto-detection of common provider export formats for one-step migration. Unsubscribe groups with group-scoped opt-outs. RFC 8058 one-click unsubscribe support, meeting Gmail and Yahoo bulk sender requirements.

Email validation

Single and batch validation, free. Validate addresses before you hit send and reduce your bounce rate. Available through the same API, same key, same dashboard.

Tracking

Real-time webhooks for every event from queued to opened. Event polling API via GET /v2/email_events for agents and firewalled services that cannot receive inbound webhooks. Per-message status and full event history lookup. Open, click, and unsubscribe tracking with per-domain toggles.

One platform, every channel

Email alongside SMS, voice, WhatsApp, and fax under one API key. Same dashboard, same bill, same vendor. For existing Telnyx customers, email is an add-on. For new customers, a reason to consolidate. Pay-as-you-go per email, on the same invoice as your other channels.