feat(email): multipart HTML+plaintext for RI exchange pending approval (#296)

Mirror the purchaseApprovalRequestHTMLTemplate pattern for the
SendRIExchangePendingApproval flow:

- Add riExchangePendingApprovalHTMLTemplate: inline-styled table of
  exchanges with per-row Approve/Reject CTA buttons, summary block,
  optional requested-by line, configurable cancellation-window note,
  and skipped-exchanges section.
- Extend riExchangePendingApprovalTemplate (plaintext): labelled
  Approve/Reject URLs (replacing bracket notation), optional
  requested-by block, configurable cancellation-window note.
- Extend RIExchangeNotificationData with RequestedByName,
  RequestedByEmail, RequestedAt, CancellationWindowNote fields.
- Add RenderRIExchangePendingApprovalEmailHTML renderer.
- Add sendRIExchangePendingApprovalVia helper (shared by Sender and
  SMTPSender, non-fatal HTML degrade on render error).
- SMTPSender.SendRIExchangePendingApproval: delegates to helper.
- Sender.SendRIExchangePendingApproval: uses direct SES multipart path
  when emailAddress+fromEmail are configured; falls back to SNS
  broadcast for topic-only deployments.
- 7 new test cases covering both halves, empty/custom cancellation
  notes, missing requested-by, and skipped-exchanges rendering.

Author: cristim

internal/email/sender.go

@@ -464,6 +464,18 @@ type RIExchangeNotificationData struct {
 	Exchanges    []RIExchangeItem
 	Skipped      []SkippedExchange
 	TotalPayment string
+	// RequestedByName is the human-readable display name of the user who
+	// triggered the exchange run. Empty falls back to RequestedByEmail.
+	RequestedByName string
+	// RequestedByEmail is the requester's email address. Empty omits the
+	// requested-by block from the approval email.
+	RequestedByEmail string
+	// RequestedAt is the ISO-8601 / RFC3339 timestamp the exchange was
+	// submitted. Empty omits the timestamp from the summary.
+	RequestedAt string
+	// CancellationWindowNote is short text rendered below the approve/reject
+	// buttons. Empty falls back to a generic 6-hour note.
+	CancellationWindowNote string
 }
 
 // RIExchangeItem represents a single exchange in an email notification

internal/email/smtp_sender.go

@@ -369,13 +369,10 @@ func (s *SMTPSender) SendPurchaseFailedNotification(ctx context.Context, data No
 }
 
 // SendRIExchangePendingApproval sends an RI exchange approval email via SMTP
+// as multipart/alternative (plain-text + styled HTML). Issue #296.
 func (s *SMTPSender) SendRIExchangePendingApproval(ctx context.Context, data RIExchangeNotificationData) error {
 	subject := fmt.Sprintf("CUDly - RI Exchange Approval Required (%d exchanges)", len(data.Exchanges))
-	body, err := RenderRIExchangePendingApprovalEmail(data)
-	if err != nil {
-		return fmt.Errorf("failed to render ri exchange pending approval email: %w", err)
-	}
-	return s.SendToEmail(ctx, s.notifyEmail, subject, body)
+	return sendRIExchangePendingApprovalVia(ctx, s, s.notifyEmail, subject, data)
 }
 
 // SendRIExchangeCompleted sends an RI exchange completion email via SMTP

internal/email/template_renderers.go

@@ -101,11 +101,22 @@ func RenderPurchaseFailedEmail(data NotificationData) (string, error) {
 	return renderTemplate("failed", purchaseFailedTemplate, data)
 }
 
-// RenderRIExchangePendingApprovalEmail renders the RI exchange pending approval email template
+// RenderRIExchangePendingApprovalEmail renders the plain-text RI exchange
+// pending approval email template. Pair with
+// RenderRIExchangePendingApprovalEmailHTML for multipart/alternative delivery.
 func RenderRIExchangePendingApprovalEmail(data RIExchangeNotificationData) (string, error) {
 	return renderTemplate("ri-exchange-pending", riExchangePendingApprovalTemplate, data)
 }
 
+// RenderRIExchangePendingApprovalEmailHTML renders the HTML half of the RI
+// exchange pending approval email -- inline-styled per email-client constraints.
+// The plain-text half (RenderRIExchangePendingApprovalEmail) carries the same
+// content; receiving clients pick whichever they support via the
+// multipart/alternative wrapper assembled by the sender. Issue #296.
+func RenderRIExchangePendingApprovalEmailHTML(data RIExchangeNotificationData) (string, error) {
+	return renderTemplate("ri-exchange-pending-html", riExchangePendingApprovalHTMLTemplate, data)
+}
+
 // RenderRIExchangeCompletedEmail renders the RI exchange completed email template
 func RenderRIExchangeCompletedEmail(data RIExchangeNotificationData) (string, error) {
 	return renderTemplate("ri-exchange-completed", riExchangeCompletedTemplate, data)

internal/email/template_renderers_test.go

@@ -496,3 +496,167 @@ func TestRenderWelcomeEmailHTML(t *testing.T) {
 	assert.Contains(t, html, "Hello carol@example.com,")
 	assert.Contains(t, html, "<strong>admin</strong>")
 }
+
+// Issue #296: plain-text RI exchange pending approval email carries the
+// enriched summary fields (requested-by, cancellation-window note) and uses
+// labelled Approve/Reject URLs instead of bracket-wrapped actions.
+func TestRenderRIExchangePendingApprovalEmail_Issue296(t *testing.T) {
+	data := RIExchangeNotificationData{
+		DashboardURL:           "https://dashboard.example.com",
+		TotalPayment:           "125.50",
+		RequestedByName:        "Cristi M",
+		RequestedByEmail:       "cristi@acme.com",
+		RequestedAt:            "2026-05-22T10:00:00Z",
+		CancellationWindowNote: "RI exchanges are irreversible once accepted by AWS.",
+		Exchanges: []RIExchangeItem{
+			{
+				RecordID:           "rec-001",
+				ApprovalToken:      "tok-abc",
+				SourceRIID:         "ri-0123456789abcdef0",
+				SourceInstanceType: "m5.large",
+				TargetInstanceType: "m6i.large",
+				TargetCount:        1,
+				PaymentDue:         "125.50",
+				UtilizationPct:     42.5,
+			},
+		},
+	}
+
+	body, err := RenderRIExchangePendingApprovalEmail(data)
+	require.NoError(t, err)
+
+	// Exchange details.
+	assert.Contains(t, body, "ri-0123456789abcdef0")
+	assert.Contains(t, body, "m5.large")
+	assert.Contains(t, body, "m6i.large")
+	assert.Contains(t, body, "42.5")
+	assert.Contains(t, body, "125.50")
+
+	// Requested-by block.
+	assert.Contains(t, body, "Cristi M")
+	assert.Contains(t, body, "cristi@acme.com")
+	assert.Contains(t, body, "2026-05-22T10:00:00Z")
+
+	// Labelled action URLs (not bracket notation).
+	assert.Contains(t, body, "Approve: ")
+	assert.Contains(t, body, "Reject:  ")
+	assert.Contains(t, body, "/api/ri-exchange/approve/rec-001")
+	assert.Contains(t, body, "/api/ri-exchange/reject/rec-001")
+
+	// Custom cancellation-window note overrides the generic fallback.
+	assert.Contains(t, body, "RI exchanges are irreversible once accepted by AWS.")
+	assert.NotContains(t, body, "Please approve within 6 hours")
+}
+
+// Issue #296: plain-text template omits requested-by block when email is empty.
+func TestRenderRIExchangePendingApprovalEmail_NoRequestedBy(t *testing.T) {
+	data := RIExchangeNotificationData{
+		DashboardURL: "https://dashboard.example.com",
+		TotalPayment: "50.00",
+		Exchanges: []RIExchangeItem{{
+			RecordID: "rec-002", ApprovalToken: "tok-xyz",
+			SourceRIID: "ri-aaa", SourceInstanceType: "c5.large",
+			TargetInstanceType: "c6i.large", TargetCount: 1,
+			PaymentDue: "50.00", UtilizationPct: 80.0,
+		}},
+	}
+
+	body, err := RenderRIExchangePendingApprovalEmail(data)
+	require.NoError(t, err)
+
+	assert.NotContains(t, body, "Requested by:")
+	// Generic note rendered when CancellationWindowNote is empty.
+	assert.Contains(t, body, "Please approve within 6 hours")
+}
+
+// Issue #296: HTML half of the RI exchange pending approval email carries
+// inline-styled approve/reject anchors with correct hrefs, the exchange
+// summary table, and the requested-by line.
+func TestRenderRIExchangePendingApprovalEmailHTML_Issue296(t *testing.T) {
+	data := RIExchangeNotificationData{
+		DashboardURL:           "https://dashboard.example.com",
+		TotalPayment:           "125.50",
+		RequestedByEmail:       "cristi@acme.com",
+		CancellationWindowNote: "RI exchanges are irreversible once accepted by AWS.",
+		Exchanges: []RIExchangeItem{
+			{
+				RecordID:           "rec-001",
+				ApprovalToken:      "tok-abc",
+				SourceRIID:         "ri-0123456789abcdef0",
+				SourceInstanceType: "m5.large",
+				TargetInstanceType: "m6i.large",
+				TargetCount:        1,
+				PaymentDue:         "125.50",
+				UtilizationPct:     42.5,
+			},
+		},
+	}
+
+	html, err := RenderRIExchangePendingApprovalEmailHTML(data)
+	require.NoError(t, err)
+	assert.NotEmpty(t, html)
+
+	// Inline-styled approve anchor with correct href.
+	assert.Contains(t, html, `href="https://dashboard.example.com/api/ri-exchange/approve/rec-001?token=tok-abc"`)
+	assert.Contains(t, html, `href="https://dashboard.example.com/api/ri-exchange/reject/rec-001?token=tok-abc"`)
+	assert.Contains(t, html, ">Approve<")
+	assert.Contains(t, html, ">Reject<")
+
+	// Approve button has inline green background (prove CSS classes aren't relied on).
+	assert.Regexp(t, `<a[^>]*style="[^"]*background:#16a34a[^"]*"[^>]*>Approve</a>`, html)
+
+	// Exchange table cells.
+	assert.Contains(t, html, "m5.large")
+	assert.Contains(t, html, "m6i.large")
+	assert.Contains(t, html, "42.5%")
+	assert.Contains(t, html, "125.50")
+
+	// Summary block + requested-by line.
+	assert.Contains(t, html, "cristi@acme.com")
+	assert.Contains(t, html, "RI Exchange Approval Required")
+
+	// Custom cancellation note.
+	assert.Contains(t, html, "RI exchanges are irreversible once accepted by AWS.")
+	assert.NotContains(t, html, "Please approve within 6 hours")
+}
+
+// Issue #296: HTML template falls back to generic 6-hour note when
+// CancellationWindowNote is empty.
+func TestRenderRIExchangePendingApprovalEmailHTML_DefaultCancellationNote(t *testing.T) {
+	data := RIExchangeNotificationData{
+		DashboardURL: "https://dashboard.example.com",
+		TotalPayment: "10.00",
+		Exchanges: []RIExchangeItem{{
+			RecordID: "rec-003", ApprovalToken: "tok-def",
+			SourceRIID: "ri-bbb", SourceInstanceType: "t3.medium",
+			TargetInstanceType: "t4g.medium", TargetCount: 1,
+			PaymentDue: "10.00", UtilizationPct: 60.0,
+		}},
+	}
+
+	html, err := RenderRIExchangePendingApprovalEmailHTML(data)
+	require.NoError(t, err)
+
+	assert.Contains(t, html, "Please approve within 6 hours")
+}
+
+// Issue #296: skipped exchanges block appears in HTML when Skipped is non-empty.
+func TestRenderRIExchangePendingApprovalEmailHTML_SkippedBlock(t *testing.T) {
+	data := RIExchangeNotificationData{
+		DashboardURL: "https://dashboard.example.com",
+		TotalPayment: "0.00",
+		Exchanges:    []RIExchangeItem{},
+		Skipped: []SkippedExchange{{
+			SourceRIID:         "ri-skip-01",
+			SourceInstanceType: "r5.large",
+			Reason:             "no matching target available",
+		}},
+	}
+
+	html, err := RenderRIExchangePendingApprovalEmailHTML(data)
+	require.NoError(t, err)
+
+	assert.Contains(t, html, "ri-skip-01")
+	assert.Contains(t, html, "no matching target available")
+	assert.Contains(t, html, "Skipped")
+}

internal/email/templates.go

@@ -293,29 +293,103 @@ const riExchangePendingApprovalTemplate = `CUDly - RI Exchange Approval Required
 ======================================
 
 CUDly has identified convertible RI exchanges that need your approval.
-
+{{if .RequestedByEmail}}
+Requested by: {{if .RequestedByName}}{{.RequestedByName}} <{{.RequestedByEmail}}>{{else}}{{.RequestedByEmail}}{{end}}{{if .RequestedAt}} at {{.RequestedAt}}{{end}}
+{{end}}
 Proposed Exchanges:
 {{range .Exchanges}}
 - Source: {{.SourceRIID}} ({{.SourceInstanceType}}, {{printf "%.1f" .UtilizationPct}}% utilized)
   Target: {{.TargetInstanceType}} x{{.TargetCount}}
   Payment Due: ${{.PaymentDue}}
-  [Approve] {{$.DashboardURL}}/api/ri-exchange/approve/{{.RecordID}}?token={{urlquery .ApprovalToken}}
-  [Reject]  {{$.DashboardURL}}/api/ri-exchange/reject/{{.RecordID}}?token={{urlquery .ApprovalToken}}
+  Approve: {{$.DashboardURL}}/api/ri-exchange/approve/{{.RecordID}}?token={{urlquery .ApprovalToken}}
+  Reject:  {{$.DashboardURL}}/api/ri-exchange/reject/{{.RecordID}}?token={{urlquery .ApprovalToken}}
 {{end}}
 Total Payment: ${{.TotalPayment}}
 {{if .Skipped}}
 Skipped (could not process):
 {{range .Skipped}}
 - {{.SourceRIID}} ({{.SourceInstanceType}}): {{.Reason}}
 {{end}}{{end}}
-Please approve within 6 hours (before the next analysis run).
+{{if .CancellationWindowNote}}{{.CancellationWindowNote}}{{else}}Please approve within 6 hours (before the next analysis run).{{end}}
 
 Review exchange history:
 {{.DashboardURL}}/#ri-exchange
 
-This is an automated message from CUDly.
+This is an automated message from CUDly. Do not share these links.
 `
 
+// riExchangePendingApprovalHTMLTemplate renders the same approval request as
+// the plain-text template above with inline-styled approve/reject CTAs and an
+// exchange summary table. CSS classes are NOT honoured by most email clients
+// (Outlook, mobile Gmail) — every visual rule lives in inline style=""
+// attributes. Mirrors purchaseApprovalRequestHTMLTemplate. Issue #296.
+const riExchangePendingApprovalHTMLTemplate = `<!DOCTYPE html>
+<html><head><meta charset="UTF-8"><title>CUDly - RI Exchange Approval Required</title></head>
+<body style="margin:0;padding:0;background:#f4f6f8;font-family:Arial,Helvetica,sans-serif;color:#1a202c;">
+<table role="presentation" cellpadding="0" cellspacing="0" width="100%" style="background:#f4f6f8;padding:24px 0;">
+<tr><td align="center">
+<table role="presentation" cellpadding="0" cellspacing="0" width="600" style="background:#ffffff;border-radius:8px;box-shadow:0 1px 3px rgba(0,0,0,0.06);">
+<tr><td style="padding:32px 32px 16px 32px;">
+<h1 style="margin:0;font-size:22px;color:#0f172a;">RI Exchange Approval Required</h1>
+<p style="margin:8px 0 0 0;color:#475569;font-size:14px;">CUDly has identified <strong>{{len .Exchanges}}</strong> convertible RI exchange(s) that need your approval.</p>
+</td></tr>
+
+<tr><td style="padding:0 32px 8px 32px;">
+<table role="presentation" cellpadding="0" cellspacing="0" width="100%" style="border-collapse:collapse;font-size:14px;">
+<tr><td style="padding:6px 0;color:#64748b;width:180px;">Total Payment</td><td style="padding:6px 0;color:#0f172a;font-weight:600;">${{.TotalPayment}}</td></tr>
+{{if .RequestedByEmail}}<tr><td style="padding:6px 0;color:#64748b;">Requested by</td><td style="padding:6px 0;color:#0f172a;">{{if .RequestedByName}}{{.RequestedByName}} &lt;{{.RequestedByEmail}}&gt;{{else}}{{.RequestedByEmail}}{{end}}{{if .RequestedAt}} <span style="color:#94a3b8;">at {{.RequestedAt}}</span>{{end}}</td></tr>
+{{end}}
+</table>
+</td></tr>
+
+<tr><td style="padding:0 32px 16px 32px;">
+<h2 style="margin:16px 0 8px 0;font-size:15px;color:#334155;text-transform:uppercase;letter-spacing:0.04em;">Proposed Exchanges</h2>
+<table role="presentation" cellpadding="0" cellspacing="0" width="100%" style="border-collapse:collapse;font-size:13px;border:1px solid #e2e8f0;border-radius:6px;overflow:hidden;">
+<thead><tr style="background:#f1f5f9;">
+<th align="left" style="padding:10px 12px;color:#475569;font-weight:600;">Source RI</th>
+<th align="left" style="padding:10px 12px;color:#475569;font-weight:600;">Target</th>
+<th align="right" style="padding:10px 12px;color:#475569;font-weight:600;">Utilization</th>
+<th align="right" style="padding:10px 12px;color:#475569;font-weight:600;">Payment Due</th>
+<th align="left" style="padding:10px 12px;color:#475569;font-weight:600;">Actions</th>
+</tr></thead>
+<tbody>
+{{range .Exchanges}}<tr style="border-top:1px solid #e2e8f0;">
+<td style="padding:10px 12px;color:#0f172a;"><div>{{.SourceInstanceType}}</div><div style="color:#94a3b8;font-size:11px;margin-top:2px;">{{.SourceRIID}}</div></td>
+<td style="padding:10px 12px;color:#0f172a;">{{.TargetInstanceType}} x{{.TargetCount}}</td>
+<td align="right" style="padding:10px 12px;color:#475569;">{{printf "%.1f" .UtilizationPct}}%</td>
+<td align="right" style="padding:10px 12px;color:#0f172a;font-weight:600;">${{.PaymentDue}}</td>
+<td style="padding:10px 12px;">
+<a href="{{$.DashboardURL}}/api/ri-exchange/approve/{{.RecordID}}?token={{urlquery .ApprovalToken}}" style="display:inline-block;padding:6px 14px;background:#16a34a;color:#ffffff;text-decoration:none;font-weight:600;font-size:12px;border-radius:4px;margin-right:4px;">Approve</a>
+<a href="{{$.DashboardURL}}/api/ri-exchange/reject/{{.RecordID}}?token={{urlquery .ApprovalToken}}" style="display:inline-block;padding:6px 14px;background:#ffffff;color:#dc2626;text-decoration:none;font-weight:600;font-size:12px;border-radius:4px;border:1px solid #dc2626;">Reject</a>
+</td>
+</tr>
+{{end}}</tbody></table>
+</td></tr>
+
+{{if .Skipped}}
+<tr><td style="padding:0 32px 16px 32px;">
+<h2 style="margin:8px 0 8px 0;font-size:13px;color:#94a3b8;text-transform:uppercase;letter-spacing:0.04em;">Skipped (could not process)</h2>
+<ul style="margin:0;padding-left:20px;color:#475569;font-size:13px;">
+{{range .Skipped}}<li style="margin-bottom:4px;">{{.SourceRIID}} ({{.SourceInstanceType}}): {{.Reason}}</li>
+{{end}}</ul>
+</td></tr>
+{{end}}
+
+<tr><td style="padding:8px 32px 24px 32px;">
+<p style="margin:8px 0 0 0;color:#64748b;font-size:12px;line-height:1.5;">
+{{if .CancellationWindowNote}}{{.CancellationWindowNote}}{{else}}Please approve within 6 hours (before the next analysis run).{{end}}
+</p>
+<p style="margin:8px 0 0 0;color:#94a3b8;font-size:11px;">Clicking a link will require you to sign in if you aren't already; the action is then recorded against your logged-in account.</p>
+</td></tr>
+
+<tr><td style="padding:16px 32px;background:#f8fafc;border-top:1px solid #e2e8f0;border-radius:0 0 8px 8px;">
+<p style="margin:0;color:#94a3b8;font-size:11px;">This is an automated message from CUDly. Do not share these links. <a href="{{.DashboardURL}}/#ri-exchange" style="color:#64748b;">View exchange history</a></p>
+</td></tr>
+
+</table>
+</td></tr></table>
+</body></html>`
+
 const riExchangeCompletedTemplate = `CUDly - RI Exchanges Completed
 ==============================
 
@@ -435,15 +509,39 @@ func (s *Sender) SendUserInviteEmail(ctx context.Context, email, setupURL string
 	)
 }
 
+// sendRIExchangePendingApprovalVia composes the plain-text + HTML approval
+// bodies and ships them through s.SendToEmailWithCCMultipart. HTML render
+// failures are non-fatal and degrade to single-part text so a template bug
+// never drops the approval email. Shared by Sender and SMTPSender -- issue #296.
+func sendRIExchangePendingApprovalVia(ctx context.Context, s SenderInterface, recipient, subject string, data RIExchangeNotificationData) error {
+	textBody, err := RenderRIExchangePendingApprovalEmail(data)
+	if err != nil {
+		return fmt.Errorf("failed to render ri exchange pending approval email (text): %w", err)
+	}
+	htmlBody, htmlErr := RenderRIExchangePendingApprovalEmailHTML(data)
+	if htmlErr != nil {
+		logging.Warnf("email: HTML ri-exchange-pending render failed, falling back to text-only: %v", htmlErr)
+		htmlBody = ""
+	}
+	return s.SendToEmailWithCCMultipart(ctx, recipient, nil, subject, textBody, htmlBody)
+}
+
 // SendRIExchangePendingApproval sends an email with RI exchange approval links
+// as multipart/alternative (plain-text + styled HTML) when a direct recipient
+// address is configured, or falls back to SNS broadcast (text-only) for
+// deployments that use the topic-based notification path. Issue #296.
 func (s *Sender) SendRIExchangePendingApproval(ctx context.Context, data RIExchangeNotificationData) error {
-	body, err := RenderRIExchangePendingApprovalEmail(data)
+	subject := fmt.Sprintf("CUDly - RI Exchange Approval Required (%d exchanges)", len(data.Exchanges))
+	// Use the direct SES multipart path when a notification address and a
+	// FROM_EMAIL are both configured; otherwise fall back to SNS broadcast.
+	if s.emailAddress != "" && isValidFromEmail(s.fromEmail) {
+		return sendRIExchangePendingApprovalVia(ctx, s, s.emailAddress, subject, data)
+	}
+	textBody, err := RenderRIExchangePendingApprovalEmail(data)
 	if err != nil {
 		return fmt.Errorf("failed to render ri exchange pending approval email: %w", err)
 	}
-
-	subject := fmt.Sprintf("CUDly - RI Exchange Approval Required (%d exchanges)", len(data.Exchanges))
-	return s.SendNotification(ctx, subject, body)
+	return s.SendNotification(ctx, subject, textBody)
 }
 
 // SendRIExchangeCompleted sends a notification about completed RI exchanges