Back to Email API

Last updated 18 Nov 2026

What is an email API? How it works, vs SMTP, and setup

An email API lets your app send email with an HTTPS request. See how a send reaches the inbox, when to use SMTP relay instead, and what to set up first.

By Global AEO/SEO Lead
Email API: your app's request ends at 202, then the provider delivers the email to the inbox later.

An email API lets your app send email with an HTTPS request. See how a send reaches the inbox, when to use SMTP relay instead, and what to set up first.

What is an email API?

An email API is a programmatic interface for sending emails without a mail server: your code makes one HTTPS request, and a provider handles everything after that. The sender, recipient, subject, and body are structured as JSON, authenticated with an API key.

That's why an email API for developers is triggered with a few lines of code. A sign-up flow calls it when someone asks for a password reset. A billing job calls it when a payment clears.

Your app sends one request; the email provider queues the message, signs it with DKIM, finds the recipient's mail server, retries, and handles bounces, then sends events back.
Your app sends one request; the email provider queues the message, signs it with DKIM, finds the recipient's mail server, retries, and handles bounces, then sends events back.

Email sending APIs vs mailbox APIs (like the Gmail API)

An email sending API sends domain-level email to anyone: receipts, password resets, and customer alerts. A mailbox API, such as the Gmail API, works inside an individual's mailbox. It reads, sorts, and sends that person's mail only after explicit permission.

InterfaceWhat it doesHow it connectsTypical auth
Email sending APISends mail from an app through a providerHTTPSAPI key
SMTP relayAccepts mail from an app over SMTP and delivers it onwardSMTP submission, port 587Username and password, or API key
Mailbox API (Gmail API, Microsoft Graph)Reads, sends, and manages one user's mailboxHTTPSOAuth, with the user's consent
IMAP or POPLets a mail client read a mailboxIMAP or POP3Username and password, or OAuth

Transactional vs marketing email APIs

Transactional email carries information about a user action: a password reset message, an order confirmation, or a change of address. It contains no promotional text and is used strictly to transmit key information. Marketing emails drive sales through promotional offers, discount codes, restock notifications, and holiday sales. They have different compliance rules.

Many providers send both through one API, but each kind belongs on its own sending stream (its own subdomain and, at high volume, its own IP), so a complaint spike from a newsletter can't drag down your receipts.

In the US, under the FTC's CAN-SPAM guidance, a purely transactional message, such as a receipt, is exempt from most of the Act's rules, including the unsubscribe requirement.

How does an email API work?

An email API works like handing a letter to the clerk at a post office counter. The clerk takes it, says they've got it, and you walk out. That nod means the post office has your letter, not that it reached anyone's mailbox. Delivery happens after you've left.

For an API, the app is the customer and the email provider is the post office. The app sends one HTTPS request, the provider immediately confirms it has the message, and the code moves on. Then the provider does the slow part: it signs the message, finds the recipient's mail server, hands the message over, and tries again later if the server is busy.

That gap explains a support ticket every developer gets eventually. A user swears the password reset never arrived, and your logs show the request succeeded. Both are true: the app did its part, and the message stalled somewhere after the handoff.

One send has two halves: your app's request ends at 202 queued, then the provider handles the MX lookup and delivery and reports events back.
One send has two halves: your app's request ends at 202 queued, then the provider handles the MX lookup and delivery and reports events back.

From API request to the recipient's mail server

A send email API request passes through six steps between the sending app and the recipient's server:

  1. The app sends an HTTPS POST with the message as JSON and an API key in the header.
  2. The provider checks the request: a verified sending domain, a valid recipient, an address not on its suppression list.
  3. The provider queues the message and signs it with DKIM, a cryptographic signature that lets the receiver confirm the sending domain sent it unaltered.
  4. The provider's mail server looks up the recipient domain's MX record, the DNS entry that names the server accepting mail for that domain.
  5. The mail server connects to that server over SMTP and sends the message.
  6. The receiving server accepts the message with a 250 or rejects it with an error code, then its filters file an accepted message in the inbox or the spam folder.

Delivery events: delivered, bounced, deferred, complained

Delivery events are reports on what happened to each recipient after the API call. One recipient can produce several, such as deferred, then delivered, then complained:

  • Delivered means the receiving server accepted the message with a 250. It doesn't mean the inbox: no event reports where the receiving server filed the message.
  • Bounced means delivery failed and the provider stopped trying. A hard bounce is permanent, such as a mailbox or domain that doesn't exist, or a policy block. A soft bounce is temporary, and providers define it differently: some report it as deferred, some as a bounce once retries run out.
  • Deferred means the receiving server asked the provider to try again later, so the provider retries.
  • Complained means the recipient marked the message as spam, on mailbox providers that report complaints back.

Providers also keep a suppression list: addresses that hard-bounced or complained stop receiving mail from the account, protecting the sender's reputation.

Webhooks push these events to a webhook endpoint as they happen.

Tracing an email send

The Telnyx Email API is a REST API: you send a message with a POST request to https://api.telnyx.com/v2/email_messages, authenticated with your Telnyx API key as a Bearer token.

Send one email with the Telnyx Email API

Shell
curl -X POST https://api.telnyx.com/v2/email_messages \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "from": "[email protected]",
    "to": ["[email protected]"],
    "subject": "Your receipt",
    "text_body": "Thanks for your order. Your receipt is below."
  }'

The response comes back as a 202 Accepted with a message ID and a status of queued. That means Telnyx has the message, not that it arrived:

What the API sends back

json
{
  "data": {
    "record_type": "email_message",
    "id": "b0c7e8cb-6227-4c74-9f32-c7f80c30934b",
    "status": "queued",
    "subject": "Your receipt",
    "created_at": "2026-07-06T12:00:00.000000Z"
  }
}

Sending email programmatically with Telnyx (video demo)

Telnyx's demo: sending a transactional email with zero configuration, from request to inbox.

The API reference has more details on API capabilities.

Email API vs SMTP relay

An email API and an SMTP relay are two ways to hand the same message to an email provider. The difference is how the app talks to it. With an API, the app sends one HTTPS request with the message as JSON, and the provider answers with a message ID or an error.

With SMTP relay, the app opens a connection to the provider's mail server and walks through a short back-and-forth: it says hello, logs in, names the sender and each recipient, then sends the message. Mail servers use the same protocol to talk to each other, which is why almost any software can speak it.

After the handoff, the provider delivers the message the same way, no matter which door it came through. So the choice comes down to the software. Use the API when you control the code and want detailed errors and delivery events. Use the relay when the software can only speak SMTP.

When to use SMTP relay

SMTP relay works best for software you can't or won't rewrite: a CMS plugin, a monitoring tool, a scanner that emails PDFs, any app with an SMTP settings screen and nothing else. Pointing that software at a relay takes a hostname, a port, and a password. Rewriting it to call an API takes a project.

When to use an email API

An email API suits in-house products because it answers every request with a specific error code and a message ID trackable through delivery events. It also carries features SMTP has no field for, such as scheduled sends, batches, and retry protection.

Retry protection solves a problem every app hits eventually: a send request times out, and you can't tell whether the provider got it. Retry, and your user may get two password reset emails; don't, and they may get none.

An idempotency key, a unique ID you attach to each send, lets the provider spot the retry and return the first result instead of sending again. On Telnyx, an Idempotency-Key header makes a retried send safe for 24 hours.

Batches turn a thousand order confirmations into one request: on Telnyx, one batch request sends up to 1,000 messages and returns a result for each one. Scheduled sends fail safe there too: Telnyx rejects past send times with a 422 error instead of sending at once.

Email API vs SMTP relay, side by side.

Email APISMTP relay
How the app connectsHTTPS requestSMTP session on port 587
ErrorsSpecific error code per requestSMTP reply codes
Scheduling and batchesCommonVaries by provider
Safe retriesIdempotency keys on some providersVaries by provider
Delivery eventsWebhooks and pollingDepends on the provider
Works with SMTP-only softwareNoYes
Works from cloud VMsYesYes, on port 587

Telnyx also runs an SMTP relay at smtp.telnyx.com on port 587 with STARTTLS. The username is apikey and the password is a Telnyx API key. Mail sent over the SMTP relay gets no open or click tracking; use the API when you need it.

What an email API service replaces

An email API service replaces the mail server an app would otherwise need. That server is an MTA (mail transfer agent: the software that queues mail and delivers it to other mail servers). Running one means retry queues, bounce processing, DNS records, and watching the sending IP's reputation with Gmail and Outlook.

On a cloud server, running an MTA is harder still, because by default the big clouds block outbound port 25, the port mail servers use to deliver to each other:

Outbound port 25 on the three largest clouds.

CloudOutbound port 25What the provider recommends
AWSBlocked by default on EC2 instances and Lambda functionsRemoval on request, or a relay
Google CloudBlocked to destinations outside the VPC networkPort 587 or 465 to a mail service
AzureBlocked for VMs, except Enterprise Agreement and MCA-E subscriptionsAuthenticated relay on port 587

An email provider runs all of that and returns an HTTPS endpoint and a stream of events.

How to set up an email API

Before an email API can start delivering emails, the receiving servers need proof that the sender is allowed to send for the domain. Here's how to get that up and running:

  1. Create an API key and keep it on your server, never in browser code.
  2. Add a sending domain. A subdomain such as mail.example.com keeps app mail apart from the company's own email.
  3. Publish the DNS records the provider generates: usually a verification record, a DKIM key, an SPF entry, and a DMARC record.
  4. Wait for the provider to see the records and mark the domain verified.
  5. Set up a webhook endpoint, or plan to poll the events API.
  6. Test in the sandbox, then send real mail, raising volume gradually on a new domain.

A DMARC record is one line of DNS text. This one asks receivers to report on the domain's mail without blocking any of it yet:

A DMARC record that reports without blocking

text
_dmarc.mail.example.com  TXT  "v=DMARC1; p=none; rua=mailto:[email protected]"

Verify your sending domain with SPF, DKIM, and DMARC

Domain verification authenticates the primary owner of the domain. Authentication records pass that on to receiving servers. SPF is an authorized server allowlist, with DKIM signing each message to verify emails for receivers.

DMARC tells receivers what to do with mail that doesn't pass SPF or DKIM for the domain and where to send reports.

Google and Yahoo bulk email sender rules

Google's sender requirements say sending to Gmail accounts must set up SPF or DKIM, use TLS, have valid forward and reverse DNS for the sending domain or IP, and keep the spam rate below 0.3%.

Senders of more than 5,000 messages a day to Gmail accounts must also publish SPF, DKIM, and DMARC, align the From domain with the SPF or DKIM domain, and offer one-click unsubscribe on marketing mail.

Yahoo's sender requirements closely match Google's, asking senders to honor unsubscribes within two days.

Shared IPs, dedicated IPs, and sending subdomains

Most senders start on a provider's shared IPs, where there is one pooled reputation. A dedicated IP gives your mail its own reputation, which suits high volume senders.

Sending subdomains split reputation at the domain level. M3AAWG, the industry's anti-abuse working group, recommends a separate subdomain for each kind of mail, such as info.example.com for receipts and offers.example.com for marketing.

How to test email APIs safely

A sandbox is the safest way to test APIs: it accepts requests and records delivery outcomes without sending real mail.

Sandbox mode and test recipients

On Telnyx, sandbox mode accepts a message without delivering it, with no billing and no quota use. Eight reserved test addresses simulate fixed outcomes such as a hard bounce or a spam complaint.

For a first send with real delivery, Telnyx lets you send from a shared Telnyx domain with no DNS setup, only to your own verified address.

Do sandbox sends fire webhooks?

Sandbox sends fire webhooks on some providers and not others.

On Telnyx, sandbox sends do fire webhooks: each test address runs a fixed chain of events, such as queued, sending, sent, and bounced for the hard-bounce address. Telnyx's send guide recommends them for testing webhook handling, event polling, and the error screens in your app.

The simulated soft bounce ends in bounced and never sends a deferred event. Simulated hard bounces and complaints add the test address to your suppression list, just as real ones would. Telnyx also lets you fetch any sent message by ID, with its body and its full event history.

Frequently asked questions about email APIs

Osman Husain Telnyx
Osman Husain
Global AEO/SEO Lead

Osman is the Global AEO/SEO Lead at Telnyx, helping make voice AI and communications products clearer for builders. With almost a decade of experience in SEO, he previously led growth at Windscribe and Enzuzo, shipping and scaling organic programs that reached millions.