Email API for SaaS products and event-driven workflows

Why Email API earns its place

The case for an Email API is not "HTTP is better than SMTP." It is "our product has absorbed email." When a SaaS product sends a password reset, it does not want to hand the message to a transport layer and forget about it. It wants to know that the message was accepted, it wants to know when the user opened it, it wants to correlate that event with the authentication flow that triggered it, and it wants the tenant boundary to be visible throughout. That is a data model, not a protocol choice.

Once a product is in that state, SMTP starts feeling like a compatibility shim. The send call returns a three-digit status code and nothing else. Events about the message arrive via a separate pipeline that has to be bolted on. Metadata about the tenant and trigger gets encoded into custom headers that each provider parses differently. Idempotency is the application's problem, not the transport's. Each of those gaps is solvable over SMTP, but solving them means reimplementing what a modern Email API already provides as part of the contract.

The alternative framing — the one that keeps the decision honest — is workload-first. Look at how your product already behaves and ask which transport fits that shape. Products that send "fire and forget" messages tied to low-level operational events (an admin alert, a cron job notification) are happy over SMTP. Products that treat email as part of the user experience (a welcome flow, an onboarding sequence, a usage alert that drives in-app state) want the API. The answer is usually obvious once the question is framed that way.

What "event-driven" means for email in practice

The phrase "event-driven" gets overused, so it is worth defining. In the context of a SaaS product that sends email, event-driven means four things, and all four tend to travel together:

Each pillar is individually trivial to approximate over SMTP. Together, they add up to a substantial amount of glue code that the Email API absorbs as part of its contract. The fourth pillar in particular — the closed loop from send to downstream event — is the one that most often tips the architectural decision toward the API. For the deeper treatment of how to design transactional workflows around application events rather than protocol mechanics, see designing transactional email workflows around application events.

The provider landscape in late 2022

The Email API market has stabilized over the last five years into a small set of serious options, each with a different position. The table below is a working summary of what we have seen teams choose and why, as of late 2022.

Two observations about the table. First, the market has consolidated under a few strategic acquirers — Twilio absorbed SendGrid in 2019, Sinch absorbed Mailgun and Mailjet in 2021, MessageBird absorbed SparkPost in 2021, ActiveCampaign absorbed Postmark in 2022. The "independent Email API startup" is less common than it was five years ago. Second, the right provider depends on the shape of the workload, not the brand of the provider. A team picking SendGrid because "everyone uses SendGrid" is doing worse analysis than a team picking Postmark because their transactional latency SLA demands it.

Core capabilities that justify the integration cost

Moving from SMTP relay to an Email API is not free. Application code changes; templates move from the app to the provider; webhook infrastructure has to be built; monitoring changes. The question is whether the capabilities justify that cost. The honest answer is: for some workloads yes, for others no. The table below is the short version.

Every row marked "yes" is a concrete thing the API does that SMTP does not, and a product that needs that thing will either build it themselves on top of SMTP or pay the API provider to include it. For two or three of the "yes" rows, the API path wins on total cost. For none of them, SMTP is still the correct tool. For the specific case of account lifecycle messaging — signup, activation, onboarding, password — where the API pattern most naturally applies, see building reliable API-based email for account lifecycle messaging.

Multi-tenant SaaS: the hardest part

Every mature Email API has a multi-tenant story, and every multi-tenant story looks slightly different, and every one of those differences shows up in your integration code. This is the single most important detail to get right before committing to a provider.

The three tenancy models providers offer

What "per-tenant suppression" really means

A recipient who unsubscribes from tenant A should not be suppressed for tenant B. A hard bounce from tenant A's list should not affect tenant B's deliverability. A complaint about tenant A's message should not reduce tenant B's sender reputation. Each of those is a design choice, and providers handle them differently. The pattern we see work best is:

1. Global suppression for abuse signals. A hard bounce at the address level (user@example.com does not exist) is suppressed globally, because the address is the problem, not the tenant.
2. Per-tenant suppression for preference signals. An unsubscribe or complaint from a specific tenant's sending applies only to that tenant, because the recipient's preference is tenant-specific.
3. Per-tenant reputation isolation where the volume justifies it. Small tenants share the platform's reputation; large tenants earn dedicated IPs and per-IP reputation curves.
4. Per-tenant event streams. Webhooks include the tenant identifier so the application can route events back to the right customer's analytics surface.
5. Per-tenant rate limits. One tenant's spike in traffic should not drain the account-level throughput budget for everyone else.

A concrete request, from app to API

What an Email API request actually looks like, in the shape most providers have converged on. The code below is illustrative — the exact field names differ per provider, but the shape is consistent across all the serious ones.

pythonimport httpx, os, uuid

API = "https://api.authorizehosting.com/v1/send"
KEY = os.environ["AHK_API_KEY"]

def send_password_reset(tenant_id, user_id, to_addr, first_name, reset_link):
    payload = {
        "from":    { "email": "notify@app.example.com", "name": "Example App" },
        "to":      [{ "email": to_addr }],
        "template_id": "pwd_reset_v3",
        "variables": {
            "first_name": first_name,
            "reset_link": reset_link
        },
        "metadata": {
            "tenant_id": tenant_id,
            "user_id":   user_id,
            "flow":      "auth.reset",
            "app_event_id": str(uuid.uuid4())
        },
        "tags": ["transactional", "auth", f"tenant:{tenant_id}"],
        "stream": "transactional",
        "idempotency_key": f"reset-{tenant_id}-{user_id}-{int(time.time() // 60)}"
    }
    r = httpx.post(API,
                   json=payload,
                   headers={"Authorization": f"Bearer {KEY}"},
                   timeout=10.0)
    r.raise_for_status()
    response = r.json()
    # Response: { "message_id": "msg_abc123", "accepted": true }
    # We persist message_id so webhooks later can correlate events to this send.
    store_outbound_event(
        tenant_id=tenant_id,
        user_id=user_id,
        message_id=response["message_id"],
        flow="auth.reset"
    )
    return response["message_id"]

Three details worth commenting. First, the metadata field is where the tenant identifier lives; it travels with the message into every webhook event, letting the application correlate downstream events to the tenant that generated them. Second, the idempotency_key is constructed to be stable across retries of the same logical operation — same tenant, same user, same minute bucket produces the same key, so a retried call does not duplicate the message. Third, the stream field tells the provider this is transactional rather than marketing, which scopes the sending identity and reputation pool on the provider side.

What the application does not do in this code is equally important. It does not compose MIME. It does not build the HTML body. It does not sign the message. It does not handle bounces inline. All of that lives at the provider. The application is describing what it wants sent, not how to send it.

Webhooks: idempotency and signature verification

An Email API's webhook endpoint is the reverse direction of the contract: the provider pushes events to your application as they happen. Done well, webhooks are the cleanest possible way to surface email state in a product. Done poorly, they are the source of duplicate database records, inconsistent analytics and mysterious support tickets about password resets arriving twice.

The three non-negotiables

pythonimport hmac, hashlib
from flask import request, abort

WEBHOOK_SECRET = os.environ["AHK_WEBHOOK_SECRET"]

@app.route("/webhooks/email", methods=["POST"])
def email_webhook():
    # 1. Verify signature BEFORE reading any payload field
    signature = request.headers.get("X-AHK-Signature", "")
    body = request.get_data()
    expected = hmac.new(
        WEBHOOK_SECRET.encode(),
        body,
        hashlib.sha256
    ).hexdigest()
    if not hmac.compare_digest(signature, expected):
        abort(401)

    # 2. Parse payload after signature is verified
    event = request.get_json()
    event_id = event["event_id"]

    # 3. Deduplicate by event_id — insert first, process second
    if db.webhook_events.exists(event_id):
        return ("", 200)  # already processed; acknowledge and return
    db.webhook_events.insert(event_id, event["type"], event["payload"])

    # 4. Acknowledge fast; enqueue the actual work
    enqueue_webhook_processing.delay(event_id)
    return ("", 200)

The pattern above is boring and battle-tested. The temptation to cut corners — skip signature verification during development, process inline "because the volume is small," accept duplicates because deduplication feels like overkill — is how production incidents begin. The right approach is to implement the full pattern on day one and never touch it again.

Stream separation inside a single API account

Even within a single Email API account, your product usually has multiple sending streams that should not share reputation. Password resets and marketing newsletters both go out as "transactional" in some sense, but inbox providers treat them differently, and your sending posture should too. Most serious Email API providers offer stream separation as a first-class feature; some call it "message streams," some call it "subaccounts," some call it "IP pools." The shape is the same.

• Transactional stream. Password resets, receipts, 2FA codes, alerts. Highest reputation priority. Dedicated IP pool or a clearly-separated shared pool. Aggressive bounce suppression. No open/click tracking that adds pixels (which can correlate with marketing signatures).
• Lifecycle stream. Onboarding sequences, trial reminders, product update digests. High priority. Shared pool with controlled reputation. Open and click tracking appropriate.
• Marketing / broadcast stream. Newsletters, campaigns, promotional sends. Separate pool entirely. Complaint rate monitoring aggressive; the reputation cost of marketing mistakes should not leak into transactional.

The provider-side configuration is straightforward. The application-side discipline is harder: every outgoing message has to pick the right stream, and getting that wrong conflates the reputations you carefully separated. A common pattern is to add stream selection into the template itself — the pwd_reset_v3 template is tagged as stream=transactional on the provider side, and the application never has to specify it at send time. For teams whose sending includes cold outreach as a parallel stream — which creates its own set of isolation requirements — domain separation for cold email teams is the companion read.

Authentication posture with a provider in the loop

Using an Email API does not exempt the sender from SPF, DKIM and DMARC. It moves responsibility around. The provider signs DKIM on your behalf, publishes the SPF include record you add to your domain, and typically handles the DMARC reporting pipe if you want them to. Your domain owner still has to publish the right records.

DNS# SPF — authorize the provider's sending infrastructure
app.example.com.  IN  TXT  "v=spf1 include:spf.authorizehosting.com -all"

# DKIM — CNAMEs to the provider's signing infrastructure
ahk1._domainkey.app.example.com.  IN  CNAME  ahk1.dkim.authorizehosting.com.
ahk2._domainkey.app.example.com.  IN  CNAME  ahk2.dkim.authorizehosting.com.

# DMARC — start at monitoring, progress to enforcement
_dmarc.app.example.com.  IN  TXT  "v=DMARC1; p=none; rua=mailto:dmarc@example.com; fo=1"

Two details deserve attention. First, the CNAME-based DKIM pattern is the modern default — it lets the provider rotate keys without requiring DNS changes on your side. Second, the DMARC policy should progress from p=none (monitoring) through p=quarantine (soft enforcement) to p=reject (full enforcement) as you confirm that every legitimate source of mail from the domain is aligned. Jumping to p=reject on day one, especially with legacy applications still in the mix, breaks things invisibly.

BIMI adds another dimension for 2022. Once your DMARC is at p=quarantine or p=reject, you can publish a BIMI record that lets supporting mailbox clients display your brand logo next to authenticated messages. Gmail rolled out BIMI support in mid-2021; the ecosystem has been growing steadily since. For product teams that care about brand recognition in the inbox, BIMI is worth the setup cost once the authentication foundation is in place.

When SMTP relay remains the better answer

A lot of the Email API positioning you read online implies that SMTP is obsolete. That framing is convenient for vendors but wrong for most real programs. SMTP relay remains the better answer in several specific situations.

1. Third-party applications you did not write. Billing systems, ERP suites, help desks, monitoring agents. These speak SMTP natively and will not be rewritten. An API integration is not an option; a relay is the only practical path.
2. Internal tools that send occasional operational mail. Cron jobs, nightly reports, backup-status notifications. The product does not care about open rates on these. SMTP is cleaner.
3. Low-volume single-stream sending. A small SaaS that sends 5,000 password resets a month does not need the complexity of an API integration. A relay with proper authentication is enough and cheaper to maintain.
4. Teams that explicitly want to minimize vendor lock-in. An SMTP relay can be swapped by changing credentials. An API integration is a code change. For teams that plan to migrate providers, relay gives optionality the API does not.

Most mature SaaS companies end up running both. The product itself sends through the Email API. Internal tools, legacy integrations and system alerts send through the SMTP relay. Both paths can authenticate against the same domain (with different DKIM selectors), and both share the benefits of the organization's authentication posture. The choice is per-workload, not per-company. For the deeper treatment of the comparison, see SMTP relay for billing systems and legacy applications.

Frequently asked questions

Can we use the same Email API for transactional and marketing?

Technically yes, in the sense that providers support both. Operationally, serious programs separate them at the stream or sub-account level, because the reputation dynamics are different. Mixing them in the same pool means a bad marketing campaign can affect your password-reset delivery, which is the wrong direction for reputation contamination.

How do we pick a provider?

Match your workload to the provider's shape. Transactional-only with strict latency requirements: Postmark. High-volume mixed transactional and marketing: SendGrid. AWS-native with engineering capacity to own more of the layer: SES. Developer-focused with granular routing needs: Mailgun. Evaluate on a test workload for two weeks before committing; the only comparison that matters is your own traffic.

What happens when the provider has an outage?

Transactional mail through any provider will sometimes be delayed or lost. A production-ready integration includes a dead-letter queue for sends that fail permanently, a retry policy with exponential backoff for transient failures, and either a secondary provider for failover or an explicit SLA relationship with the primary provider. Building this is part of the cost of API-based sending.

Should we use the provider's template system or our own?

Use the provider's template system when your marketing or product team needs to iterate without deploying. Use your own templates when your templates are complex, shared across channels (email plus push plus in-app), or tied to code deployments for regulatory reasons. Most teams start with the provider's templates and graduate to their own as templating needs grow.

How do we test webhook handling before we are live?

All the serious providers offer a webhook test endpoint or replay feature. Tunnel your local webhook endpoint to the internet with a tool like ngrok or Tailscale Funnel, point the provider at the tunneled URL, and trigger test events. Test the signature verification, the idempotency path, and the timeout handling before the first production send, not after.

What about inbound email?

Some Email APIs support inbound (receiving mail at a domain you configure, parsing it, and webhook-delivering the parsed content to your application). This is a separate capability from transactional sending; not every provider offers it, and the implementations differ substantially. Evaluate it independently from outbound when you need it.

Closing perspective

The Email API decision is not a modernization story. It is a workload-fit story. Products that have absorbed email into their data model — events, tenants, metadata, downstream state — benefit from the HTTP contract that the API provides. Products that still treat email as a side channel behind SMTP credentials are usually better off leaving that relationship alone and improving other things.

The teams that do this well tend to share a few habits. They start with a real workload audit rather than a vendor comparison. They design their tenancy model before they pick a provider, because providers differ more on tenancy than on raw sending capability. They implement webhook idempotency and signature verification on day one. They keep SMTP relay as the right tool for legacy and internal workloads, rather than forcing everything through the API because "modern means API." And they treat the Email API as part of their product's architecture, not as a vendor relationship.

The teams that do this poorly tend to pick the provider first, spend six months adapting their product to the provider's conventions, discover the tenancy model does not fit, and migrate eighteen months later to the provider that matches the workload they had all along. The cost of that migration is usually larger than the cost of getting the initial decision right.

The good news is that the Email API landscape has matured. The serious providers all handle the basics competently. The differentiation is at the edges — multi-tenant support, deliverability culture, event model, template system — and those edges are where the workload-fit analysis earns its keep. Take the analysis seriously and the provider choice becomes straightforward; skip it and the choice becomes expensive.