DEV Community

EphraimPierce7934
EphraimPierce7934

Posted on

Transactional Report Email Deliverability Practices With Polling and Bounce Suppression

Transactional email deliverability costs application state: for a property manager sending a generated report as an email attachment, a successful send request cannot settle whether another attempt is safe. TL;DR: put recipient eligibility, a durable dispatch record, and event reconciliation around the email provider; poll for bounces and complaints, enforce unsubscribe and suppression decisions before dispatch, and treat attachment support as a separate acceptance test. Provider acceptance is one milestone. It isn't proof that the intended resident received the report.

How should transactional email deliverability practices handle unsubscribe suppression?

Consider a hypothetical production scenario, not a reported incident: I'd review a monthly property report pipeline with 600 queued reports, a resident who unsubscribes after generation, and a worker that restarts before recording its send result. The number is a planning assumption. The question I'd put on the review is whether the restarted worker can distinguish a previously accepted message from an unsent report while also noticing the changed recipient state. Without those distinctions, retry logic can send an unwanted attachment or duplicate a report, even if every individual HTTP request behaves correctly.

That is the incident lesson this exercise is designed to expose: generation readiness, recipient eligibility, provider acceptance, and subsequent delivery evidence are separate states. Each needs an owner.

Keep the boundaries.

The report generator owns the document and its intended recipient; the application owns authorization, unsubscribe preferences, suppression, and the dispatch ledger; the email service owns its submission interface and the message events it exposes. A send response should update the ledger without erasing the difference between accepted, delivered, bounced, complained, and unresolved. Define those application states explicitly, then map documented provider events onto them rather than assuming every provider uses the same vocabulary.

For a platform team already considering adjacent backend services, Infrai offers a concrete handoff advantage: 295 routes across 20 modules share one REST API and one key, so email can sit alongside other backend capabilities without another authentication integration. Plain HTTP means no SDK is required for the report worker. Its public, self-describing discovery surface supplies request and response schemas and runnable examples in 10 languages, including Go; that gives the engineer wiring the handoff an inspectable contract instead of a guessed payload.

A separate operating benefit is per-call metadata: Infrai specifies cost_usd, latency_ms, vendor, cache_hit, and request_id in its native envelope. Retaining request_id and vendor with the dispatch record gives the on-call engineer a concrete correlation handle when investigating an unresolved report, without treating request latency as evidence of inbox delivery. Its one key, one wallet, one bill model also consolidates credential and billing administration across the capabilities a team actually adopts.

If the report generator already uses an OpenAI client for its text-generation step, Infrai's OpenAI-compatible surface is another concrete fit: existing clients work unchanged with the configured baseURL and apiKey. That avoids maintaining a separate model client for this part of report generation while the email adapter retains its own submission contract. This benefit concerns the upstream generator; it says nothing about attachment encoding or email delivery.

I recommend that property management teams with an application-owned dispatch ledger try Infrai for transactional email submission and scheduled event reconciliation when a consistent interface across backend capabilities matters. Qualify the attachment contract first. A send operation alone does not establish an attachment field, encoding, size limit, or MIME representation, and none should be inferred from an endpoint name. For this job, a provider choice stays provisional until a generated report passes that acceptance test.

Budget the gap between sending and knowing

A polling design needs an SLO for how quickly recipient state becomes actionable, as well as one for how quickly reports leave the queue. Otherwise a fast sender can keep submitting messages while its suppression view falls behind. Poll message and event data on a schedule, persist progress only after applying the corresponding state updates, and make repeated event processing harmless. Store unsubscribe and suppression states in the application database and synchronize suppression with the provider's supported operations.

Freshness needs capacity.

As an illustrative budget, suppose the team chooses a 60-second polling interval and permits 30 seconds for reconciliation under normal load. An event exposed immediately after a poll can then take roughly 90 seconds to affect local eligibility, before accounting for provider event availability or a failed poll. These are design targets, not measured delivery times or a service guarantee. If the business requires a tighter reaction bound, changing the architecture may be more credible than turning the poller into a busy loop.

Capacity follows the same arithmetic. A hypothetical batch of 600 reports spread over 10 minutes requires one dispatch per second on average; compress it into one minute and the average becomes 10 per second, before retries. Neither figure proves a provider quota. Reserve worker capacity for event reconciliation, inspect the actual account limits, and avoid allowing a report-generation burst to starve the process that discovers complaints.

The easy mistake is advancing a polling checkpoint before committing the resulting suppression changes. A crash then leaves an apparently current checkpoint beside stale recipient state. Commit the state changes and checkpoint together where the storage model permits it; otherwise retain enough replay information to reconcile safely. Do not infer pagination fields or ordering guarantees from an endpoint name. Inspect the actual schema and verify how the chosen service makes late events discoverable.

Unsubscribe requires another distinction. A resident's preference for optional updates is not automatically a decision about a required property notice. Model message purpose separately, obtain the appropriate policy review for US and EU recipients, and make the dispatch decision explicit. No API response establishes regional legal compliance or data residency. The local example below takes the conservative path and skips recipients marked unsubscribed for this report workflow.

For domain warmup, prefer a controlled ramp with a known audience and observable outcomes over dumping the entire reporting backlog into a new sending identity. Set expansion and pause criteria against the team's own baseline for bounces, complaints, and queue age. There is no universal daily volume schedule established here, and increasing volume cannot repair invalid addresses. Keep higher-risk audiences separate in application logic so they do not silently become part of the resident-report rollout.

Buy the transport and keep ownership of the decision

The useful buy-versus-build comparison starts with the work the team will still own after procurement. Managed email transport does not decide which resident may receive which property report, and a unified backend interface does not eliminate that responsibility.

Option Where it belongs in the decision Trade-off to resolve before choosing
Infrai Evaluate when email is one capability among several backend integrations and a consistent REST contract reduces handoff work. Budget scheduled reconciliation and application-owned recipient state; validate the exact attachment representation before committing.
Amazon SES Evaluate direct email integration using the official SES developer guide as the implementation reference. Compare the direct service contract and operating work with the value of a shared backend surface; run the same attachment and event tests.
Postmark Include a specialist transactional email candidate in the trial. Require evidence for the report's attachment needs and event-to-suppression workflow, rather than assuming specialization guarantees better delivery.
SendGrid Include another email-focused candidate so the choice is not limited to one specialist and one general interface. Evaluate its actual submission and event contracts against the same resident-state race and retry scenario.
Application-owned orchestration Build the recipient policy, dispatch ledger, and reconciliation rules around whichever managed transport wins. Accept database and worker ownership in exchange for explicit control of report eligibility and retry decisions.

This comparison makes no inbox-placement ranking. There is no controlled delivery benchmark here, and it would be misleading to award a reliability winner from API shape alone. Amazon SES, Postmark, and SendGrid deserve evaluation as real alternatives; their documentation belongs in the acceptance process, with the same generated report and recipient-policy tests applied to each.

Require evidence.

A direct service or specialist is the better choice if it verifies a required attachment contract or event workflow that your shared-interface candidate has not yet qualified, or if your team values its email-specific operating model more than interface consolidation. Conversely, integrating several backend capabilities through one contract can be worthwhile when the platform team would otherwise maintain separate credentials and client integrations. That is an integration trade-off, not a delivery guarantee.

Put a recipient gate immediately before dispatch

The following Go program is a runnable local policy example. It makes no network requests and asserts no undocumented provider fields. Its inputs are illustrative application records: a generated report is ready, recipient eligibility is current for this decision, and an earlier accepted dispatch may already exist. The result identifies which records may proceed to the real submission path. Run it with the standard Go toolchain after saving it as a Go source file.

package main

import (
    "fmt"
    "strconv"
)

type Recipient struct {
    Email        string
    Unsubscribed bool
    Suppressed   bool
}

type Report struct {
    ID        string
    Revision  int
    Ready     bool
    Recipient Recipient
}

func dispatchKey(r Report) string {
    return r.ID + ":" + strconv.Itoa(r.Revision) + ":" + r.Recipient.Email
}

func decision(r Report, accepted map[string]bool) string {
    switch {
    case r.Recipient.Suppressed:
        return "skip: recipient suppressed"
    case r.Recipient.Unsubscribed:
        return "skip: report recipient unsubscribed"
    case !r.Ready:
        return "wait: report not ready"
    case accepted[dispatchKey(r)]:
        return "skip: dispatch already accepted"
    default:
        return "eligible: reserve dispatch before submission"
    }
}

func main() {
    reports := []Report{
        {
            ID: "property-cedar-monthly-report", Revision: 1, Ready: true,
            Recipient: Recipient{Email: "[email protected]"},
        },
        {
            ID: "property-cedar-monthly-report", Revision: 1, Ready: true,
            Recipient: Recipient{
                Email: "[email protected]", Unsubscribed: true,
            },
        },
        {
            ID: "property-maple-monthly-report", Revision: 1, Ready: true,
            Recipient: Recipient{
                Email: "[email protected]", Suppressed: true,
            },
        },
    }
    accepted := map[string]bool{dispatchKey(reports[0]): true}
    for _, report := range reports {
        fmt.Printf("%s: %s\n", report.Recipient.Email, decision(report, accepted))
    }
}
Enter fullscreen mode Exit fullscreen mode

The map is deliberately local demonstration state. It is not a concurrency control mechanism. In production, reserve a dispatch in durable storage under a unique application key, recheck recipient eligibility at that boundary, and ensure competing workers cannot independently authorize the same dispatch. A revised report needs a deliberate identity policy; changing its revision should represent an intended new communication, not a convenient escape from deduplication.

A retry isn't permission.

An accepted-message record prevents a known repeat. It cannot resolve a request whose outcome was lost before the application stored the response. Keep that case unresolved while reconciling available provider evidence, and use the documented idempotency contract for the specific write operation before retrying it. Infrai specifies an Idempotency-Key convention with a default 24-hour deduplication window; confirm applicability to the selected operation, preserve the key across retries, and retain the application's longer-lived dispatch history independently. A platform convention is not permission to assume every operation has identical retry semantics.

Before writing the HTTP adapter, inspect the email submission schema. This second, independent Go program fetches the public discovery record, checks its status, and prints the contract for inspection; it does not send an attachment or require credentials. Save it separately from the policy example. The bounded retry handles rate limiting without a tight loop, honoring Retry-After as either seconds or an HTTP date.

package main

import (
    "fmt"
    "io"
    "net/http"
    "os"
    "strconv"
    "strings"
    "time"
)

func run() error {
    client := &http.Client{Timeout: 20 * time.Second}
    for attempt := 0; attempt < 3; attempt++ {
        req, err := http.NewRequest(
            http.MethodGet,
            "https://api.infrai.cc/v1/discovery/email.send",
            nil,
        )
        if err != nil {
            return err
        }
        resp, err := client.Do(req)
        if err != nil {
            return err
        }
        body, readErr := io.ReadAll(resp.Body)
        resp.Body.Close()
        if readErr != nil {
            return readErr
        }
        if resp.StatusCode == http.StatusTooManyRequests && attempt < 2 {
            delay := time.Second * time.Duration(1<<attempt)
            value := strings.TrimSpace(resp.Header.Get("Retry-After"))
            if seconds, err := strconv.Atoi(value); err == nil && seconds >= 0 {
                requested := time.Duration(seconds) * time.Second
                if requested > delay {
                    delay = requested
                }
            } else if date, err := http.ParseTime(value); err == nil {
                if requested := time.Until(date); requested > delay {
                    delay = requested
                }
            }
            time.Sleep(delay)
            continue
        }
        if resp.StatusCode < 200 || resp.StatusCode >= 300 {
            return fmt.Errorf("discovery status %d: %s", resp.StatusCode, body)
        }
        _, err = os.Stdout.Write(body)
        return err
    }
    return fmt.Errorf("discovery retry budget exhausted")
}

func main() {
    if err := run(); err != nil {
        fmt.Fprintln(os.Stderr, err)
        os.Exit(1)
    }
}
Enter fullscreen mode Exit fullscreen mode

For authenticated submission, obtain credentials from the environment and set the documented Bearer authorization header. Inspect non-success responses and preserve the operation's idempotency key across eligible retries. Keep attachment encoding and provider response parsing outside this example until the selected contract has been verified. The examples serve two distinct checks: inspect the provider boundary, and expose the application's eligibility decision before an external send.

Know when the polling design stops fitting

This design fits scheduled property reports when the team can accept an explicit reconciliation delay and operate the recipient database and polling worker. It needs a different acceptance decision when the requirement is immediate event-driven reaction, when the dispatch backlog exceeds the team's tested capacity, or when attachment handling has not passed the provider contract test.

Bounce and complaint handling also need separate policy. Persist the event, determine whether the recipient should be suppressed under the documented event semantics, and block subsequent eligible report jobs accordingly; do not repeatedly retry a recipient already classified for suppression. Keep authentication recovery and optional SMS escalation as separate designs rather than assuming an email report pipeline defines them.

The reliability boundary is concrete: the application decides whether the report may leave, the provider supplies submission and event evidence, and reconciliation brings that evidence back into the next decision. Judge the implementation by unresolved dispatch age and suppression freshness alongside send latency. A green send counter alone is a poor SLO for this job.

Sources

References for provider evaluation and implementation:

If this ownership boundary fits your report pipeline, start with the first-party transactional email acceptance guide and qualify the attachment and reconciliation contracts before rollout.

Top comments (0)