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 generally available, 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 over HTTP, with SDKs for Node.js and Python when you want one.

Getting started: from zero to first email in 5 minutes

Here is the whole path, from an empty account to a tracked send.

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 are official agent skills for Email API on GitHub. They teach 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 skills you need:

/plugin marketplace add team-telnyx/ai
/plugin install telnyx-email@telnyx telnyx-email-domains@telnyx telnyx-email-inbound@telnyx telnyx-email-suppressions@telnyx

The Telnyx skills marketplace includes four curl-based skills for Email API:

• telnyx-email-curl: Send transactional email, batch sends, scheduled delivery, templates, email validation, and delivery event tracking.
• telnyx-email-domains-curl: Manage sending domains, verify DNS records (SPF, DKIM, DMARC, MX), check domain health, and configure domain-level webhooks.
• telnyx-email-inbound-curl: Manage inboxes, list and search inbound messages and threads, set sender filters, and reply or forward.
• telnyx-email-suppressions-curl: Manage suppressions (blocks), import and export suppression lists, and manage unsubscribe groups.

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 required. Create, render, and send from any language, or use the Node.js and Python SDKs.

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.

What the Email API costs

Pricing is pay as you go and flat rate per tier. Your whole monthly volume bills at the rate for the tier it falls into. A billable email is one message accepted by the Telnyx MTA for one recipient, so a send to three recipients counts as three. Messages rejected at the API are not billed.

Above 2.5M a month, volume pricing trades a monthly commitment for a discounted rate, 24/7 support, and a dedicated customer success manager.

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.