Next.js boilerplate with Mailgun

One surface

sendEmail() from @/lib/email is the only way this app sends mail. Nothing else imports mailgun.js, constructs a client, or reads MAILGUN_API_KEY. The Resend battery exports sendEmail, SendEmailOptions, SendEmailResult, EmailAttachment and EmailSuppressedError with the same shapes, so a caller written against one compiles against the other, and the rules below are enforced in one file instead of being remembered in twenty.

The one field that is not shared is tracking below, because Resend has no per-message tracking switch: open and click tracking are a per-domain setting in its dashboard. Everything else you can pass here, you can pass there.

import { sendEmail } from "@/lib/email";
import ReceiptEmail from "@/lib/email/templates/receipt";

await sendEmail({
  to: user.email,
  subject: `Receipt ${payment.reference}`,
  react: ReceiptEmail({ reference: payment.reference, /* ... */ }),
  idempotencyKey: `receipt:${payment.id}`,
});

Never send from an unverified domain

from is not a parameter. It is EMAIL_FROM, whose domain must equal MAILGUN_DOMAIN and must show active in the dashboard with DKIM, SPF and a DMARC record in place. Mailgun rejects a From address outside the sending domain outright, and mailbox providers filter mail that fails authentication.

Use a subdomain (mail.example.com), never the root domain: transactional mail then builds its own reputation and a bad campaign cannot take password resets down with it.

Never put a customer's address in from to make a message look like it came from them. It fails DMARC on their domain, lands in spam, and is technically indistinguishable from spoofing. Set replyTo instead.

Be explicit about the region. MAILGUN_REGION decides the API host, a domain's region is fixed when it is created, and the wrong host answers 401, which reads exactly like a bad key.

Always set a reply-to

sendEmail fills h:Reply-To from REPLY_TO, falling back to EMAIL_FROM. Callers may override it; they may not remove it. A no-reply address is a deliverability penalty and a support failure: people answer transactional mail and the answer has to reach a human.

Never put a secret in an email body

Messages sit unencrypted in mailboxes, get forwarded, get indexed, and pass through scanners that click every link. None of the following may appear in a message this app sends:

• API keys, database URLs, signing keys, or any environment value.
• A raw session token or cookie value: anything that authenticates a request as an existing session.
• A password, including a temporary one you generated.
• A full or self-masked card number, or a payment token. cardLast4, as supplied by the payment provider, is the limit.

A magic link is the one credential an email may carry, and only because it is single-use and short-lived. Pass the URL in as a prop, never log it, and state the expiry in the body.

Use an idempotency key on transactional sends

Mailgun has no server-side idempotency, so sendEmail derives a deterministic Message-Id from the key and attaches it as a custom variable. That collapses duplicates in most clients and makes the rest findable in the logs.

Scope the key to the causing event (receipt:${paymentId}, welcome:${userId}) never to a timestamp or a random value, which is the same as having no key.

tags is Record<string, string> here as well, flattened to Mailgun's name:value tag form by src/lib/email/tags.ts, which also enforces the three-tag limit by name instead of letting the send fail. Never put an address, a name or an id in one.

Deliberately omit it where a repeat is the point: a user who requests a second sign-in link must receive one.

Let the suppression lists do their job

sendEmail checks Mailgun's bounce, complaint and unsubscribe lists before sending and throws EmailSuppressedError. Do not catch that and retry through another path.

That check is an optimisation, not the enforcement. Mailgun refuses a listed address on its own, which is why a failed lookup (a 5xx, a timeout, a DNS blip) answers "not suppressed" and lets the send proceed. Never change that to rethrow: it would turn a thirty-second provider hiccup into a total sign-in outage, because a magic link is the one message a user cannot work around. A run of suppression-unavailable incidents is the signal that the safety net is off.

unsuppress() is for an explicit request from the mailbox owner. Never clear lists in bulk: those addresses bounced for a reason, and re-sending is how a sending domain gets blocked.

suppress() writes into a list an operator reads next to entries Mailgun wrote itself, so it records a sentence rather than the app's internal reason code. Keep it that way: a row saying hard_bounce is indistinguishable from a real SMTP failure, and the next person cannot tell whether the mailbox is dead or whether support blocked it.

One message per recipient

to accepts an array, and an array produces one message per address. Nothing in this app ever puts two customers in one To header, because the recipients would see each other, and Mailgun would need recipient-variables to fan out, which this battery deliberately does not set. SendEmailResult.ids carries one id per address in order; id is the first of them.

An idempotencyKey is suffixed with the address when a send fans out, because a repeated Message-Id is treated as a duplicate by receiving servers and the second recipient would silently never get the mail.

Retries and rate limits

sendEmail retries a 429, a 5xx and a transport failure up to three attempts with jittered backoff, and never retries anything else: a 400 or a 401 fails identically every time. The budget is deliberately small because a request path is waiting on it. Bulk work belongs in a job.

Headers and attachments

headers is how List-Unsubscribe and List-Unsubscribe-Post get set, which Google and Yahoo require of bulk senders; each entry becomes an h: field. From, To, Subject and Reply-To are dropped from that map: they are owned by sendEmail and a duplicate header is a malformed message, not an override.

attachments takes { filename, content, contentType? } and becomes Mailgun's attachment field. The ceiling is 25MB for the whole message, lower than most people expect, so anything large should be a signed URL in the body.

Tracking is off unless someone decided otherwise

tracking defaults to false. Open tracking is a 1x1 pixel that reports when and roughly where a message was read; click tracking rewrites every link through a Mailgun domain. Both are personal data in the EU and both have deliverability costs: a rewritten link whose text and href disagree is a phishing signal.

Never enable tracking on a magic link, a password reset or a receipt. There is no product question those answer that is worth the rewritten URL.

Templates, not string concatenation

Mail HTML lives in src/lib/email/templates as React Email components with PreviewProps, rendered to HTML and text by sendEmail. Do not build HTML with template literals, and never interpolate user input into markup by hand: a name containing <script> is stored XSS in every webmail client that renders it.

Templates take a locale prop, and the receipt uses it for both the currency and the date. Pass the recipient's own locale rather than accepting the "en" default: a EUR receipt formatted for en-US on a document that declares lang="en" is wrong twice for a German customer.