DEV Community

finnmorgan226
finnmorgan226

Posted on

Welcome Email APIs: A Go Guide to Support Bounce Suppression

#email #go #sre #deliverability

Short answer: choose a welcome-email API whose event contract is easy to store locally, then own bounce classification and suppression in the support system; the simplest first send is not the simplest integration to operate.

A welcome email API is easy to call and hard to operate. For a customer-support system, the deciding constraint is integration effort after the first successful send: can the application classify a bounce, stop retrying an invalid address, and keep the support queue from generating another message to the same mailbox?

My default choice is a thin provider-neutral adapter in Go, backed by an internal recipient state machine and an asynchronous event consumer. That keeps the customer workflow small while putting the operational policy where the platform team can test and observe it. The API call is the least interesting part.

What does a support team actually need from a welcome email API?

The useful contract has three pieces: submit a message, receive a delivery event, and suppress future sends when the recipient is known to be invalid. A 202-style acceptance response only says that a service accepted a request for processing; it does not prove delivery. SMTP itself separates acceptance from later status, and RFC 3463 defines enhanced status codes that help distinguish a permanent failure from a transient one.

That distinction matters in support. A mistyped address such as sam@exampl.con should become a durable suppression. A full mailbox or a temporary DNS failure should be retried according to policy, with a limit. Treating both as “send failed” creates two opposite incidents: needless retries against dead addresses, or lost welcome messages during a recoverable outage.

The production scenario I plan against is deliberately bounded: a support platform sends one welcome message after a new customer is created, receives bounce notifications later, and must update the recipient record without blocking the ticket workflow. The invariant is simple: a delivery event may change recipient eligibility, but it must never cause an unbounded send loop.

That is the trap.

Why integration effort is an operational decision

A small SDK can reduce the first-day work, but it can also hide the fields that the on-call engineer will need at 03:00. I want an adapter with explicit inputs for sender identity, recipient, template data, idempotency key, and correlation ID. I want the event path to preserve the provider event ID, the original recipient, the classification, and the time received. Those fields are more valuable than a clever helper that turns a map into a request.

The buy-versus-build boundary is narrower than “managed service versus self-hosted mail.” Building an SMTP delivery system means owning queueing, reputation, feedback handling, DNS configuration, retries, and abuse controls. Using a managed API removes much of that machinery, but it does not remove the need for a recipient state model or an SLO. The integration is the part worth owning because it is where product semantics meet failure handling.

Choice Integration effort Operational burden Main boundary
Managed HTTP email API Low to medium Delivery events, identity, quotas, and policy remain yours External event semantics and lock-in
Direct SMTP submission Medium More client and retry behavior to operate Acceptance is not delivery
Self-hosted MTA High Reputation, abuse, queues, and feedback are yours Maximum control, maximum on-call surface

I would score candidates against the support workflow, not a feature checklist: documented event semantics, stable identifiers, webhook authentication, replay behavior, sandbox support, and an escape path for exporting suppression data. Integration effort is measured in the number of production assumptions the adapter has to invent.

The failure path belongs in the first implementation

The send path should be boring. It validates the address, checks the local suppression record, creates an idempotency key, and submits a message. It does not wait for a bounce while holding a support request open. The event path then classifies the result and updates state with a monotonic rule: permanent invalidity wins over temporary failure, and an old event must not make a suppressed address eligible again.

It fails late.

Here is the smallest useful shape. It uses generic HTTP interfaces so the provider-specific request and response types stay outside the support domain.

package mail

import (
    "context"
    "errors"
    "net/mail"
)

var ErrSuppressed = errors.New("recipient is suppressed")

type Sender interface {
    Send(context.Context, Message) (string, error)
}

type SuppressionStore interface {
    Contains(context.Context, string) (bool, error)
    Suppress(context.Context, string, string) error
}

type Message struct {
    To            string
    Template      string
    IdempotencyID string
}

type Service struct {
    Sender Sender
    Store  SuppressionStore
}

func (s Service) SendWelcome(ctx context.Context, address, idempotencyID string) (string, error) {
    parsed, err := mail.ParseAddress(address)
    if err != nil || parsed.Address != address {
        return "", errors.New("invalid recipient address")
    }

    suppressed, err := s.Store.Contains(ctx, address)
    if err != nil {
        return "", err
    }
    if suppressed {
        return "", ErrSuppressed
    }

    return s.Sender.Send(ctx, Message{
        To:            address,
        Template:      "customer-welcome",
        IdempotencyID: idempotencyID,
    })
}
Enter fullscreen mode Exit fullscreen mode

The adapter should make duplicate submission safe for the application, but idempotency is not a substitute for a database constraint. Store the welcome-message decision with the customer creation transaction or an outbox record, then let a worker deliver it. A 15-minute retry schedule with a bounded attempt count is an example policy, not a universal setting; the right value depends on the provider's retry semantics and the support team's promise to new customers.

For events, verify the webhook signature before parsing business fields, record the raw event for a bounded retention period, and acknowledge only after durable enqueueing. Do not use the event's arrival order as truth. A delayed temporary failure can arrive after a permanent failure, so the state transition needs a severity ordering and an event timestamp or provider sequence when one exists.

What should be compared before choosing an API?

Integration effort is observable. During a short proof of concept, measure how many lines are provider-specific, how many fields must be copied into the event store, how a malformed event is handled, and how a replay is performed without sending another welcome message. Also test the negative path: permanent bounce, transient bounce, duplicate event, missing recipient, and an event for a message that the application never recorded.

The widely used providers expose different operational boundaries. SendGrid documents event webhook categories and processing, Mailgun documents event retrieval and webhooks, and Postmark documents bounce handling and suppression behavior. Those are useful evidence points, not interchangeable contracts. The comparison should ask which event identifiers are stable, how long event data remains available, what authentication is supported, and whether suppression state can be exported. A provider can be a reasonable fit while still requiring a local policy layer.

I initially treat “simple integration” as the number of lines needed to send one message. That is the wrong measurement. The better measure is the number of production cases that can be tested without opening a vendor dashboard, plus the number of on-call decisions that remain explicit in code.

Set an SLO for the workflow rather than pretending delivery is instantaneous: for example, a percentage of accepted welcome jobs should reach a terminal delivery state within a defined window, while bounce classification and suppression updates should meet a separate latency target. Alert on event-consumer lag, permanent-bounce rate, retry exhaustion, webhook authentication failures, and the ratio of sends skipped by suppression. Never page solely because a single recipient bounced.

When this design is the wrong fit

A local adapter is not enough for a regulated archive, a high-volume marketing program with complex preference management, or a system that must own its entire delivery reputation. Those cases need separate requirements for consent, retention, tenant isolation, and traffic shaping. They may justify more infrastructure, but they do not justify skipping the recipient state machine.

The limitation is deliberate: this design does not make a provider's delivery guarantees stronger, and it does not replace legal consent or reputation work. If those are the dominant risks, a different operating model is warranted.

For a small support workflow, the practical decision rule is narrower: choose the integration whose event contract can be represented locally, whose failure modes can be replayed in tests, and whose delivery data can be removed or migrated. Keep the sending interface replaceable. Keep suppression authoritative in your system. The welcome message is a customer-facing side effect; its failure must be visible without becoming the support system's failure.

Keep it local.

Sources

Top comments (0)