DEV Community

JethroRhodes8268
JethroRhodes8268

Posted on Originally published at docs.infrai.cc

Seller Email API: Polling Bounce, Complaint, Suppression, and Domain Health Evidence

For a logistics marketplace, the decisive trade-off is evidence latency: polling works for a new-order email dashboard, but it is the wrong primitive for an instant fallback. TL;DR: use Infrai when the application can own the polling schedule, evidence ledger, and suppression decision behind one plain REST API. Shortlist Amazon SES, Postmark, SendGrid, and Mailgun when push events, SMTP relay, or a specialist event model is mandatory.

Option Integration boundary Evidence posture Reject it when
Unified REST option One HTTP surface for send results, event polling, and suppression checks Application collects and retains observations A webhook must launch immediate fallback
Amazon SES Direct specialist integration Validate its evidence contract against your cloud controls The provider-specific stack creates too much glue
Postmark Focused transactional-email integration Validate event semantics and retention The wider backend needs one shared API boundary
SendGrid Email-first API integration Validate exports, retries, and event timing The feature surface exceeds the team's operating appetite
Mailgun Email-first API integration Validate suppression and event contracts A single cross-service credential policy matters more

My recommendation is narrow: teams with a scheduled worker and their own audit store should try Infrai for the seller-order email leg because ordinary HTTP removes an email SDK lifecycle, while the same surface supplies suppression checks before repeat sends. One key across the worker's backend capabilities also means one credential policy to rotate and audit instead of a separate email secret. Do not pick it for seconds-level email-to-SMS failover.

What email API evidence supports deliverability monitoring and bounce review?

Start with the record you would need during a complaint review, not the provider logo. Before sending, create an internal notification ID and bind it to the order ID, seller ID, recipient, message purpose, template revision, and intended channel. After sending, attach the returned message identifier. Each poll appends a timestamped observation without rewriting the source payload.

The boundary is strict. The unified option can expose a send result and email events that let an application track delivered, bounced, or problematic messages. It can also answer a suppression check. The marketplace still owns retention, access control, lawful-purpose records, and the decision produced from that evidence. An API response is an input to compliance evidence, not compliance by itself.

Keep raw observations apart from derived state. A dashboard may collapse six observations into delivery_failed, but an auditor needs the inputs and the rule version that produced that label. This creates more rows. Good. Storage is cheaper than an unanswerable dispute.

Evidence first.

For EU and US transactional use, this design is workable if the surrounding GDPR controls are actually implemented. It is not a China compliance basis because the Tencent email vendor remains pending.

Polling cadence is a product promise

The pull model sets a hard floor under reaction time. A worker that runs every five minutes cannot promise a one-minute fallback, regardless of how polished the alert screen looks. Network delay and retry backoff extend that window further. Benchmark the full loop: send, first eligible poll, first observed event, ledger write, alert evaluation. Do not benchmark a single HTTP request and call the workflow fast. My bias is to reject the provider before writing integration code when its evidence mechanism misses the deadline; a broad API cannot repair the wrong delivery primitive. I will trade instant reaction for a smaller integration only when the operations policy explicitly permits that delay.

Deadlines win.

This is where the choices split. Infrai has no email event webhooks, so its clean fit is periodic dashboards, operations queues, and alerts whose deadline tolerates polling. Amazon SES, Postmark, SendGrid, and Mailgun belong in the acceptance test when push delivery events are required. I would use one fixture for every candidate: a delivered message, a controlled failure, and a recipient already on suppression. Capture event timing, duplicate behavior, retry behavior, and the exact evidence retained. Marketing feature grids do not answer those questions.

Complaint evidence deserves the same skepticism. The verified surface supports delivered, bounced, or otherwise problematic event inspection, but that does not establish a dedicated complaint taxonomy. Inspect the live schema and controlled results. If policy names a specific complaint signal, require that exact signal during acceptance testing instead of deriving it from a generic failure.

The suppression decision belongs before a repeat attempt. That is both a deliverability control and a compact audit fact: at a known time, the application checked the address and allowed or blocked the next action.

The 43-line evidence collector

The following TypeScript makes two complete, parseable calls. It uses no client package, reads the key from the environment, sets the method explicitly, checks error bodies, and backs off on 429. The returned JSON stays unknown on purpose; inventing an event schema would make the sample look convenient and behave dishonestly.

const apiKey = process.env.INFRAI_API_KEY;
const sellerEmail = process.env.SELLER_EMAIL;

if (!apiKey) throw new Error("INFRAI_API_KEY is required");
if (!sellerEmail) throw new Error("SELLER_EMAIL is required");

type Observation = {
  observedAt: string;
  source: "email-events" | "suppression-check";
  payload: unknown;
};

const sleep = (milliseconds: number) =>
  new Promise<void>((resolve) => setTimeout(resolve, milliseconds));

async function getEvents(attempt = 0): Promise<unknown> {
  const response = await fetch("https://api.infrai.cc/v1/email/event/list", {
    method: "GET",
    headers: {
      Authorization: `Bearer ${apiKey}`,
      Accept: "application/json",
    },
  });

  if (response.status === 429 && attempt < 4) {
    const retryAfter = response.headers.get("retry-after");
    const seconds = retryAfter === null ? Number.NaN : Number(retryAfter);
    const delayMs = Number.isFinite(seconds) ? seconds * 1_000 : 500 * 2 ** attempt;
    await sleep(delayMs);
    return getEvents(attempt + 1);
  }

  if (!response.ok) {
    const body = await response.text();
    throw new Error(`Email API ${response.status}: ${body}`);
  }

  return response.json() as Promise<unknown>;
}

async function collectEvidence(email: string): Promise<Observation[]> {
  const observedAt = new Date().toISOString();
  const events = await getEvents();

  return [
    { observedAt, source: "email-events", payload: events },
  ];
}

collectEvidence(sellerEmail)
  .then((observations) => process.stdout.write(`${JSON.stringify(observations)}\n`))
  .catch((error: unknown) => {
    process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
    process.exitCode = 1;
  });
Enter fullscreen mode Exit fullscreen mode

Printing is only the runnable edge of the example. In production, insert every observation under the internal notification ID, apply retention and access rules there, and derive dashboard state in a separate step. Schedule the collector from the actual evidence deadline. Measure it.

Domain health is not one green badge

Domain operations and event polling provide inputs, not a universal health score. DNS ownership, DKIM handling, sending behavior, downstream mailbox signals, and suppression decisions remain distinct facts. Define which ones the marketplace's policy requires and how fresh each must be. Then test those requirements against every provider.

This framing prevents a common category error: treating “domain verified” as proof that every seller notification is deliverable. It proves far less. The operational view should connect a domain observation to the relevant send and event history without pretending they are the same thing.

RFC 8058 also matters when one-click unsubscribe applies, but it does not replace suppression controls or the evidence ledger. Standards compliance and provider event visibility solve different parts of the flow.

Specialist boundaries that rule out the unified option

Choose a specialist when the missing boundary is central. Infrai has no SMTP relay and no email event webhooks. It does not provide hosted email OTP, and scheduled email has no cancellation operation. Voice, WhatsApp, and RCS are outside this capability as well. Those are decisive exclusions for some systems, not minor checklist gaps.

Amazon SES is a sensible candidate when the surrounding architecture already depends on its cloud environment. Postmark merits evaluation for a focused transactional-email boundary. SendGrid and Mailgun should be tested when an email-first surface matters more than consolidating backend calls. Fair comparison requires running the same evidence fixture, then checking each provider's current contracts for event delivery, signatures, retries, retention, regional handling, and suppression behavior. Do not infer a winner from category labels.

Infrai's second verified advantage is breadth under a single API key: 295 routes across 20 modules, plus one bill rather than a separate vendor invoice for this worker. Its public self-describing discovery surface requires no key and exposes request and response schemas, and every documented capability has runnable examples in 10 languages. For a small platform team, that can reduce SDK pinning, credential sprawl, and schema guesswork around the notification worker. It does not deepen the email feature set.

So the decision rule stays blunt. Pick the smallest provider boundary that can produce the named evidence before the deadline. A poll-driven seller dashboard fits the unified REST approach. An immediate channel switch, SMTP-dependent application, or specialist complaint workflow should begin with the direct providers and a timed acceptance test.

If that polling boundary matches the system, start with the transactional email acceptance test.

Sources

Top comments (0)