DEV Community

AdalbertCross4085
AdalbertCross4085

Posted on

Email API Selection for Custom Welcome Templates: Queue Ownership and Delivery Polling

#email #typescript #architecture

TL;DR: Keep marketplace support templates in the application repository, let routing choose a queue before rendering, and put each email service behind a small send-and-status adapter. Choose a service only after a proof shows that it can verify your sending domain, send your custom content, and expose delivery evidence that the backend can poll without webhooks. Template ownership is the deciding boundary; a provider dashboard should not become an accidental content store.

A marketplace contact form gets complicated when buyers, sellers, trust staff, and billing staff need different acknowledgements. The useful flow is plain: validate the form, classify it into a support queue, select that queue's reviewed template, send one transactional message, store the external message identifier, and poll for evidence later. Regional requirements belong in this evaluation from the start. "US and EU supported" is too vague unless the service contract explains where message content, recipient data, and event records are processed and retained.

How should you choose an email API for custom welcome templates?

The team accountable for a reply should review the acknowledgement. A seller payout question needs different promises from a buyer's damaged-item report. If those strings live only in a mail dashboard, an application deploy and a copy change follow separate histories. The running code also loses a clear answer to a basic question: which exact content did this routing decision select?

Repository-owned templates make that relationship explicit. Store a stable template revision with the outbound record, not just a mutable template name. Render before crossing the provider boundary, then pass subject, HTML, and text to the adapter. This has a cost: the application owns escaping, previews, and multipart generation. I would accept that work for a small marketplace because portability and auditability remain in the code path already under review.

This pattern has limitations. It is not a fit when a content team must publish frequent copy changes without an application release, or when the backend cannot safely own HTML rendering. In that case, a provider-hosted template with an exported, versioned source may be the better trade-off. For this contact form, four queues, two message representations, and one stored revision per send are small enough to keep together.

Keep the boundary narrow.

Domain verification is separate from template ownership. A useful evaluation must prove control of the sending domain using the records required by the candidate, then check its documented verification status. SPF, DKIM, and DMARC have distinct roles; they are not one generic "verified" checkbox. DNS changes should be deployment prerequisites, never work performed during a contact-form request.

Put the runnable boundary before the provider decision

This example has no vendor route names. It models the capability the backend needs: accept rendered content, return a durable external identifier, and permit later status reads. The queue and revision stay application data.

type SupportQueue = "buyers" | "sellers" | "trust" | "billing";
type DeliveryState = "accepted" | "delivered" | "failed" | "unknown";

type ContactForm = {
  id: string;
  email: string;
  topic: "order" | "payout" | "safety" | "invoice";
};

type RenderedMail = { subject: string; html: string; text: string };

interface MailAdapter {
  send(input: {
    idempotencyKey: string;
    from: string;
    to: string;
    message: RenderedMail;
    metadata: Record<string, string>;
  }): Promise<{ messageId: string }>;
  readStatus(messageId: string): Promise<{
    state: DeliveryState;
    observedAt: string;
    rawType: string;
  }>;
}

const queueByTopic: Record<ContactForm["topic"], SupportQueue> = {
  order: "buyers",
  payout: "sellers",
  safety: "trust",
  invoice: "billing",
};

const revisionByQueue: Record<SupportQueue, string> = {
  buyers: "buyer-contact-v3",
  sellers: "seller-contact-v2",
  trust: "trust-contact-v4",
  billing: "billing-contact-v1",
};

async function acknowledge(
  form: ContactForm,
  mail: MailAdapter,
  render: (revision: string, form: ContactForm) => RenderedMail,
): Promise<{ messageId: string; queue: SupportQueue; revision: string }> {
  const queue = queueByTopic[form.topic];
  const revision = revisionByQueue[queue];
  const sent = await mail.send({
    idempotencyKey: `contact:${form.id}:${revision}`,
    from: "support@market.example",
    to: form.email,
    message: render(revision, form),
    metadata: { formId: form.id, queue, revision },
  });
  return { ...sent, queue, revision };
}
Enter fullscreen mode Exit fullscreen mode

The sample does not claim every service accepts an idempotency key or arbitrary metadata. Those are requirements on the application-facing adapter. A concrete adapter must document whether it forwards them, emulates them with a local outbox, or cannot meet the contract. That distinction matters because retrying a timed-out send can create two acknowledgements.

Rendering must escape untrusted form data. Never place submitted text into HTML through string concatenation. Keep a plain-text alternative, snapshot-test both forms, and test the longest supported queue name and locale. One malformed template should fail before deployment, not after a buyer submits a form.

Poll delivery evidence outside the request path

Sending and observing are different jobs. The contact request should enqueue durable work; a worker sends the message and records the external identifier. Another scheduled worker reads due records, asks the adapter for current status, appends the observation, and schedules the next read. The browser never waits for delivery.

No polling in-band.

Use bounded polling. Read soon enough to catch an immediate rejection, then increase the interval with jitter and stop at a documented terminal state or an application deadline. Exact intervals depend on rate limits, the support team's evidence needs, and the candidate's event-retention window. A service that exposes events only through pushed webhooks does not satisfy a no-webhook requirement, even if its sending interface is otherwise convenient.

Normalize cautiously. "Accepted" means a sending system accepted work; it is not proof that the recipient received or read the message. Preserve the original event type beside the normalized state so operators can inspect information the common enum discards. Store observation time separately from provider-reported event time.

Polling also has a multiplication factor: attempts times outbound messages. Measure reads per message, time to a terminal state, age of unknown records, and failures by queue. Stop polling completed records.

Test one trace instead of trusting a feature matrix

A feature matrix can say "custom templates," "domain verification," and "events" while hiding incompatible meanings. Run the same trace against every candidate. Use a test subdomain, a synthetic recipient you control, and one application-owned template revision. Send through the adapter, retain the returned identifier, retrieve status through the documented read mechanism, and save the raw evidence.

The acceptance record should answer six questions:

  1. Can the account verify the exact sending domain, and can deployment detect incomplete verification?
  2. Can the backend send HTML and plain text rendered from its reviewed template?
  3. Does a send return an identifier accepted by the status API later?
  4. Which documented states can polling observe, and which state is terminal?
  5. How are authentication failures, throttling, missing identifiers, and expired event data represented?
  6. What do the service terms say about US/EU processing, storage, subprocessors, and retention for recipient data and message content?

The sixth answer cannot be inferred from an API hostname or a region selector. Record contractual and technical evidence with the decision. If content must stay within a region, get a precise answer for each data category before integration.

For authentication messages, keep content minimal and do not turn a welcome template into an identity protocol. NIST's authenticator guidance is relevant when the same mail system carries recovery or verification flows, but a friendly welcome message is not identity proof. Separate those templates, policies, and retention rules.

Operate the contract after launch

Before production traffic, verify DNS state, render every queue and locale in CI, and send synthetic mail through the same adapter used by the worker. Confirm that revision, queue, external identifier, and raw delivery type appear in one trace. Alert on old unknown records and rising failures, but keep submitted contact text out of logs. Review retention for bodies and addresses separately from aggregate metrics.

Then rehearse replacement. A second adapter should pass the same contract tests without moving templates or rewriting routing rules. It may map status differently, which is why raw event data remains available.

The final choice is the service that passes this trace under the marketplace's regional and operational constraints. Price matters only after correct domain authentication, application-owned rendering, stable identifiers, and readable delivery evidence are demonstrated. A cheap send that the backend cannot audit is the wrong unit to optimize.

Sources

Top comments (0)