Email API vs SMTP: a 30-second decision table and the same receipt sent both ways

SMTP is the step-by-step conversation mail servers use to pass a message along. An email API takes the same message as one HTTPS request. Find your situation below; if two rows match, the API wins unless the sending code is not yours to change. Sentences that start “Rasket:” are about our service; the rest hold for any provider.

For the agent row, the MCP article covers keeping the key out of the model’s reach and putting a person in front of each send.

On the same provider, inbox placement does not depend on the choice: the receiving server gets the same signed message either way. If mail lands in spam, open a delivered copy’s Authentication-Results header (RFC 8601) and look for dkim=pass and dmarc=pass before changing anything else. DKIM, SPF and DMARC explained says what each result means, and the spam guide covers the rest.

One receipt, sent over the API and then over SMTP, in Python with only the standard library. Every output is from a run on 17 October 2026 against a local build of Rasket’s API and relay. Founders can skip to moving from SMTP to the API. For Node, the rate limits article has the same send with fetch and backoff, and the SMTP relay article has Nodemailer settings.

import http.client, json, os, time, urllib.error, urllib.request

API = os.environ.get("RASKET_API_URL", "https://api.rasket.com")
KEY = os.environ["RASKET_API_KEY"]
RETRY = {"rate_limit_exceeded", "concurrent_idempotent_requests"}

body = {
    "from": "Acme <billing@acme.example>",
    "to": ["jordan@example.com"],
    "subject": "Your receipt for order A-2291",
    "text": "Thanks for your order.",
}
request = urllib.request.Request(
    f"{API}/emails",
    data=json.dumps(body).encode(),
    method="POST",
    headers={
        "Authorization": f"Bearer {KEY}",
        "Content-Type": "application/json",
        "User-Agent": "acme-billing/1.0",
        "Idempotency-Key": "receipt-a2291",  # the same on every attempt
    },
)
for attempt in range(1, 4):
    try:
        with urllib.request.urlopen(request, timeout=30) as response:
            print(response.status, json.loads(response.read()))
        break
    except urllib.error.HTTPError as error:  # an answer, and it is a refusal
        try:
            problem = json.loads(error.read())  # {"statusCode", "name", "message"}
        except ValueError:
            problem = {}  # a proxy's HTML error page
        # A quota 429 or a 4xx gets the same answer again, so only these are retried.
        if attempt == 3 or not (error.code >= 500 or problem.get("name") in RETRY):
            raise SystemExit(f"{error.code} {problem or error.reason}")
        wait = error.headers.get("retry-after", "")
        time.sleep(min(int(wait), 60) if wait.isdigit() else 2**attempt)
    except (OSError, http.client.HTTPException):  # no answer: it may have been sent
        if attempt == 3:
            raise
        time.sleep(2**attempt)  # the same key makes this retry safe

200 {'id': '01a14bbe-6c34-7e1f-ab72-58fa5b6e5ccc'}
200 {'id': '01a14bbe-6c34-7e1f-ab72-58fa5b6e5ccc'}

The second run is a replay: same key, same id, no second email, and the response carries idempotent-replayed: true. A refusal comes back as a JSON body with a name to branch on. With the recipient changed to jordan@example, the script stopped at once:

422 {'statusCode': 422, 'name': 'invalid_parameter', 'message': 'to[0]: to contains an invalid email address: jordan@example'}

The loop retries a 5xx, rate_limit_exceeded (waiting for its retry-after), concurrent_idempotent_requests (an attempt with the same key still running), and a request that got no answer. Everything else would get the same answer again: a 4xx, and a quota 429 such as daily_quota_exceeded or monthly_quota_exceeded. The rate limits article adds jitter and a time budget.

import os, smtplib, ssl
from email import policy
from email.message import EmailMessage
from email.utils import formatdate, make_msgid

HOST = os.environ.get("RASKET_SMTP_HOST", "smtp.rasket.com")
PORT = int(os.environ.get("RASKET_SMTP_PORT", "587"))

msg = EmailMessage()
msg["From"] = "Acme <billing@acme.example>"
msg["To"] = "jordan@example.com"
msg["Subject"] = "Your receipt for order A-2291"
msg["Date"] = formatdate()
msg["Message-ID"] = make_msgid(domain="acme.example")
msg["X-Rasket-Idempotency-Key"] = "receipt-a2291"
msg.set_content("Thanks for your order.")

def expect(step, reply, ok):
    code, text = reply
    if code not in ok:  # a 4xx may pass later; a 5xx will fail again
        raise SystemExit(f"{step} refused: {code} {text.decode()}")
    return text.decode()

with smtplib.SMTP(HOST, PORT, timeout=30) as smtp:  # reads the 220 greeting
    smtp.starttls(context=ssl.create_default_context())  # sends EHLO, then STARTTLS
    smtp.login("rasket", os.environ["RASKET_API_KEY"])  # EHLO again, then AUTH
    # send_message() would hide the final reply, so take the steps and check each one.
    expect("MAIL FROM", smtp.mail("billing@acme.example"), {250})
    expect("RCPT TO", smtp.rcpt(msg["To"]), {250, 251})  # syntax and recipient cap
    # data() raises SMTPDataError if DATA itself is refused, and returns the reply
    # after the dot: suppression, domain and content refusals come back there.
    reply = smtp.data(msg.as_bytes(policy=policy.SMTP))  # CRLF line ends (RFC 5321)
    print(250, expect("DATA", reply, {250}))

250 2.0.0 Queued as 01a14bbe-6f09-74ee-b9cf-9d061911e1ca
250 2.0.0 Queued as 01a14bbe-6f09-74ee-b9cf-9d061911e1ca

Both samples use receipt-a2291. Run them one after the other and the SMTP one stops at DATA refused: 554 5.6.0 This Idempotency-Key was already used with a different payload, a reply the SMTP docs list. The relay builds its own request body from your message, so the API sees the key reused for a different email. One key cannot fail over between the API and SMTP, so send each message one way. Over SMTP alone the key does its job: if the connection drops after the dot, send again, and the second run above shows the same id coming back.

Count the exchanges in the SMTP session. After the server’s greeting the client takes eight turns with AUTH PLAIN (more with AUTH LOGIN): EHLO, STARTTLS, EHLO again inside TLS, AUTH, MAIL FROM, RCPT TO, DATA (answered 354), then the message and its final dot (answered 250). The API takes one request. A server that offers PIPELINING (RFC 2920) lets a client send several commands without waiting, and one connection can carry many messages, so at a few emails a minute speed will not decide this.

What comes back matters more. An SMTP reply is usually one line (RFC 5321 §4.2.1 allows several): a code, a finer status such as 5.7.8, and some text. Where a refusal shows up depends on the cause. With the recipient changed to jordan@example, the sample stopped at RCPT TO refused: 553 5.1.3 Bad recipient address syntax. Suppression, domain and content refusals come only after the final dot. Rasket’s relay puts the message id in the last reply’s text, and your code only sees it if the library hands the reply over. The API answers with a JSON body.

Many comparisons put suppression lists and webhooks in the API column. They belong to whoever runs the server. A bare relay you run yourself has none. A provider’s relay can have all of them.

The retry row is the one that bites. If the connection drops after your final dot and before the server answers, you cannot tell whether it took the message. RFC 5321 §6.1 names this duplicate-message problem and only asks the server to answer quickly, so a mailer that resends can deliver twice.

Port 25 is the one that gets blocked. Mail servers use it to deliver to each other (RFC 5321 §4.5.4.2), and it is where a hijacked machine sends spam, so many hosting and access providers block it outbound (RFC 5068 §4 describes the practice). Google Cloud, for example, blocks port 25 to outside addresses by default and places no restriction on 465 or 587.

Applications use SMTP submission instead, on 587 (RFC 6409) or on 465 with TLS from the first byte (RFC 8314), and RFC 5068 §4.1 says access providers must not block 587. Some locked-down networks still block both, so test from where the code will run:

import os, smtplib, ssl, urllib.error, urllib.request

HOST = os.environ.get("RASKET_SMTP_HOST", "smtp.rasket.com")
API = os.environ.get("RASKET_API_URL", "https://api.rasket.com")
tls = ssl.create_default_context()

def implicit_tls():
    with smtplib.SMTP_SSL(HOST, 465, context=tls, timeout=10) as smtp:
        return smtp.ehlo()[0]

def starttls():
    with smtplib.SMTP(HOST, 587, timeout=10) as smtp:
        return smtp.starttls(context=tls)[0]

def https():
    try:
        with urllib.request.urlopen(f"{API}/emails", timeout=10) as response:
            return response.status
    except urllib.error.HTTPError as error:
        return error.code  # 401 without a key still proves the port is open

for name, check in [("465 implicit TLS", implicit_tls), ("587 STARTTLS", starttls), ("443 HTTPS", https)]:
    try:
        print(name, "reachable:", check())
    except OSError as error:  # a timeout usually means the network blocks the port
        print(name, "failed:", type(error).__name__)

465 implicit TLS reachable: 250
587 STARTTLS reachable: 220
443 HTTPS reachable: 401

The SMTP guide explains how STARTTLS on 587 differs from TLS on 465. The SMTP relay article covers which one to pick, the alternates for blocked networks, and every reply code.

The relay at smtp.rasket.com turns each message into one POST /emails. The password is an API key, so give each tool its own sending-access key, restricted to one domain. A relayed message shares the API’s rate limit and allowance, and gets the same message id, events and suppression checks an API send gets. The relay ignores your MAIL FROM for routing, because the return path is set by your domain, but uses it with the Message-ID and the recipients to derive an idempotency key when you send no X-Rasket-Idempotency-Key header. That only catches a resend that keeps the same Message-ID, so set the header if your app rebuilds the message on retry. Settings, limits and reply codes are in the SMTP relay article.

The fields keep their names: From: becomes from, To: becomes to, the text and HTML parts become text and html. What changes is the call that carries them.

1. Find the one helper that opens the SMTP transport, and swap its body for one HTTP call with the same signature. Every caller moves untouched, and a later change of provider touches this one function.
2. Store the returned id on the record that caused the send, such as the order row, and derive the idempotency key from that record, as in receipt-a2291.
3. Move your bounce handling into a webhook handler. If your old setup hands you bounces as emails to parse, as a bare relay does, they now arrive as events with the id attached; the webhooks article has a receiver.
4. Run both paths for a week on one low-stakes message type. Look up each API send with GET /emails/{id} (a full-access key), and compare it with what your old provider’s logs show for the SMTP copy.

• Mail that never leaves your network. Alerts between internal systems can go through the relay you already run. There is no outside reputation to protect.
• Signed or encrypted mail. Rasket’s relay refuses S/MIME and PGP because it rebuilds the message, and the API takes fields, not a finished message. You need a mail server that passes your bytes on unchanged.
• A device with no TLS or no login. Rasket’s relay requires both. Run Postfix on your own network to accept mail from the device and log in upstream with a key. If the device’s From address is not on your verified domain, rewrite it with sender_canonical_maps.

For that local relay, two settings matter. mynetworks is the list of client addresses Postfix relays for without a login, so list the device and nothing else; a wider range makes an open relay, which RFC 5068 §3.2 says a submission server must never be. And smtp_tls_security_level = secure checks the upstream certificate, so the key cannot be read by someone in the middle.

# /etc/postfix/main.cf on a machine on the device's network
inet_interfaces = all
# the device, and nothing else (Postfix reads # only at the start of a line)
mynetworks = 127.0.0.0/8, 192.168.1.40/32
relayhost = [smtp.rasket.com]:587
# secure = require TLS and check the certificate; encrypt would not check it
smtp_tls_security_level = secure
smtp_tls_CAfile = /etc/ssl/certs/ca-certificates.crt
smtp_sasl_auth_enable = yes
smtp_sasl_tls_security_options = noanonymous
# hash: on Debian and Ubuntu; use a map type that postconf -m lists
smtp_sasl_password_maps = hash:/etc/postfix/sasl_passwd

# /etc/postfix/sasl_passwd, then: postmap /etc/postfix/sasl_passwd
# and chmod 600 both sasl_passwd and the sasl_passwd.db it creates
[smtp.rasket.com]:587 rasket:<a sending-only API key>