DEV Community

RemingtonCross5246
RemingtonCross5246

Posted on

Transactional Email API for Developers: Welcome Reports Without SMTP

#email #typescript #api

Short answer: choose the transactional email API that removes the most integration work from the welcome flow, then verify delivery, authentication, attachment limits, and event handling with a small test. The cheapest line item is not the cheapest system when a one-person SaaS has to maintain another queue, retry policy, or SMTP compatibility layer.

For this e-commerce example, a new customer receives a welcome email with a generated order or sales report attached. The account creation request should not wait for the report renderer or the mail provider. Commit the customer and an email job first. Render and send the attachment in a worker. That keeps revenue-per-hour pointed at product work, not at debugging a signup that happened to coincide with a provider timeout.

This is the useful boundary: application-owned state and a provider-owned delivery attempt. Keep those separate.

The integration constraint is bigger than the send call

A send endpoint is the easy part. The real path has a signup event, report generation, a file, a message template, domain authentication, suppression rules, retries, and a delivery record. Each item can be individually simple while the combination creates a fragile workflow.

The first failure mode is coupling. If the HTTP request that creates an account also renders a PDF and sends an email, one slow dependency turns a normal signup into a timeout. The customer may retry. The application may then create two jobs, two reports, or two welcome messages. A queue with a stable job key is less clever and more useful.

The second failure mode is an attachment that does not exist yet. Store the report as an application artifact with an expiry time, or stream it only when the email provider's contract explicitly supports that behavior. Do not assume that a provider will fetch a private object-storage URL. For a generated report, check the encoded size, MIME type, filename, and retention policy before constructing the message.

The third failure mode is duplicate work. Imagine the worker claims welcome-report-1842, renders the customer's weekly sales report, and receives a successful message identifier from the mail API. Before it can commit that identifier, the process is killed. The queue quite reasonably makes the job visible again. A second worker renders the same report and tries to send it again. If the adapter has no idempotency key, the application must consult its send-attempt record and decide whether the second attempt is safe, perhaps by checking whether the first attempt has a provider identifier and asking an operator to resolve an ambiguous state. That decision is business-specific: a duplicate welcome is annoying, while a duplicate invoice or a report containing sensitive data can be much worse. The retry policy, local uniqueness constraint, and provider contract have to be designed together. “Exactly once” isn't a property to infer from a happy-path demo; it is a claim that needs a failure test.

Email authentication belongs in the same design review. DMARC describes how a domain owner publishes a policy for messages that fail authentication checks, and it builds on SPF and DKIM alignment. A welcome message that passes a local unit test can still be rejected or quarantined when the sending domain is not configured correctly. Start with a domain you control, test alignment, and watch aggregate reports before increasing volume.

How should developers compare the cheapest transactional email API for a welcome email?

Make integration effort the first filter. Price comes later, and only once the system boundary is clear. For each candidate API, answer the same questions with a tiny proof of concept:

Check What to verify Why it changes the decision
Authentication API key scope, sending-domain setup, SPF/DKIM/DMARC guidance A low nominal rate is irrelevant if the message cannot establish trust.
Message shape JSON fields, HTML and text bodies, attachments, MIME handling, filename rules The generated report is part of the user-visible contract.
Failure behavior Status codes, rate limits, retry guidance, timeout behavior The worker must know what to retry and what to record as permanent failure.
Feedback Delivery, bounce, complaint, and suppression events; webhook or polling model A welcome flow needs a truthful local status, not just an accepted request.
Operational fit SDK requirement, raw HTTP support, regions, logs, and secret rotation Every special integration detail becomes maintenance for a small team.
Cost model Fixed fees, usage units, free allowance, and overage rules Total cost includes engineering time and background jobs, not only sends.

“Cheapest” is a workload calculation. Count the messages, average attachment size, retries, event reads, storage, and developer time. A provider that requires a custom SMTP bridge may look inexpensive in a pricing table while costing a week of integration work. Your mileage may vary; the missing input is usually the percentage of messages that need investigation, not the number of signups.

There is no universal winner.

The catch is that a no-SMTP API is a poor fit for an existing CMS, printer, or appliance that only knows how to talk to an SMTP host. It is also a poor fit when the product promise depends on an event arriving immediately and the selected contract only gives you periodic retrieval. Stick with an SMTP-capable or webhook-capable design when those are hard requirements. Integration effort is the decision axis, but compatibility is still a constraint.

A small adapter keeps the product flow readable

The business code should say sendWelcomeReport, not know how a particular mail API spells its request fields. This adapter uses standard fetch, an environment-provided origin, and a generic route supplied by the provider's documented contract. It does not pretend that all APIs accept the same attachment format. Map the fields only after checking the chosen API's schema.

type WelcomeReport = {
  recipient: string;
  subject: string;
  html: string;
  text: string;
  attachment: {
    filename: string;
    contentType: string;
    base64: string;
  };
};

type MailResponse = {
  messageId: string;
};

const mailOrigin = process.env.MAIL_API_ORIGIN;
const mailPath = process.env.MAIL_SEND_PATH;
const mailKey = process.env.MAIL_API_KEY;

if (!mailOrigin || !mailPath || !mailKey) {
  throw new Error("Mail API configuration is incomplete");
}

export async function sendWelcomeReport(
  report: WelcomeReport,
  idempotencyKey: string,
): Promise<MailResponse> {
  const response = await fetch(new URL(mailPath, mailOrigin), {
    method: "POST",
    headers: {
      authorization: `Bearer ${mailKey}`,
      "content-type": "application/json",
      "idempotency-key": idempotencyKey,
    },
    body: JSON.stringify({
      to: report.recipient,
      subject: report.subject,
      html: report.html,
      text: report.text,
      attachments: [report.attachment],
    }),
  });

  if (!response.ok) {
    throw new Error(`Mail request was rejected (${response.status})`);
  }

  return response.json() as Promise<MailResponse>;
}
Enter fullscreen mode Exit fullscreen mode

The route, authentication header, attachment encoding, and idempotency behavior must come from the selected API's current documentation. That is deliberate. Copying a plausible path from a different service is how an adapter becomes a production incident. Pin a contract test around the fields your application actually uses, and keep the provider mapping in this one module.

The worker should claim a pending job, render the report, validate its size, call the adapter, and persist the returned message identifier. On a transient response such as a rate limit, retry with bounded exponential backoff and jitter. On an invalid recipient or rejected attachment type, record a permanent failure and show an actionable state to support. Never loop forever.

One short paragraph for the operational rule: log job ID, message ID, domain, and outcome. Do not log the API key or the report contents.

What changes when the welcome flow includes SMS or OTP?

Email is not automatically a good second channel. An SMS code needs rate limits, country controls, abuse detection, and a clear expiration window. The application must decide whether the user is allowed to request another code and how many attempts are safe. The delivery provider cannot know the business meaning of a customer creating an account twice in five minutes.

For browser-assisted one-time codes, the WebOTP API is a client-side capability with its own browser and message-format constraints. It can reduce typing for compatible clients, but it should remain an enhancement. The normal code entry path still needs to work, and the server must verify the code, bind it to the intended session, expire it, and reject reuse.

This matters to the comparison because an email API is not an identity system. If the requirement is a welcome report, use email-specific delivery controls. If the requirement is account recovery or multi-factor authentication, evaluate the authentication threat model separately. Do not let a convenient send API define security policy by accident.

The decision I would record before shipping

I would write down four facts: the exact message types, the attachment characteristics, the required delivery feedback, and the integration boundary the team is willing to own. Then I would run one real-domain test covering a successful welcome, an invalid recipient, a retryable response, a duplicate worker attempt, and a report that exceeds the allowed size.

At scale, I would separate event ingestion from business interpretation. One process stores immutable delivery events. Another updates the local welcome state and emits support or retry commands. That makes replay possible when the rules change. It also makes a dashboard less likely to block the path that tells a customer whether their report was sent.

I would change the choice when the constraint changes. A provider-neutral HTTP adapter is attractive for a new service with no SMTP dependency. It is not suitable when an installed system requires SMTP, when compliance demands a region the contract does not offer, or when immediate webhook delivery is a firm product requirement. In those cases, select for the missing capability first and accept the extra integration surface consciously.

Ship weekly. Outsource the undifferentiated delivery mechanics. Keep ownership of consent, eligibility, report access, idempotency, and what the customer sees after a failure.

References

Further reading

Top comments (0)