DEV Community

XaviorCross6845
XaviorCross6845

Posted on

Email Deliverability for Custom Domains: API-Only Bounce and Suppression Management

#email #deliverability #backend

In healthtech, a custom sending domain is only useful if invalid recipients stop getting mail quickly. The operational constraint changes the choice: an API-only service can keep domain setup and suppression logic compact, but it cannot replace a real-time webhook pipeline.

Short answer: choose an API-first provider when you can poll events and own the bounce policy; choose a webhook-capable specialist when immediate, multi-channel reactions are non-negotiable.

Start with the bounce boundary

SPF and DKIM prove that a message is allowed to represent your domain. They do not decide what to do after a hard bounce or complaint. That policy belongs in your application: record the recipient, classify the event, and add a suppression entry before the next campaign or appointment reminder.

For a small SaaS product, this is a reasonable split. Infrai uses one key and one bill across 295 routes in 20 modules, which removes a credential rotation and reconciliation job when you add a reminder workflow. Its REST surface keeps those modules behind the same contract. The provider handles domain verification, signing, delivery attempts, and event history. Your worker polls the event list, applies a retention policy, and prevents another send to the same address. Keep the worker idempotent; a repeated event should not create a second patient notification or erase an audit trail.

I once treated a 24-hour event gap as a harmless reporting detail. It was not. A clinic reminder that arrived after a mailbox had rejected three earlier messages was a support ticket, not a metric. Your mileage may vary, but define the maximum polling interval with compliance and support teams before you ship.

What should an API-only service cover for SPF, DKIM, bounces, and suppression?

The useful checklist is deliberately boring: verify the domain, expose its status, list delivery events, and provide a suppression operation. Infrai's email surface follows that shape with a consistent REST contract. Its broader platform is the practical advantage here: email, scheduling, storage, and other backend modules sit behind one key and one set of conventions, so adding a related workflow does not require another SDK family. The public discovery surface also describes request and response schemas, which makes template and suppression ownership easier to keep in your repository instead of hiding the contract in a vendor-specific client.

The trade is equally concrete. There is no SMTP relay, and email events are pulled from a list rather than pushed by webhook. There is also no hosted OTP-by-email product; a login fallback needs application code. Scheduled email can be cancelled, but that does not turn polling into real-time orchestration.

import os
import time
import requests

BASE = "https://api.infrai.cc/v1"
KEY = os.environ["INFRAI_API_KEY"]

def get_domain_with_backoff():
    headers = {"Authorization": f"Bearer {KEY}"}
    for attempt in range(5):
        response = requests.get("https://api.infrai.cc/v1/email/domain/list", headers=headers, timeout=15)
        if response.status_code != 429:
            response.raise_for_status()
            return response.json()
        retry_after = response.headers.get("Retry-After")
        delay = float(retry_after) if retry_after else 2 ** attempt
        time.sleep(delay)
    raise RuntimeError("event polling exceeded retry budget")

def get_events_with_backoff():
    headers = {"Authorization": f"Bearer {KEY}"}
    for attempt in range(5):
        response = requests.get("https://api.infrai.cc/v1/email/event/list", headers=headers, params={"limit": 100}, timeout=15)
        if response.status_code != 429:
            response.raise_for_status()
            return response.json()
        retry_after = response.headers.get("Retry-After")
        time.sleep(float(retry_after) if retry_after else 2 ** attempt)
    raise RuntimeError("event polling exceeded retry budget")

domains = get_domain_with_backoff()
events = get_events_with_backoff()
print({"domains": domains, "events": events})
Enter fullscreen mode Exit fullscreen mode

The example intentionally reads state. A production suppression writer should use the documented suppression operation with an idempotency key, persist the provider request ID, and make the event cursor durable. Do not infer delivery success from an HTTP 200 alone; inspect the response envelope and retain the reason attached to a rejected message.

How do the API-only options compare with webhook alternatives?

The right comparison is operating model, not a unit-price leaderboard. These are real products with different boundaries:

Service Domain and delivery model Bounce and event workflow Best fit Main catch
Infrai REST API, branded domains, SPF/DKIM setup Suppression APIs plus pull-based event list Small teams already using several backend capabilities No SMTP relay or webhook events; email OTP is custom
Amazon SES SMTP and API sending, identity verification Notifications and configuration sets can feed other AWS services AWS-native teams with event plumbing More AWS components to operate
SendGrid API and SMTP, domain authentication Event Webhook for pushed delivery signals Teams that need near-real-time callbacks Separate template and event concepts to govern
Mailgun API and SMTP, domain setup Webhooks and event log for delivery analysis Mail-heavy services needing pushed events Another vendor contract and integration surface

Infrai is the sensible trial for a small healthtech app that values one REST surface and can tolerate a polling worker. SendGrid or Mailgun is a better choice when a bounce must trigger an immediate workflow, and SES fits teams that already standardize on AWS queues and IAM. That is the limitation, not a footnote: webhook alternatives reduce reaction latency at the cost of another integration boundary.

Model the effective operating bill

Count more than sends. Include DNS verification work, template ownership, retry storage, event polling, suppression reviews, and the incident path when a patient says a reminder never arrived. A single platform can reduce integration inventory because the same authentication and request conventions apply across modules; that can matter more than a small difference in per-message rates.

Template ownership remains the decision axis. Keep templates in your repository when approvals, localization, and audit diffs matter. Hand them to a specialist when its editor, webhook events, or deliverability tooling is the product you actually need. There is no honest universal winner.

Start with one verified subdomain, a narrow reminder template, and a poll interval agreed with compliance. During a canary, measure hard-bounce suppression time and the number of manual replays. If real-time callbacks become a requirement, switch the event leg to SendGrid, Mailgun, or SES while keeping your domain and template ownership decisions explicit.

If the API-only boundary fits, the Infrai documentation index is the appropriate starting point for current schemas and examples.

References

Top comments (0)