feat: add List-Unsubscribe headers and throttle email sends (#2507)

* feat: add List-Unsubscribe headers and throttle email sends

- Add List-Unsubscribe and List-Unsubscribe-Post headers to all
  outbound emails for Gmail/RFC 8058 one-click unsubscribe compliance
- Reduce email queue concurrency from 30 to 10
- Add 1s delay between sends to avoid email spikes that trigger
  reputation systems

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* fix: use setTimeout instead of wait.for for email throttling

wait.for suspends execution and frees the concurrency slot,
defeating the throttling purpose. setTimeout holds the slot
occupied for 1s, actually spacing out sends.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* fix: use real recipient email for unsubscribe URL, not test override

When RESEND_TO_TEST is set, toAddress becomes the test email.
The unsubscribe URL should always reference the real recipient
(params.to) so the token validates correctly.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* fix: remove List-Unsubscribe-Post, add mailto fallback

The one-click POST handler doesn't exist yet (unsubscribe page is
GET only). Removed List-Unsubscribe-Post to avoid claiming RFC 8058
support we don't have. Added mailto fallback for broader client
compatibility.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* feat: add RFC 8058 one-click unsubscribe POST endpoint

- New POST /v1/email/unsubscribe endpoint that accepts email+token
  via query params, verifies HMAC token, and unsubscribes the user
- No auth required (token IS the auth, Gmail needs to POST directly)
- Re-add List-Unsubscribe-Post header now that the handler exists
- List-Unsubscribe URL points to API endpoint for one-click POST

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* fix: remove dead import, use timing-safe token comparison

- Remove unused getUnsubscribeUrl import from send-email.ts
- Use crypto.timingSafeEqual for HMAC token verification in
  unsubscribe endpoint

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* fix: guard against type confusion on query/body params

CodeQL flagged that query params could be arrays. Explicitly
coerce to string before using.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* fix: include findingNotifications in unsubscribe preferences

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: claudfuen

apps/api/src/email/email.module.ts

@@ -1,9 +1,10 @@
 import { Module } from '@nestjs/common';
 import { AuthModule } from '../auth/auth.module';
 import { EmailController } from './email.controller';
+import { UnsubscribeController } from './unsubscribe.controller';
 
 @Module({
   imports: [AuthModule],
-  controllers: [EmailController],
+  controllers: [EmailController, UnsubscribeController],
 })
 export class EmailModule {}

apps/api/src/email/unsubscribe.controller.ts

@@ -0,0 +1,71 @@
+import { Controller, Post, Body, Query, HttpCode, BadRequestException } from '@nestjs/common';
+import { ApiOperation, ApiTags } from '@nestjs/swagger';
+import { db } from '@db';
+import { generateUnsubscribeToken } from '@trycompai/email/lib/unsubscribe';
+import { timingSafeEqual } from 'node:crypto';
+
+@ApiTags('Email - Unsubscribe')
+@Controller({ path: 'email/unsubscribe', version: '1' })
+export class UnsubscribeController {
+  /**
+   * RFC 8058 one-click unsubscribe endpoint.
+   * Gmail POSTs to this URL with List-Unsubscribe=One-Click in the body.
+   * Email and token come via query params in the URL.
+   */
+  @Post()
+  @HttpCode(200)
+  @ApiOperation({ summary: 'One-click unsubscribe (RFC 8058)' })
+  async unsubscribe(
+    @Query('email') queryEmail?: string,
+    @Query('token') queryToken?: string,
+    @Body() body?: { email?: string; token?: string },
+  ) {
+    // Coerce to string - query params can be arrays if repeated
+    const rawEmail = queryEmail || body?.email;
+    const rawToken = queryToken || body?.token;
+    const email = typeof rawEmail === 'string' ? rawEmail : undefined;
+    const token = typeof rawToken === 'string' ? rawToken : undefined;
+
+    if (!email || !token) {
+      throw new BadRequestException('Email and token are required');
+    }
+
+    // Verify HMAC token (timing-safe comparison)
+    const expectedToken = generateUnsubscribeToken(email);
+    const tokensMatch =
+      expectedToken.length === token.length &&
+      timingSafeEqual(Buffer.from(expectedToken), Buffer.from(token));
+    if (!tokensMatch) {
+      throw new BadRequestException('Invalid token');
+    }
+
+    // Unsubscribe the user from all email notifications
+    const user = await db.user.findUnique({
+      where: { email },
+      select: { id: true },
+    });
+
+    if (!user) {
+      // Don't reveal user existence - just return success
+      return { success: true };
+    }
+
+    await db.user.update({
+      where: { id: user.id },
+      data: {
+        emailNotificationsUnsubscribed: true,
+        emailPreferences: {
+          policyNotifications: false,
+          taskReminders: false,
+          weeklyTaskDigest: false,
+          unassignedItemsNotifications: false,
+          taskMentions: false,
+          taskAssignments: false,
+          findingNotifications: false,
+        },
+      },
+    });
+
+    return { success: true };
+  }
+}

apps/api/src/trigger/email/send-email.ts

@@ -1,10 +1,11 @@
 import { logger, queue, schemaTask } from '@trigger.dev/sdk';
 import { z } from 'zod';
 import { resend } from '../../email/resend';
+import { generateUnsubscribeToken } from '@trycompai/email/lib/unsubscribe';
 
 const emailQueue = queue({
   name: 'send-email',
-  concurrencyLimit: 30,
+  concurrencyLimit: 10,
 });
 
 export const sendEmailTask = schemaTask({
@@ -51,12 +52,22 @@ export const sendEmailTask = schemaTask({
     }
 
     try {
+      // Build List-Unsubscribe headers for Gmail/RFC 8058 one-click compliance
+      const apiBaseUrl = process.env.NEXT_PUBLIC_API_URL || 'https://api.trycomp.ai';
+      const token = generateUnsubscribeToken(params.to);
+      const oneClickUrl = `${apiBaseUrl}/v1/email/unsubscribe?email=${encodeURIComponent(params.to)}&token=${encodeURIComponent(token)}`;
+      const headers: Record<string, string> = {
+        'List-Unsubscribe': `<${oneClickUrl}>`,
+        'List-Unsubscribe-Post': 'List-Unsubscribe=One-Click',
+      };
+
       const { data, error } = await resend.emails.send({
         from: fromAddress,
         to: toAddress,
         cc: params.cc,
         subject: params.subject,
         html: params.html,
+        headers,
         scheduledAt: params.scheduledAt,
         attachments: params.attachments?.map((att) => ({
           filename: att.filename,
@@ -76,6 +87,9 @@ export const sendEmailTask = schemaTask({
 
       logger.info('Email sent', { to: params.to, id: data?.id });
 
+      // Throttle: hold the concurrency slot for 1s to space out sends
+      await new Promise((r) => setTimeout(r, 1000));
+
       return { id: data?.id };
     } catch (error) {
       logger.error('Email sending failed', {