Sending transactional email over an API without regretting it later

The call itself

Every transactional email API in this category converged on the same shape years ago: a bearer token, a JSON body, an accepted-for-sending response with an id you can use to look the message up later. The example below is ours, but the structure transfers directly to any of the major providers.

const response = await fetch("https://www.sendkernel.com/api/v1/emails", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.EMAIL_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    from: "Acme <receipts@yourdomain.com>",
    to: ["customer@example.com"],
    subject: "Your receipt",
    html: "<p>Thanks for your order.</p>",
    reply_to: "support@yourdomain.com",
  }),
});

// 202 means accepted for sending. It does not mean delivered.
const { id } = await response.json();

Three details in that snippet are load-bearing. The key comes from an environment variable, because a key in client-side code is a key someone else can send from. The from address is on a domain you have verified, since sending as a domain you have not authenticated fails DMARC and will be rejected. And the response is a 202 rather than a 200 — the message has been accepted for sending, and whether it was delivered is a question answered minutes later, by webhook.

Retries, and the duplicate email problem

This is the failure that reaches customers, and almost every integration has it at first. Your request times out. Your HTTP client, or your job queue, retries. The original request had already been accepted on the far side, so the customer receives two receipts — or, in the case of a password reset, two links, one of which may now be invalid.

Most transactional email APIs, ours included, do not support idempotency keys, which means preventing this is your responsibility rather than the provider's. There is no way to ask after the fact whether a timed-out request was accepted.

1. 1Record the intent before you call

   Write a row with your own send key — an order id plus a message type, say — and a pending status. Send only if that write succeeded and no row already exists.

2. 2Store the returned id against that row

   Now you have a mapping from your intent to the provider's message, which is also what makes delivery events useful later.

3. 3On a timeout, do not retry blindly

   Mark the row uncertain and reconcile it, rather than sending again. Delivering nothing is recoverable; delivering twice is not.

4. 4Retry only on 5xx and 429, with backoff

   A 4xx is a bug in your request and will fail identically forever. Retrying it just burns rate limit.

Delivery events are the half people skip

A successful API call tells you the provider accepted the message. Everything you actually care about — delivered, bounced, marked as spam — happens afterwards and reaches you by webhook. Integrations that skip this work fine in testing and quietly rot in production, because nothing updates the application's view of which addresses are still reachable.

• Hard bounce: the address does not exist. Stop sending to it permanently, and mark it in your own database as well as the provider's suppression list.
• Soft bounce: a temporary failure such as a full mailbox. Retry a few times, then treat repeated failures as hard.
• Complaint: the recipient marked it as spam. Suppress immediately, and treat it as more serious than an unsubscribe.
• Delivered: accepted by the receiving server. Useful for support conversations, and the only event that answers 'did they get it'.

Two properties matter when you write the handler. It must be idempotent, because providers redeliver events and you will see duplicates. And it must verify the signature on the request, because an unauthenticated webhook endpoint lets anyone suppress your customers' addresses by posting fake bounces.

Keep transactional mail away from marketing mail

Password resets and receipts have to arrive. A newsletter would like to arrive. If both go out through the same stream on the same domain, a badly received campaign drags the reset emails down with it — and the person who cannot log in does not care that the cause was a marketing send.

• Separate the streams, either as distinct products or distinct subdomains — receipts@ or mail@ for transactional, news@ for campaigns.
• Never add an unsubscribe header to transactional mail. It is not required by the bulk sender rules, and a recipient who opts out of password resets has locked themselves out of their own account.
• Do not slip marketing content into transactional messages. A receipt with a promotion attached is a marketing message legally and, more importantly, is what recipients report as spam.
• Watch the two complaint rates separately. A transactional complaint rate above zero is a signal that something is wrong with what you are sending.

A short checklist before you ship

• API key in a server-side environment variable, never in client or mobile code.
• Sending domain verified with SPF, DKIM, and DMARC all aligned.
• Your own send key recorded before the call, so a timeout cannot become a duplicate.
• Retries limited to 5xx and 429, with exponential backoff and a ceiling.
• A signed, idempotent webhook handler that writes bounces and complaints back to your database.
• Transactional and marketing on separate streams, with separate reputations.
• A plain-text alternative on every message, generated if you do not write one.
• A staging path that does not deliver, so tests cannot mail real customers.

For what it is worth, the API described here runs the same preflight as the dashboard — an unverified domain, a missing postal address, or a complaint rate over the threshold blocks an API send exactly as it blocks a manual one. There is no API-only bypass. That is occasionally inconvenient and it is the point: a compliance rule that a script can skip is not a rule.