From 0cd6789e4118ceb60ca7eebbfe96a4bf69471714 Mon Sep 17 00:00:00 2001
From: Gutierrez Soto Jhosepmyr Orlando <jhosepmyrgutierrezsoto@gmail.com>
Date: Fri, 10 Jul 2026 11:36:37 -0500
Subject: [PATCH] feat(iam): redesign transactional email templates with 2026
 best practices
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Replaces bare <p>/<a> string concatenation with a proper table-based,
inline-CSS HTML layout (Outlook-safe), a hidden preheader, an
accessible CTA button with a raw-link fallback, and a real
multipart/alternative plain-text body generated from the same
structured EmailContent — so HTML and plain text can't drift apart.

Also fixes an HTML-injection gap: display/organization/project names
were interpolated raw into the email body; they're now escaped via
EmailTemplateRenderer before insertion.
---
 CHANGELOG.md                                  |  24 +++
 .../email/strategy/SmtpEmailAdapter.java      | 101 ++++++++----
 .../email/template/EmailContent.java          |  28 ++++
 .../email/template/EmailTemplateRenderer.java | 155 ++++++++++++++++++
 .../email/strategy/SmtpEmailAdapterTest.java  |  63 ++++++-
 5 files changed, 341 insertions(+), 30 deletions(-)
 create mode 100644 src/main/java/com/kntro/reqsai/iam/infrastructure/email/template/EmailContent.java
 create mode 100644 src/main/java/com/kntro/reqsai/iam/infrastructure/email/template/EmailTemplateRenderer.java

diff --git a/CHANGELOG.md b/CHANGELOG.md
index f802ac83..d86926f9 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -11,6 +11,30 @@ follows [Semantic Versioning](https://semver.org/).
 
 _Bounded-context implementation (iam, billing, workspace, discovery, gateway) in progress._
 
+### Changed (Transactional email templates — `feature/improve-email-html-templates`)
+
+- **Redesigned every transactional email** (verification, password reset, org invitation, project
+  invitation, project assignment) from bare unstyled `<p>`/`<a>` tags into a proper, brand-consistent
+  HTML layout: table-based structure (renders correctly in Outlook's Word engine, unlike
+  flexbox/grid), all styling inlined per-element (webmail clients like Gmail strip `<style>`
+  blocks/stylesheets), a fixed 600px card width, a hidden preheader driving the inbox preview
+  snippet, and an accessible CTA button (descriptive label, not "click here"; ~48px tall; a raw-link
+  fallback underneath for when the button doesn't render).
+- **Plain-text fallback** — every email is now sent as a real `multipart/alternative` message (HTML +
+  plain text generated from the same structured content), so clients that can't or won't render HTML
+  still get a readable message, per standard transactional-email delivery practice.
+- **HTML-escaping of user-controlled values** — display names, organization names, and role/project
+  names are now HTML-escaped before insertion (`EmailTemplateRenderer`/`HtmlUtils.htmlEscape`). The
+  previous string-concatenation approach interpolated these raw, which meant a display name like
+  `<script>...</script>` would have been injected verbatim into the rendered email.
+- New `com.kntro.reqsai.iam.infrastructure.email.template` package: `EmailContent` (a single
+  structured source of truth — preheader, heading, paragraphs, optional CTA, optional footnote) and
+  `EmailTemplateRenderer`, which renders both the HTML and plain-text bodies from it so the two can
+  never drift out of sync.
+- Verification and password-reset emails now state their token's actual expiry (24h / 1h,
+  matching `IAM_EMAIL_VERIFICATION_EXPIRATION` / `IAM_PASSWORD_RESET_EXPIRATION` defaults) and a
+  clear "if this wasn't you" security note.
+
 ### Added (Billing / Stripe subscriptions — `feature/billing-subscription-payments-quota`)
 
 - **Paid subscription lifecycle** — the `Subscription` aggregate gains upgrade/cancel/reactivate/downgrade
diff --git a/src/main/java/com/kntro/reqsai/iam/infrastructure/email/strategy/SmtpEmailAdapter.java b/src/main/java/com/kntro/reqsai/iam/infrastructure/email/strategy/SmtpEmailAdapter.java
index c48dff65..58acc6cf 100644
--- a/src/main/java/com/kntro/reqsai/iam/infrastructure/email/strategy/SmtpEmailAdapter.java
+++ b/src/main/java/com/kntro/reqsai/iam/infrastructure/email/strategy/SmtpEmailAdapter.java
@@ -1,12 +1,16 @@
 package com.kntro.reqsai.iam.infrastructure.email.strategy;
 
 import com.kntro.reqsai.iam.application.port.EmailNotificationPort;
+import com.kntro.reqsai.iam.infrastructure.email.template.EmailContent;
+import com.kntro.reqsai.iam.infrastructure.email.template.EmailTemplateRenderer;
 import com.kntro.reqsai.iam.infrastructure.exception.IamInfrastructureExceptions;
 import jakarta.mail.internet.MimeMessage;
 import lombok.RequiredArgsConstructor;
 import org.springframework.mail.javamail.JavaMailSender;
 import org.springframework.mail.javamail.MimeMessageHelper;
 
+import java.util.List;
+
 /**
  * SMTP-based implementation of {@link EmailNotificationPort} using Spring's {@link JavaMailSender}.
  * A single instance of this class is wired per active email provider (Mailpit, Mailtrap, Gmail)
@@ -16,6 +20,10 @@
  * All three supported SMTP providers share the same JavaMail protocol. HTTP-based providers
  * (e.g. Resend, SendGrid) require a separate adapter that uses {@code RestClient} with an API key
  * instead of {@link JavaMailSender}.
+ * <p>
+ * Every message is sent as {@code multipart/alternative} — an HTML body rendered via
+ * {@link EmailTemplateRenderer} plus a plain-text fallback generated from the same
+ * {@link EmailContent}, so clients that can't (or won't) render HTML still get a readable message.
  */
 @RequiredArgsConstructor
 public class SmtpEmailAdapter implements EmailNotificationPort {
@@ -28,18 +36,34 @@ public class SmtpEmailAdapter implements EmailNotificationPort {
     @Override
     public void sendVerificationEmail(String toEmail, String firstName, String rawToken) {
         String link = appUrl + "/auth/verify-email?token=" + rawToken;
-        send(toEmail, "Verifica tu correo — Reqs-AI",
-                "<p>Hola " + firstName + ",</p><p><a href=\"" + link + "\">Verificar correo</a></p>",
-                "verification email");
+        EmailContent content = new EmailContent(
+                "Verifica tu correo para activar tu cuenta en ReqsAI",
+                "Verifica tu correo",
+                List.of(
+                        "Hola " + firstName + ",",
+                        "Confirma tu dirección de correo para activar tu cuenta y empezar a usar ReqsAI."
+                ),
+                "Verificar correo", link,
+                "Este enlace expira en 24 horas. Si no creaste una cuenta en ReqsAI, ignora este mensaje."
+        );
+        send(toEmail, "Verifica tu correo — ReqsAI", content, "verification email");
     }
 
     @Override
     public void sendPasswordResetEmail(String toEmail, String firstName, String rawToken) {
         String link = appUrl + "/auth/reset-password?token=" + rawToken;
-        send(toEmail, "Restablece tu contraseña — Reqs-AI",
-                "<p>Hola " + firstName + ",</p><p><a href=\"" + link + "\">Restablecer contraseña</a></p>" +
-                "<p>Este enlace expira en 1 hora. Si no solicitaste este cambio, ignora este mensaje.</p>",
-                "password reset email");
+        EmailContent content = new EmailContent(
+                "Restablece tu contraseña de ReqsAI",
+                "Restablece tu contraseña",
+                List.of(
+                        "Hola " + firstName + ",",
+                        "Recibimos una solicitud para restablecer tu contraseña de ReqsAI."
+                ),
+                "Restablecer contraseña", link,
+                "Este enlace expira en 1 hora. Si no solicitaste este cambio, ignora este mensaje — tu " +
+                        "contraseña actual sigue siendo válida."
+        );
+        send(toEmail, "Restablece tu contraseña — ReqsAI", content, "password reset email");
     }
 
     @Override
@@ -49,11 +73,17 @@ public void sendInvitationEmail(String toEmail, String displayName, String organ
         String inviter = invitedByName != null && !invitedByName.isBlank()
                 ? invitedByName + " te ha invitado"
                 : "Te han invitado";
-        send(toEmail, "Te invitaron a " + organizationName + " — Reqs-AI",
-                "<p>Hola " + displayName + ",</p>" +
-                "<p>" + inviter + " a unirte a <strong>" + organizationName + "</strong> como " + role + ".</p>" +
-                "<p><a href=\"" + link + "\">Aceptar invitación</a></p>",
-                "invitation email");
+        EmailContent content = new EmailContent(
+                inviter + " a unirte a " + organizationName + " en ReqsAI",
+                "Te invitaron a colaborar",
+                List.of(
+                        "Hola " + displayName + ",",
+                        inviter + " a unirte a **" + organizationName + "** como **" + role + "**."
+                ),
+                "Aceptar invitación", link,
+                "Si no esperabas esta invitación, puedes ignorar este mensaje con seguridad."
+        );
+        send(toEmail, "Te invitaron a " + organizationName + " — ReqsAI", content, "invitation email");
     }
 
     @Override
@@ -64,35 +94,50 @@ public void sendProjectInvitationEmail(String toEmail, String displayName, Strin
         String inviter = invitedByName != null && !invitedByName.isBlank()
                 ? invitedByName + " te ha invitado"
                 : "Te han invitado";
-        send(toEmail, "Te invitaron a " + organizationName + " — Reqs-AI",
-                "<p>Hola " + displayName + ",</p>" +
-                "<p>" + inviter + " a unirte a <strong>" + organizationName + "</strong> como " + role + ".</p>" +
-                "<p>Al aceptar quedarás asignado al proyecto <strong>" + projectName + "</strong> con el rol "
-                + projectRoleName + ".</p>" +
-                "<p><a href=\"" + link + "\">Aceptar invitación</a></p>",
-                "project invitation email");
+        EmailContent content = new EmailContent(
+                inviter + " a unirte a " + organizationName + " en ReqsAI",
+                "Te invitaron a colaborar",
+                List.of(
+                        "Hola " + displayName + ",",
+                        inviter + " a unirte a **" + organizationName + "** como **" + role + "**.",
+                        "Al aceptar quedarás asignado al proyecto **" + projectName + "** con el rol **"
+                                + projectRoleName + "**."
+                ),
+                "Aceptar invitación", link,
+                "Si no esperabas esta invitación, puedes ignorar este mensaje con seguridad."
+        );
+        send(toEmail, "Te invitaron a " + organizationName + " — ReqsAI", content, "project invitation email");
     }
 
     @Override
     public void sendProjectAssignmentEmail(String toEmail, String displayName, String projectName,
                                            String projectRoleName, String projectId) {
         String link = appUrl + "/projects/" + projectId;
-        send(toEmail, "Te agregaron al proyecto " + projectName + " — Reqs-AI",
-                "<p>Hola " + displayName + ",</p>" +
-                "<p>Te agregaron al proyecto <strong>" + projectName + "</strong> con el rol "
-                + projectRoleName + ".</p>" +
-                "<p><a href=\"" + link + "\">Ir al proyecto</a></p>",
-                "project assignment email");
+        EmailContent content = new EmailContent(
+                "Te agregaron al proyecto " + projectName + " en ReqsAI",
+                "Te agregaron a un proyecto",
+                List.of(
+                        "Hola " + displayName + ",",
+                        "Te agregaron al proyecto **" + projectName + "** con el rol **" + projectRoleName + "**."
+                ),
+                "Ir al proyecto", link,
+                null
+        );
+        send(toEmail, "Te agregaron al proyecto " + projectName + " — ReqsAI", content, "project assignment email");
     }
 
-    private void send(String toEmail, String subject, String htmlBody, String emailType) {
+    private void send(String toEmail, String subject, EmailContent content, String emailType) {
         try {
             MimeMessage message = mailSender.createMimeMessage();
-            MimeMessageHelper helper = new MimeMessageHelper(message, "UTF-8");
+            // multipart=true is required for setText(text, html) below to attach an alternative
+            // plain-text part; Spring nests it as mixed > alternative > {text/plain, text/html}
+            // since there are no attachments/inline resources, which every mail client unwraps
+            // transparently to render the HTML part.
+            MimeMessageHelper helper = new MimeMessageHelper(message, true, "UTF-8");
             helper.setFrom(fromEmail);
             helper.setTo(toEmail);
             helper.setSubject(subject);
-            helper.setText(htmlBody, true);
+            helper.setText(EmailTemplateRenderer.plainText(content), EmailTemplateRenderer.html(content));
             mailSender.send(message);
         } catch (Exception e) {
             throw IamInfrastructureExceptions.emailDeliveryFailed(providerName, emailType, e);
diff --git a/src/main/java/com/kntro/reqsai/iam/infrastructure/email/template/EmailContent.java b/src/main/java/com/kntro/reqsai/iam/infrastructure/email/template/EmailContent.java
new file mode 100644
index 00000000..098c8418
--- /dev/null
+++ b/src/main/java/com/kntro/reqsai/iam/infrastructure/email/template/EmailContent.java
@@ -0,0 +1,28 @@
+package com.kntro.reqsai.iam.infrastructure.email.template;
+
+import org.jspecify.annotations.Nullable;
+
+import java.util.List;
+
+/**
+ * Structured content for a transactional email, rendered into both an HTML and a plain-text body
+ * by {@link EmailTemplateRenderer} — a single source of truth so the two versions never drift out
+ * of sync (required for a proper {@code multipart/alternative} message).
+ *
+ * @param preheader   short inbox-preview snippet (40-90 chars); hidden in the rendered body, shown
+ *                    by the mail client next to the subject line
+ * @param heading     the card's visible title
+ * @param paragraphs  body copy, one entry per paragraph, in reading order
+ * @param ctaText     the button/link label, or {@code null} for a notice-only email with no action
+ * @param ctaUrl      the button/link target, required when {@code ctaText} is set
+ * @param footnote    small print under the button (e.g. an expiry or "if this wasn't you" notice),
+ *                    or {@code null}
+ */
+public record EmailContent(
+        String preheader,
+        String heading,
+        List<String> paragraphs,
+        @Nullable String ctaText,
+        @Nullable String ctaUrl,
+        @Nullable String footnote
+) {}
diff --git a/src/main/java/com/kntro/reqsai/iam/infrastructure/email/template/EmailTemplateRenderer.java b/src/main/java/com/kntro/reqsai/iam/infrastructure/email/template/EmailTemplateRenderer.java
new file mode 100644
index 00000000..3d68c37e
--- /dev/null
+++ b/src/main/java/com/kntro/reqsai/iam/infrastructure/email/template/EmailTemplateRenderer.java
@@ -0,0 +1,155 @@
+package com.kntro.reqsai.iam.infrastructure.email.template;
+
+import org.springframework.web.util.HtmlUtils;
+
+import java.time.Year;
+import java.util.regex.Pattern;
+
+/**
+ * Renders {@link EmailContent} into an HTML body and a matching plain-text body for
+ * {@code multipart/alternative} delivery.
+ * <p>
+ * The HTML follows the conventions that keep transactional email readable across mail clients
+ * (Outlook's Word-based renderer included): a table-based layout instead of flexbox/grid, every
+ * visual rule inlined as a {@code style} attribute rather than a stylesheet, a fixed 600px content
+ * width, and a hidden preheader so the inbox preview line is under our control instead of showing
+ * raw HTML. Every dynamic value is HTML-escaped before insertion — email content built from
+ * user-supplied strings (display names, organization/project names) is otherwise an HTML-injection
+ * vector.
+ */
+public final class EmailTemplateRenderer {
+
+    private static final String INK = "#0f172a";
+    private static final String ACCENT = "#ef4444";
+    private static final String BODY_TEXT = "#1f2937";
+    private static final String MUTED_TEXT = "#6b7280";
+    private static final String BORDER = "#e5e7eb";
+    private static final String PANEL_BG = "#f9fafb";
+    private static final Pattern BOLD = Pattern.compile("\\*\\*(.+?)\\*\\*");
+
+    private EmailTemplateRenderer() {
+    }
+
+    public static String html(EmailContent content) {
+        StringBuilder paragraphsHtml = new StringBuilder();
+        for (String paragraph : content.paragraphs()) {
+            paragraphsHtml.append("""
+                    <tr><td style="padding:0 0 16px;font-size:15px;line-height:1.6;color:%s;">%s</td></tr>
+                    """.formatted(BODY_TEXT, boldToHtml(escape(paragraph))));
+        }
+
+        String ctaHtml = "";
+        if (content.ctaText() != null && content.ctaUrl() != null) {
+            String url = escape(content.ctaUrl());
+            ctaHtml = """
+                    <tr>
+                      <td style="padding:8px 0 24px;">
+                        <table role="presentation" cellpadding="0" cellspacing="0" border="0">
+                          <tr>
+                            <td style="border-radius:8px;background-color:%s;">
+                              <a href="%s" target="_blank"
+                                 style="display:inline-block;padding:14px 28px;font-size:15px;font-weight:700;
+                                        color:#ffffff;text-decoration:none;border-radius:8px;min-height:20px;">
+                                %s
+                              </a>
+                            </td>
+                          </tr>
+                        </table>
+                      </td>
+                    </tr>
+                    <tr>
+                      <td style="padding:0 0 24px;font-size:13px;line-height:1.5;color:%s;">
+                        Si el botón no funciona, copia y pega este enlace en tu navegador:<br/>
+                        <a href="%s" target="_blank" style="color:%s;word-break:break-all;">%s</a>
+                      </td>
+                    </tr>
+                    """.formatted(ACCENT, url, escape(content.ctaText()), MUTED_TEXT, url, ACCENT, url);
+        }
+
+        String footnoteHtml = "";
+        if (content.footnote() != null) {
+            footnoteHtml = """
+                    <tr><td style="padding:0 0 4px;font-size:13px;line-height:1.5;color:%s;">%s</td></tr>
+                    """.formatted(MUTED_TEXT, boldToHtml(escape(content.footnote())));
+        }
+
+        return """
+                <!DOCTYPE html>
+                <html lang="es">
+                <head>
+                  <meta charset="UTF-8" />
+                  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+                  <meta name="color-scheme" content="light" />
+                  <meta name="supported-color-schemes" content="light" />
+                  <title>%s</title>
+                </head>
+                <body style="margin:0;padding:0;background-color:%s;font-family:-apple-system,Segoe UI,Roboto,Helvetica,Arial,sans-serif;">
+                  <div style="display:none;max-height:0;overflow:hidden;opacity:0;">%s</div>
+                  <table role="presentation" width="100%%" cellpadding="0" cellspacing="0" border="0" style="background-color:%s;">
+                    <tr>
+                      <td align="center" style="padding:32px 16px;">
+                        <table role="presentation" width="600" cellpadding="0" cellspacing="0" border="0"
+                               style="width:600px;max-width:100%%;background-color:#ffffff;border-radius:12px;overflow:hidden;border:1px solid %s;">
+                          <tr>
+                            <td style="background-color:%s;padding:24px 32px;">
+                              <span style="font-size:18px;font-weight:700;color:#ffffff;letter-spacing:0.02em;">Reqs<span style="color:%s;">AI</span></span>
+                            </td>
+                          </tr>
+                          <tr>
+                            <td style="padding:32px;">
+                              <table role="presentation" width="100%%" cellpadding="0" cellspacing="0" border="0">
+                                <tr><td style="padding:0 0 16px;font-size:20px;font-weight:700;color:%s;">%s</td></tr>
+                                %s
+                                %s
+                                %s
+                              </table>
+                            </td>
+                          </tr>
+                          <tr>
+                            <td style="background-color:%s;padding:20px 32px;border-top:1px solid %s;">
+                              <p style="margin:0;font-size:12px;line-height:1.5;color:%s;">
+                                Este es un correo automático de ReqsAI, no respondas a esta dirección.<br/>
+                                &copy; %d ReqsAI &mdash; elicitación de requisitos asistida por IA.
+                              </p>
+                            </td>
+                          </tr>
+                        </table>
+                      </td>
+                    </tr>
+                  </table>
+                </body>
+                </html>
+                """.formatted(
+                escape(content.heading()), PANEL_BG, escape(content.preheader()), PANEL_BG, BORDER,
+                INK, ACCENT, BODY_TEXT, escape(content.heading()), paragraphsHtml, ctaHtml, footnoteHtml,
+                PANEL_BG, BORDER, MUTED_TEXT, Year.now().getValue());
+    }
+
+    public static String plainText(EmailContent content) {
+        StringBuilder sb = new StringBuilder();
+        sb.append(stripBold(content.heading())).append("\n\n");
+        for (String paragraph : content.paragraphs()) {
+            sb.append(stripBold(paragraph)).append("\n\n");
+        }
+        if (content.ctaText() != null && content.ctaUrl() != null) {
+            sb.append(stripBold(content.ctaText())).append(": ").append(content.ctaUrl()).append("\n\n");
+        }
+        if (content.footnote() != null) {
+            sb.append(stripBold(content.footnote())).append("\n\n");
+        }
+        sb.append("---\nEste es un correo automático de ReqsAI, no respondas a esta dirección.\n");
+        return sb.toString().strip();
+    }
+
+    private static String escape(String raw) {
+        return HtmlUtils.htmlEscape(raw, "UTF-8");
+    }
+
+    private static String boldToHtml(String escapedText) {
+        return BOLD.matcher(escapedText).replaceAll("<strong>$1</strong>");
+    }
+
+    private static String stripBold(String raw) {
+        return BOLD.matcher(raw).replaceAll("$1");
+    }
+}
diff --git a/src/test/java/com/kntro/reqsai/iam/infrastructure/email/strategy/SmtpEmailAdapterTest.java b/src/test/java/com/kntro/reqsai/iam/infrastructure/email/strategy/SmtpEmailAdapterTest.java
index 73c6f9be..46077987 100644
--- a/src/test/java/com/kntro/reqsai/iam/infrastructure/email/strategy/SmtpEmailAdapterTest.java
+++ b/src/test/java/com/kntro/reqsai/iam/infrastructure/email/strategy/SmtpEmailAdapterTest.java
@@ -1,6 +1,8 @@
 package com.kntro.reqsai.iam.infrastructure.email.strategy;
 
+import jakarta.mail.BodyPart;
 import jakarta.mail.internet.MimeMessage;
+import jakarta.mail.internet.MimeMultipart;
 import org.junit.jupiter.api.BeforeEach;
 import org.junit.jupiter.api.DisplayName;
 import org.junit.jupiter.api.Test;
@@ -10,6 +12,9 @@
 import org.mockito.junit.jupiter.MockitoExtension;
 import org.springframework.mail.javamail.JavaMailSender;
 
+import java.util.ArrayList;
+import java.util.List;
+
 import static org.assertj.core.api.Assertions.assertThat;
 import static org.mockito.Mockito.verify;
 import static org.mockito.Mockito.when;
@@ -57,10 +62,64 @@ void project_assignment_email_content() throws Exception {
         assertThat(body).doesNotContain("/invitations/accept");
     }
 
+    @Test
+    @DisplayName("message carries both a plain-text part and an HTML part with matching content")
+    void message_has_plain_text_and_html_parts() throws Exception {
+        adapter.sendPasswordResetEmail("user@example.com", "User", "raw-token");
+
+        List<String> leaves = leafContents();
+        // Content-Type headers on an in-memory, never-transported MimeMessage aren't reliable in this
+        // test harness (JavaMail only finalizes them on save/serialize), so parts are told apart by
+        // their actual content instead — which is what a real client-side render depends on anyway.
+        List<String> htmlLeaves = leaves.stream().filter(s -> s.contains("<html")).toList();
+        List<String> plainLeaves = leaves.stream().filter(s -> !s.contains("<html")).toList();
+
+        assertThat(htmlLeaves).hasSize(1);
+        assertThat(plainLeaves).hasSize(1);
+        assertThat(plainLeaves.getFirst()).contains(APP_URL + "/auth/reset-password?token=raw-token");
+        assertThat(htmlLeaves.getFirst()).contains(APP_URL + "/auth/reset-password?token=raw-token");
+    }
+
+    @Test
+    @DisplayName("dynamic values are HTML-escaped so a hostile display/org name can't inject markup")
+    void dynamic_values_are_html_escaped() throws Exception {
+        adapter.sendInvitationEmail("victim@example.com", "<img src=x onerror=alert(1)>",
+                "<script>alert('org')</script>", "MEMBER", "Owner", "raw-token");
+
+        String htmlPart = sentHtmlPart();
+        assertThat(htmlPart).doesNotContain("<img src=x onerror=alert(1)>");
+        assertThat(htmlPart).doesNotContain("<script>alert('org')</script>");
+        assertThat(htmlPart).contains("&lt;script&gt;");
+    }
+
     private String sentBody() throws Exception {
+        return String.join("\n", leafContents());
+    }
+
+    private String sentHtmlPart() throws Exception {
+        return leafContents().stream()
+                .filter(s -> s.contains("<html"))
+                .findFirst()
+                .orElseThrow(() -> new AssertionError("No HTML part found in the sent message"));
+    }
+
+    /** Flattens the (possibly nested mixed/related/alternative) MIME tree into its leaf string bodies. */
+    private List<String> leafContents() throws Exception {
         ArgumentCaptor<MimeMessage> captor = ArgumentCaptor.forClass(MimeMessage.class);
         verify(mailSender).send(captor.capture());
-        // Read the decoded content so quoted-printable soft line-breaks don't split the asserted URL.
-        return captor.getValue().getContent().toString();
+        List<String> leaves = new ArrayList<>();
+        collectLeaves(captor.getValue().getContent(), leaves);
+        return leaves;
+    }
+
+    private void collectLeaves(Object content, List<String> leaves) throws Exception {
+        if (content instanceof MimeMultipart multipart) {
+            for (int i = 0; i < multipart.getCount(); i++) {
+                BodyPart part = multipart.getBodyPart(i);
+                collectLeaves(part.getContent(), leaves);
+            }
+        } else {
+            leaves.add(content.toString());
+        }
     }
 }