SMTP vs REST API for Transactional Email: When Each Wins
SMTP wins on universal client compatibility and zero-SDK integration. REST wins on latency, structured errors, and analytics attribution. Pick by use case, not dogma.
By SESMetric Editorial
Every transactional email provider exposes two send paths: an SMTP relay and a REST API. The marketing pages treat them as interchangeable. They are not. The protocol you pick shapes your latency budget, your error handling, your test surface, and how much attribution data flows back into your application.
This piece walks through where each protocol earns its keep, with code in both styles and a decision matrix at the end.
SMTP vs REST API: the real tradeoff
The smtp vs rest api debate is really a question about where your sending code lives and what it already knows how to do. SMTP is a 1982 protocol that every mail-capable runtime, framework, and appliance already speaks. REST is a 2000s convention that gives you structured JSON in and out. Neither is "modern" or "legacy"; they solve different problems.
A useful mental split:
- SMTP is a transport. It moves a MIME blob between two servers. The provider sees a finished envelope and a finished message, then relays them.
- REST is a control plane. You hand the provider intent (template ID, variables, recipient, tags) and it assembles the MIME on your behalf.
Once you frame it that way, the rest of the tradeoffs fall out cleanly.
Where SMTP wins
Universal client compatibility
SMTP is what Postfix, Sendmail, exim, msmtp, Rails ActionMailer, Django EMAIL_BACKEND, Laravel Mail, WordPress, GitLab, Jenkins, Grafana, Prometheus Alertmanager, and every multi-function printer made after 1998 speak natively. If your application already builds emails, it almost certainly already builds them through an SMTP client somewhere in the dependency tree.
Switching providers becomes three environment variables:
SMTP_HOST=smtp.sesmetric.com
SMTP_PORT=587
SMTP_USER=apikey
SMTP_PASS=sk_live_xxxxxxxxxxxx
No SDK install. No serializer rewrite. No retry logic to port. The framework's existing mailer keeps working exactly as it did with the previous relay, which keeps the blast radius of the change to a config file.
Legacy and appliance traffic
Some traffic literally cannot speak HTTP cleanly: CI runners with restricted egress, on-prem ERP systems, network appliances, Docker images you do not control. SMTP on port 587 with STARTTLS is the lowest-common-denominator way to get those boxes to send mail through a managed provider. The same is true for cron jobs that already shell out to mail or sendmail; you do not want to rewrite them into HTTP clients just to swap vendors.
Sending arbitrary MIME
If you have already assembled a multipart MIME message, including inline images, calendar invites, or signed S/MIME, SMTP takes it byte-for-byte. REST endpoints typically constrain you to their JSON shape, which makes truly exotic MIME (DKIM-signed by you, PGP-encrypted, custom headers in odd positions) harder to express. When the message itself is the contract, SMTP gets out of the way.
A Python smtplib example
import smtplib
import ssl
from email.message import EmailMessage
msg = EmailMessage()
msg["From"] = "receipts@example.com"
msg["To"] = "user@customer.com"
msg["Subject"] = "Your receipt #4821"
msg.set_content("Thanks for your order. Total: $42.00")
msg.add_alternative(
"<p>Thanks for your order. Total: <b>$42.00</b></p>",
subtype="html",
)
ctx = ssl.create_default_context()
with smtplib.SMTP("smtp.sesmetric.com", 587, timeout=10) as s:
s.starttls(context=ctx)
s.login("apikey", "sk_live_xxxxxxxxxxxx")
s.send_message(msg)
Twelve lines. No SDK. Works on Python 3.6+ with stdlib only. The same pattern translates directly to Node's nodemailer, Go's net/smtp, or any other language with a stock SMTP client.
Where REST wins
One-call templating
With REST, the template lives on the provider. You send a template slug and a variables dict; the provider renders. No HTML in your codebase, no template deploys gated on application releases, no drift between staging and production renders.
import requests
resp = requests.post(
"https://api.sesmetric.com/v1/send",
headers={"Authorization": "Bearer sk_live_xxxxxxxxxxxx"},
json={
"to": "user@customer.com",
"from": "receipts@example.com",
"template": "order-receipt",
"variables": {
"order_id": "4821",
"total": "$42.00",
"items": [{"name": "Widget", "qty": 2}],
},
"tags": ["receipts", "checkout-v3"],
},
timeout=5,
)
resp.raise_for_status()
message_id = resp.json()["id"]
The response gives you message_id synchronously. That ID is the key for every downstream event (opens, clicks, bounces, complaints), so attribution starts the moment the call returns.
Structured errors
SMTP errors are terse multi-line codes from another era:
550-5.7.26 Unauthenticated email from example.com is not accepted due to
550-5.7.26 domain's DMARC policy. Please contact the administrator of
550 5.7.26 example.com domain.
Your client has to parse the enhanced status code, decide whether 5.7.26 is permanent or temporary, and surface something useful to the operator. Provider-specific extensions to these codes are common and undocumented, so portable parsing is harder than it looks.
REST gives you JSON:
{
"error": {
"code": "dmarc_reject",
"message": "Sender domain example.com publishes DMARC p=reject and this message is not aligned.",
"retryable": false,
"docs_url": "https://sesmetric.com/docs/errors/dmarc_reject"
}
}
The code field is stable. You can branch on it in a switch statement without regex parsing, and retryable tells your queue worker exactly what to do.
Simpler auth than SASL
SMTP authenticates via SASL, usually AUTH LOGIN or AUTH PLAIN with a username and password (or API key dressed up as a password). Rotation means coordinating restarts across every box that holds the credential and worrying about which mechanism each peer advertises.
REST authenticates with a bearer token in an Authorization header. Rotation is a header swap. Per-environment keys, per-service keys, scoped keys; all trivially expressible without negotiating mechanisms.
Easier to mock for tests
Mocking an HTTP call is a one-liner in every test framework:
import responses
@responses.activate
def test_sends_receipt():
responses.add(
responses.POST,
"https://api.sesmetric.com/v1/send",
json={"id": "msg_test_123"},
status=200,
)
send_receipt(order)
assert responses.calls[0].request.url.endswith("/v1/send")
Mocking SMTP requires either a fake SMTP server (aiosmtpd, MailHog) or monkey-patching smtplib.SMTP. Both work; neither is as ergonomic, and neither plays as nicely with parallel test runners.
JSON instead of MIME assembly
You do not have to think about boundaries, transfer encodings, or the difference between multipart/alternative and multipart/mixed. Hand the API a dict; it produces the right MIME on the wire. The escape hatch for binary attachments is usually a base64-encoded array of objects, which is still simpler than building MIME by hand.
Latency profile
This is the one that surprises people most.
A first-time SMTP send to a remote relay is four round-trips before the message bytes leave: TCP handshake, STARTTLS negotiation, EHLO, AUTH. On a 50ms RTT link, that is roughly 200ms before the DATA command. The connection is reusable, but only if your worker is long-lived and holds the socket open. Lambda functions, request-scoped handlers, and queue consumers that exit between jobs pay the full handshake cost on every send.
REST is one HTTPS round-trip with TLS session resumption, typically 30 to 80ms warm and around 150ms cold. The provider does any internal queuing on its side, and HTTP/2 keep-alive amortizes TLS across batched sends without any work on your end.
Rough comparison for a single send from a stateless worker:
| Step | SMTP (cold) | REST (cold) |
|---|---|---|
| TCP + TLS | ~150ms | ~120ms (resumed: ~40ms) |
| Protocol handshake | ~100ms (EHLO + AUTH) | 0 |
| Payload | ~50ms (DATA + body + DOT) | ~30ms |
| Total | ~300ms | ~150ms |
For long-lived workers that pool SMTP connections, the gap closes. For serverless or short-lived containers, REST is consistently faster end-to-end and far easier to reason about under load.
Error handling in practice
REST and SMTP both surface failures, but the affordances differ. With REST, you catch on the HTTP status and branch on error.code. With SMTP, you wrap send_message around smtplib.SMTPResponseException, read e.smtp_code and e.smtp_error, and write your own classifier. That classifier is provider-specific and tends to rot quietly when the upstream changes wording.
Plan for both layers in either path: a per-message error and a transport-level error (connection refused, TLS failure, timeout). Either way, your queue consumer needs the same two retry policies: backoff on transient, fail fast on permanent.
Webhook attribution
This often decides the call.
With REST, the response carries message_id synchronously. You write that ID into your outbound_emails table alongside the user, the template, and the tags. When the provider fires a delivery, open, click, bounce, or complaint webhook hours later, the payload references the same message_id. Join trivially.
With SMTP, the provider assigns the ID after it accepts the message. You get it back in one of two ways: parse the trailing line of the 250 Ok response (provider-specific format), or correlate via your own Message-ID: header. The first is brittle. The second works but requires you to generate and store the header yourself before sending. Both patterns are doable; neither is as clean as a JSON field on the response.
If real-time event attribution matters, where every bounce ties back to an order and every click feeds a behavior model, REST removes a class of bugs you would otherwise hand-roll.
When the choice is forced
A few cases collapse the decision:
- You are routing mail from Postfix or an MTA. SMTP. There is no other answer.
- You need DSN (delivery status notification) bounces handled by your own MTA. SMTP.
- You are sending from a serverless function with no pooled connections. REST. The handshake cost dominates per-invocation latency.
- You need provider-side templating and per-message tags. REST. SMTP can carry tags via custom headers (for example
X-SM-Tag:), but it is a second-class path. - Your egress firewall blocks port 587 outbound but allows HTTPS. REST. It rides 443 along with everything else.
Decision matrix
| Use case | Pick | Why |
|---|---|---|
| Postfix or existing MTA relay | SMTP | Drop-in; no app code change |
| Rails / Django / Laravel default mailer | SMTP | Framework already speaks it |
| Serverless function (Lambda, Workers) | REST | No connection pooling; handshake too expensive |
Need synchronous message_id for attribution | REST | Returned in response body |
| Sending custom-signed or PGP-encrypted MIME | SMTP | Byte-exact transport |
| Provider-side templating with variables | REST | One call, no local HTML |
| On-prem appliance, printer, or scanner | SMTP | Often the only protocol it speaks |
| Per-environment credential rotation | REST | Bearer header swap |
| Network restricts port 587 or requires HTTPS egress | REST | Rides 443 |
| Need fine-grained structured errors | REST | JSON code field |
| High-volume bulk transactional from one worker | SMTP (pooled) | Amortizes handshake across sends |
| Test suite running on every commit | REST | Trivial to mock |
A reasonable default for new code is REST, with SMTP kept available for the systems you do not control. Most teams end up using both: REST from application code, SMTP from infrastructure that already had a mailer. The smtp vs rest api question is rarely either/or in production; it is a routing decision per workload.