Next.js boilerplate with Resend

One surface

sendEmail() from @/lib/email is the only way this app sends mail. Nothing else imports resend, constructs a Resend, or reads RESEND_API_KEY. That is what keeps the provider swappable (the Mailgun battery exports sendEmail, SendEmailOptions, SendEmailResult, EmailAttachment and EmailSuppressedError with the same shapes, so a caller written against one compiles against the other) and it is where the rules below are enforced instead of being remembered.

The one field that is not shared is Mailgun's tracking, 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 WelcomeEmail from "@/lib/email/templates/welcome";

await sendEmail({
  to: user.email,
  subject: "Welcome aboard",
  react: WelcomeEmail({ name: user.name, ctaUrl: appUrl("/app") }),
  idempotencyKey: `welcome:${user.id}`,
});

Never send from an unverified domain

from is not a parameter. It is EMAIL_FROM, and that domain must show Verified in Resend with SPF, DKIM and DMARC in place. Resend rejects a send from an unverified domain outright (this is not a spam-folder problem, it is a

403. and a caller-supplied from would let one feature bypass the check for all of them.

Use a subdomain (mail.example.com). Transactional mail then builds its own reputation and a bad week cannot damage the domain your team emails from.

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

Always set a reply-to

sendEmail fills replyTo 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 those answers have to land somewhere a human reads.

Never put a secret in an email body

Emails sit unencrypted in mailboxes, get forwarded, get indexed by clients, and pass through corporate scanners that click every link. Nothing in this repo may put the following into a message:

• API keys, database URLs, webhook signing secrets, or any environment value.
• A raw session token, a session cookie value, or anything that authenticates a request as an existing session.
• A password, including a temporary one you generated.
• A full card number, a masked one you assembled yourself, or a bank account.

A magic link is the one credential an email may legitimately 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. If a link cannot be made single-use and short-lived, it does not go in an email.

Use an idempotency key on transactional sends

Jobs retry, buttons get double-clicked, webhooks redeliver. idempotencyKey scoped to the causing event (receipt:${paymentId}, welcome:${userId}) collapses those into one message for 24 hours.

Deliberately omit it where a repeat is the point: a user who requests a second sign-in link must receive a second link, and a key would lock them out.

Respect the suppression list

sendEmail refuses an address that hard-bounced or filed a spam complaint, and the webhook route is what puts them there. Do not catch EmailSuppressedError and retry through a different path, and never call unsuppress() in bulk, only on an explicit request from the person who owns the mailbox.

Where the list is kept is src/lib/email/store.ts, generated to match the ORM this repo selected: the email_suppressions table under Drizzle or Prisma, and an in-process Map when there is no ORM. Only the Map version has a caveat, and it is the important one, on serverless every instance starts empty, so a bounce recorded by the webhook is invisible to the next send. If this repo has no ORM and you are about to launch, add one.

setSuppressionStore() in src/lib/email/suppression.ts exists for the case the generator cannot cover: a list you already keep elsewhere, or one shared across several apps. Call it once, at startup, before the first send.

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. SendEmailResult.ids carries one id per address in order; id is the first of them, so single-recipient callers are unaffected.

An idempotencyKey is suffixed with the address when a send fans out. Do not work around that: one key across several recipients would make Resend treat the second message as a retry of the first and never send it.

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: an unverified domain or a malformed address fails identically every time. The budget is deliberately small because a request path is waiting on it. Bulk work that can afford minutes belongs in a job, not in a handler.

Headers and attachments

headers is how List-Unsubscribe and List-Unsubscribe-Post get set, which Google and Yahoo require of bulk senders. 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? }. Resend's ceiling is 40MB for the whole message after encoding, so anything large should be a signed URL in the body instead.

Templates, not string concatenation

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

Always ship a text alternative. react produces one automatically; raw html does not, and sendEmail warns when you skip 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.

Tags are labels, not data

tags is Record<string, string> on both providers. Resend allows ASCII letters, digits, underscore and dash in a name and a value, and src/lib/email/tags.ts rejects anything else by name rather than letting it come back as an unexplained 422. Never put an address, a name or an id there: tags are visible in the dashboard and in every exported log.