HIPAA-compliant email for developers: BAAs, reminders, lab results

React Email doesn't know anything about HIPAA. It turns components into HTML, and the HTML goes wherever your send function points. In a lot of Next.js projects that's Resend, the default in most tutorials, including several on this site. If the recipient is a patient, that's the first line to change.

Picking a provider is the quick decision. Most of the work is deciding what each email says, then making sure your code can't send more than that.

Does HIPAA apply to your email?

HIPAA applies to covered entities (health plans, clearinghouses, and health care providers that bill insurance electronically) and to their business associates, the vendors that handle PHI for them. If you sell scheduling or portal software to clinics, you are most likely a business associate, and your email provider is your subcontractor. The chain of BAAs has to reach the company that actually delivers the mail.

PHI covers more than diagnoses. A name, an email address, and the fact that someone is a patient of a particular practice are enough. "Hi Dana, your appointment at Northside Cardiology is Tuesday at 9:30" is PHI. So is the plain fact that Northside Cardiology sends email to dana@example.com. A patient reminder can't be PHI-free. What you control is how little it says.

Which email APIs will sign a BAA

It's tempting to treat an email API as a pipe that doesn't need a BAA. HIPAA does have a conduit exception, but it is narrow: it covers services that only transmit data and have transient access to it. HHS's cloud computing guidancesays a provider that stores PHI isn't a conduit, even if it never holds the decryption key. Email APIs queue messages for retries and keep logs and event history, and many store the full message for their dashboards. They are business associates.

A provider without a BAA can still carry email that contains no PHI. In practice that means email to clinic staff (your customers, if you sell to practices), your own subscription billing, and the newsletter on your marketing site. Email from a practice to its patients almost always contains some PHI, so send it through the BAA provider. Trying to scrub it into compliance is a losing game.

Resend runs on Amazon SES, as our Resend and SES articleexplains, so people ask whether AWS's BAA covers it. It doesn't. The AWS BAA covers your AWS account and the eligible services you use in it. For mail sent through Resend, Resend is your business associate, and its security pagesays it can't sign a BAA.

Require TLS on the patient configuration set

Mail servers upgrade to TLS with STARTTLS when both sides support it, and fall back to plain text when they don't. SES behaves the same way by default. Its security protocols pagedescribes the other option: set a configuration set's TLS policy to REQUIRE, and SES drops a message rather than deliver it unencrypted.

# Run in the AWS account where the BAA has been accepted.
aws sesv2 create-configuration-set \
  --configuration-set-name patient-notices \
  --delivery-options TlsPolicy=REQUIRE

# For an existing configuration set:
aws sesv2 put-configuration-set-delivery-options \
  --configuration-set-name patient-notices \
  --tls-policy REQUIRE

aws sesv2 get-configuration-set \
  --configuration-set-name patient-notices \
  --query 'DeliveryOptions.TlsPolicy'

A dropped message is the right failure for PHI, but it's still a failure. Gmail, Outlook.com, and Yahoo all accept TLS, so drops are more likely at small or old self-hosted mail servers. Publish delivery and bounce events for this configuration set, and treat a notice that never gets a delivery event as unsent. The result is still in the portal, and someone at the practice can call.

What each patient email should say

HHS's FAQ on emailing patientssays the Privacy Rule allows it with reasonable safeguards. Its examples include checking the address before sending and "limiting the amount or type of information disclosed through the unencrypted e-mail." Even with TLS required, you only control the hop out of your provider. After that, the message sits on a phone lock screen or a shared family laptop, and you have no say in it. So keep the default small:

Sender name, subject, and preview text

The parts of an email that people see without opening it are the easiest to overlook in a template. The From name, the subject, and React Email's <Preview>text all show up on lock screens and in the inbox list. "Northside Health" is a better From name than "Northside Fertility Clinic," and "New result in your Northside Health portal" is a better subject than "Your HbA1c result." For behavioral health, substance use treatment, reproductive health, and similar services, the department name alone can say more than the patient wants on a lock screen. Use the parent organization's name.

Link to a section, not a record

A link like /results/LAB-88123?test=hba1cputs a record ID and a test name in the patient's mail logs, in the security scanners that fetch links before delivery, and in browser history. Point links at a portal section such as /results and let the portal show the item after sign-in. If you use one-click links that change state, the agent approval email guide covers why scanners make them fire on their own.

Make the minimal version the only one that compiles

The template is the last place to enforce what goes into an email. By the time props reach it, they have passed through your job queue, your logs, and maybe your error tracker. A component that ignores an extra testNameprop doesn't help much if the job payload sitting in Redis contains it.

TypeScript won't catch this on its own. Excess property checks only apply to object literals. Assign a database row to LabResultReadyProps, spread it into the component, or pass it to a function, and the extra fields type-check fine. We tried all three with a row carrying testName and value, and the compiler accepted each one. Validate at runtime, where data enters the email pipeline, and reject keys you didn't ask for.

import { z } from "zod";

const PORTAL_ORIGIN = "https://portal.northside.example";
const PORTAL_SECTIONS = ["/appointments", "/results", "/messages", "/prescriptions", "/billing"];

// Links point at a portal section, never at a specific record.
const portalLink = z
  .string()
  .url()
  .refine((value) => {
    const url = new URL(value);
    return (
      url.origin === PORTAL_ORIGIN &&
      PORTAL_SECTIONS.includes(url.pathname) &&
      url.search === "" &&
      url.hash === ""
    );
  }, "Use a portal section URL with no identifiers");

const patientBase = {
  firstName: z.string().trim().min(1).max(40),
  organizationName: z.string().min(1),
  supportPhone: z.string().min(7),
};

export const appointmentReminderSchema = z
  .object({
    ...patientBase,
    startsAt: z.string().datetime({ offset: true }),
    timeZone: z.string(),
    locationName: z.string(),
    locationAddress: z.string(),
    manageUrl: portalLink,
  })
  .strict();

export const labResultReadySchema = z
  .object({ ...patientBase, portalUrl: portalLink })
  .strict();

export type AppointmentReminderProps = z.infer<typeof appointmentReminderSchema>;
export type LabResultReadyProps = z.infer<typeof labResultReadySchema>;

export function parsePatientEmailProps<S extends z.ZodTypeAny>(
  template: string,
  schema: S,
  input: unknown,
): z.infer<S> {
  const result = schema.safeParse(input);
  if (result.success) return result.data;

  // Report field names, never values: the values are what must not leak.
  const problems = result.error.issues.map((issue) =>
    issue.code === "unrecognized_keys"
      ? `unexpected ${issue.keys.join(", ")}`
      : issue.path.join("."),
  );
  throw new Error(`${template}: invalid props (${problems.join("; ")})`);
}

.strict() turns an unexpected field into an error instead of quietly dropping it. That is on purpose: a silent strip hides the bug that put a lab value into the pipeline. Passing a row with testName and value throws lab-result-ready: invalid props (unexpected testName, value). The message names the fields and leaves out what was in them, because it will end up in your logs and your error tracker. Alert on it, since a failed parse means a patient didn't get a notice.

The portalLink check accepts the five section URLs and nothing else. A record path, a query string, a fragment, plain HTTP, and another origin all fail.

import * as React from "react";
import {
  Html, Head, Preview, Body, Container, Heading, Text, Button, Hr,
} from "react-email";
import type { LabResultReadyProps } from "@/lib/patient-email-schemas";

const text = { fontSize: "15px", lineHeight: "24px", color: "#334155" };
const small = { fontSize: "13px", lineHeight: "20px", color: "#64748b" };

export default function LabResultReady({
  firstName,
  organizationName,
  supportPhone,
  portalUrl,
}: LabResultReadyProps) {
  return (
    <Html lang="en">
      <Head />
      <Preview>Sign in to your patient portal to view it.</Preview>
      <Body style={{ margin: 0, backgroundColor: "#f1f5f9", fontFamily: "Arial, sans-serif" }}>
        <Container style={{ maxWidth: "560px", padding: "32px 24px", backgroundColor: "#ffffff" }}>
          <Heading as="h1" style={{ fontSize: "22px", lineHeight: "30px", color: "#0f172a" }}>
            A new result is ready
          </Heading>
          <Text style={text}>
            Hi {firstName}, a new result is available in your {organizationName} patient
            portal.
          </Text>
          <Button
            href={portalUrl}
            style={{ backgroundColor: "#0f766e", color: "#ffffff", borderRadius: "6px", padding: "12px 20px", fontSize: "15px" }}
          >
            Sign in to view
          </Button>
          <Text style={text}>
            We don&apos;t put results in email. If you can&apos;t sign in, call us at{" "}
            {supportPhone}.
          </Text>
          <Hr style={{ borderColor: "#e2e8f0" }} />
          <Text style={small}>
            This message went to the email address on file for a {organizationName} patient
            portal account. If you received it by mistake, please call {supportPhone} and
            delete it.
          </Text>
        </Container>
      </Body>
    </Html>
  );
}

LabResultReady.PreviewProps = {
  firstName: "Dana",
  organizationName: "Northside Health",
  supportPhone: "(555) 010-0199",
  portalUrl: "https://portal.northside.example/results",
} satisfies LabResultReadyProps;

The props type comes from the schema, so the template can't reference a field the schema doesn't allow. The footer is the misdirected-message notice from Mailgun's list, and it's worth having with any provider. The preview text says nothing about the result, because it shows on the lock screen.

import LabResultReady from "@/emails/lab-result-ready";
import { labResultReadySchema, parsePatientEmailProps } from "@/lib/patient-email-schemas";
import { sendPatientEmail } from "@/lib/send-patient-email";
import { getPatient, recordNotice } from "@/lib/db";

// The queued job holds one ID. Patient data is loaded at send time.
export async function notifyLabResult(job: { patientId: string }): Promise<void> {
  const patient = await getPatient(job.patientId);

  // Unconfirmed address: the portal and your other channels still show the result.
  if (!patient.email || !patient.emailVerifiedAt) return;

  const props = parsePatientEmailProps("lab-result-ready", labResultReadySchema, {
    firstName: patient.firstName,
    organizationName: "Northside Health",
    supportPhone: "(555) 010-0199",
    portalUrl: "https://portal.northside.example/results",
  });

  const messageId = await sendPatientEmail({
    to: patient.email,
    subject: "New result in your Northside Health portal",
    template: "lab-result-ready",
    patientRef: patient.id,
    element: <LabResultReady {...props} />,
  });

  await recordNotice({ patientId: patient.id, template: "lab-result-ready", messageId });
}

The job payload is a patient ID, so your queue never holds a result. getPatient and recordNotice stand in for your data layer. The emailVerifiedAtcheck is the HHS FAQ's address confirmation, written as code. Send a verification email at sign-up and whenever the address changes. The email verification teardown covers how to make that email work.

import type { ReactElement } from "react";
import { SESv2Client, SendEmailCommand } from "@aws-sdk/client-sesv2";
import { render, toPlainText } from "react-email";

export const ses = new SESv2Client({});

export interface PatientEmail {
  to: string;
  subject: string;
  template: string;
  // Your internal patient ID. Never a name, MRN, or email address.
  patientRef: string;
  element: ReactElement;
}

export async function sendPatientEmail(email: PatientEmail): Promise<string> {
  const html = await render(email.element);

  const { MessageId } = await ses.send(
    new SendEmailCommand({
      FromEmailAddress: "Northside Health <care@notices.northside.example>",
      ReplyToAddresses: ["patient-support@northside.example"],
      Destination: { ToAddresses: [email.to] },
      // Created with TlsPolicy=REQUIRE in setup-ses.sh.
      ConfigurationSetName: "patient-notices",
      // Stays off even if someone enables tracking on the account or configuration set later.
      ConfigurationOverrides: {
        Tracking: { OpenTrackingEnabled: "DISABLED", ClickTrackingEnabled: "DISABLED" },
      },
      Content: {
        Simple: {
          Subject: { Data: email.subject, Charset: "UTF-8" },
          Body: {
            Html: { Data: html, Charset: "UTF-8" },
            Text: { Data: toPlainText(html), Charset: "UTF-8" },
          },
        },
      },
      EmailTags: [{ Name: "template", Value: email.template }],
    }),
  );

  if (!MessageId) throw new Error(`${email.template}: SES returned no message ID`);

  // Enough to match bounce events later. No address, subject, or body.
  console.info(
    JSON.stringify({
      event: "patient_email_sent",
      template: email.template,
      patientRef: email.patientRef,
      messageId: MessageId,
    }),
  );
  return MessageId;
}

• ConfigurationSetName points at the TLS-required set from the setup step.
• ConfigurationOverrides.Trackingturns off the open pixel and link rewriting for this message, even if someone enables engagement tracking for the account later. Open tracking records when a patient read a health notice, and click tracking sends every portal link through a redirect domain. You don't need either for a notice like this. The open and click tracking guide is for the email where you do.
• The plain-text part comes from toPlainText on the same HTML, so the two parts can't drift apart.
• The log line holds a template name, your internal ID, and the SES message ID. Store the message ID with the notice, as the job does, so bounce events can be matched without ever logging an address.

When a patient asks for details by email

Some patients will want the result in the email itself. HIPAA gives them two relevant rights. They can ask to be contacted by other means, and the HHS FAQ uses email reminders instead of postcards as its example. Under the right of access, they can also ask for copies of their records by unencrypted email. HHS's access guidancesays the provider must give "a brief warning" that the information could be read by a third party in transit, confirm the patient still wants it, and then comply. Once that's done, the provider isn't responsible for a disclosure in transit.

Keep that as data you can show later, not as a checkbox in a template:

export interface EmailDetailConsent {
  patientId: string;
  // The patient asked for details by regular email.
  requestedAt: Date;
  // The exact risk notice they saw, so you can show it again in an audit.
  riskNoticeVersion: string;
  riskNoticeConfirmedAt: Date;
  revokedAt: Date | null;
}

export function mayEmailDetails(
  consent: EmailDetailConsent | null,
  now: Date = new Date(),
): consent is EmailDetailConsent {
  return (
    consent !== null &&
    consent.revokedAt === null &&
    consent.requestedAt <= now &&
    consent.riskNoticeConfirmedAt <= now
  );
}

Version the warning text and keep every version, so you can show what a patient agreed to two years from now. The proposed Security Rule changes would require exactly these two records, the request and the warning, before the email goes out. A detailed variant of a template gets its own strict schema, and the job only picks it when mayEmailDetails returns true.

Everywhere else a copy ends up

The message body is only one copy. Most of the tools around the send keep their own.

• Application logs carry the template name, your internal ID, and the message ID. They never carry rendered HTML, props, subjects, or recipient addresses.
• Error trackers capture request bodies and breadcrumbs. Scrub them, or that vendor needs a BAA too.
• Queue payloads hold IDs, and the worker loads data at send time.
• PreviewProps, test fixtures, and screenshots in pull requests use made-up patients. Nobody copies a production record to reproduce a rendering bug.
• Replies go somewhere covered by a BAA, and someone reads them. Patients answer reminders with symptoms and questions. The Reply-To guide covers the deliverability side.
• You know how long your provider keeps message content and events, and who on your team can open them in its dashboard.
• No compliance BCC to an ordinary mailbox. Each archive copy is one more place PHI lives.

No email template is HIPAA compliant by itself, ours included. A template can keep the content small and carry the right footer. Compliance is about how you send it.