feat(emails): make to and subject optional on POST /api/emails

[sweetmantech]

Implements the "make `to` optional on `POST /api/emails`" follow-up enhancement on chat#1815. Fulfills the merged contract docs#252.

What changed

lib/emails/validateSendEmailBody.ts:

• to is now optional in sendEmailBodySchema (stays minItems: 1 when provided).
• When to is omitted, resolve the authenticated account's own email(s) via selectAccountEmails({ accountIds }) and use them as the recipients.
• 400 when to is omitted and the account has no email on file.
• The existing recipient restriction (403 without a payment method) is unchanged and now runs on the resolved recipients — the account's own email is always allowed, so the default never trips it; a stranger in cc still does.
• ValidatedSendEmailRequest.to is now always a populated string[], so processAndSendEmail (which requires to) is unaffected.

Why

So a caller can "email me this" without restating their own address — the common scheduled-report case. This also lets /api/emails fully subsume /api/notifications (self-send), which chat#1815 then deletes.

Tests (TDD, RED→GREEN)

Updated lib/emails/__tests__/validateSendEmailBody.test.ts:

• defaults to to the account's own email when omitted
• includes every account email when the account has more than one
• 400 when omitted and no account email on file
• does not resolve account emails when to is provided
• (kept) empty to: [] still 400s via minItems: 1

pnpm exec vitest run lib/emails → 129 passed. tsc --noEmit adds no new errors (the 212 errors on test are pre-existing test-file type noise in lib/tasks / lib/trigger, excluded by next build). Lint clean on changed files. Preview verification to follow as a PR comment.

Merge order

docs#252 (merged contract) → this.

🤖 Generated with Claude Code

---

Summary by cubic

Make to and subject optional on POST /api/emails; when omitted, recipients default to the authenticated account’s email(s) and the subject is derived from the body or falls back to "Message from Recoup" (docs#252 / chat#1815).

• New Features

  • to optional; defaults to the account’s email(s). 400 if the account has none.
  • Recipient restriction runs on resolved recipients; the account’s own email is always allowed.
  • subject optional; uses provided value (trimmed), else the body’s first heading/line (text preferred, then HTML with tags stripped), else "Message from Recoup". Derived subjects are capped at 120 chars.
  • Validated responses always return a populated to array and subject string.

• Refactors

  • Extracted firstMeaningfulLine and stripHtml into separate modules with unit tests; resolveEmailSubject imports them. No behavior change.

^{Written for commit 31d885d. Summary will update on new commits.}

Summary by CodeRabbit

• New Features

  • Email sending now supports leaving the recipient list and subject blank in some cases.
  • A subject is automatically generated from the message content when one isn’t provided.

• Bug Fixes

  • Email messages now fall back to sensible defaults for recipients and subject lines, helping prevent send failures.
  • Recipient checks now use the final resolved addresses before sending.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
api	Ready	Preview	Jun 25, 2026 10:07pm

[coderabbitai]

Warning

Review limit reached

@sweetmantech, we couldn't start this review because you've reached your PR review rate limit.

More reviews will be available in 40 minutes and 37 seconds. Learn how PR review limits work.

Your organization has used up its prepaid credits, and credit purchases are no longer available. Enable the review add-on in the billing tab to keep reviews running — you're only billed for reviews past your plan's rate limits ($0.25/file).

⌛ How to resolve this issue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based credits.

🚦 How do rate limits work?

CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability.

For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window.

Please see our Fair Usage Limits Policy for further information.

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: bf892f29-6bbe-4132-a15b-c60ba2bd1c54

📥 Commits

Reviewing files that changed from the base of the PR and between 3dca3b5 and 31d885d.

⛔ Files ignored due to path filters (2)

• lib/emails/__tests__/firstMeaningfulLine.test.ts is excluded by !**/*.test.*, !**/__tests__/** and included by lib/**
• lib/emails/__tests__/stripHtml.test.ts is excluded by !**/*.test.*, !**/__tests__/** and included by lib/**

📒 Files selected for processing (3)

• lib/emails/firstMeaningfulLine.ts
• lib/emails/resolveEmailSubject.ts
• lib/emails/stripHtml.ts

📝 Walkthrough

Walkthrough

The PR adds email subject derivation from explicit text or HTML, with a default fallback. It also makes send-email validation fill missing recipients from the authenticated account, enforce recipient checks, and return normalized to and subject values.

Changes

Email sending validation flow

Layer / File(s)	Summary
Subject resolution helper lib/emails/resolveEmailSubject.ts	Adds DEFAULT_EMAIL_SUBJECT, line normalization helpers, and subject resolution from explicit text, markdown text, or HTML with a length cap and fallback default.
Send-email schema and request shape lib/emails/validateSendEmailBody.ts	Makes incoming to and subject optional and exports a validated request type with resolved to, subject, and accountId fields.
Recipient and subject validation flow lib/emails/validateSendEmailBody.ts	Derives missing recipients from the authenticated account, checks authorization against the derived recipients plus cc, resolves the subject, and returns the normalized request.

Sequence Diagram(s)

sequenceDiagram
  participant Request
  participant validateSendEmailBody
  participant selectAccountEmails
  participant resolveEmailSubject
  Request->>validateSendEmailBody: sendEmail body with optional to/subject
  validateSendEmailBody->>selectAccountEmails: load account emails when to is omitted
  validateSendEmailBody->>resolveEmailSubject: derive subject from subject, text, and html
  validateSendEmailBody-->>Request: ValidatedSendEmailRequest with resolved to and subject

Loading

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Poem

A subject blooms from text and light,
Or HTML crumbs in morning bright.
If recipients drift out of view,
The account emails join the queue.
✉️ Clean mail now lands just right.

🚥 Pre-merge checks | ✅ 2 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Solid & Clean Code	⚠️ Warning	validateSendEmailBody is a 70+ line orchestration function handling parsing, auth, recipient fallback, policy checks, and subject resolution, violating SRP/KISS.	Split recipient resolution, subject resolution, and response/error building into small helpers or dedicated modules so the validator only orchestrates.

✅ Passed checks (2 passed)

Check name	Status	Explanation
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/emails-to-optional

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[cubic-dev-ai]

1 issue found across 2 files

Confidence score: 3/5

• In lib/emails/validateSendEmailBody.ts, database errors during default-recipient lookup are mapped to a 400 "no email" response, which can hide backend failures as client mistakes and lead to incorrect retries/debugging by API consumers; return a 5xx (or propagate the DB error path distinctly) before merging to avoid misclassified production incidents.

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="lib/emails/validateSendEmailBody.ts">

<violation number="1" location="lib/emails/validateSendEmailBody.ts:74">
P2: Database failures while resolving default recipients are returned as 400 "no email" instead of a server error. This misclassifies internal failures as client input errors.</violation>
</file>

Architecture diagram

sequenceDiagram
    participant Client as API Client
    participant Route as POST /api/emails
    participant Validator as validateSendEmailBody
    participant Auth as validateAuthContext
    participant EmailDB as selectAccountEmails
    participant Restrict as assertRecipientsAllowed
    participant Sender as processAndSendEmail

    Note over Client,Sender: Email Sending Flow with Optional 'to'

    Client->>Route: POST /api/emails
    Route->>Validator: forward request + body

    Validator->>Validator: parse body via Zod schema
    alt 'to' provided
        Validator->>Validator: validate minItems: 1
    else 'to' omitted
        Validator->>Validator: to defaults to undefined
    end

    Validator->>Auth: validateAuthContext(request)
    Auth-->>Validator: { accountId, authToken }

    alt 'to' was omitted
        Validator->>EmailDB: selectAccountEmails({ accountIds })
        EmailDB-->>Validator: [{ email }] or []
        alt account has no emails
            Validator-->>Route: 400 "No email address found"
            Route-->>Client: 400 error response
        else emails found
            Validator->>Validator: set to = own emails
        end
    end

    Validator->>Restrict: assertRecipientsAllowed(accountId, [...to, ...cc])
    alt recipient not allowed
        Restrict-->>Validator: { allowed: false }
        Validator-->>Route: 403 "Recipient not allowed"
        Route-->>Client: 403 error response
    else allowed
        Restrict-->>Validator: { allowed: true }
    end

    Validator-->>Route: { to: string[], cc?, subject, text, accountId }
    Route->>Sender: processAndSendEmail(to, subject, text)
    Sender-->>Route: success
    Route-->>Client: 200 success response

    Note over Client,Sender: Key invariants: to always string[],<br/>own email always allowed by restriction

Loading

<sub>Reply with feedback, questions, or to request a fix.

Re-trigger cubic</sub>

[cubic-dev-ai]

P2: Database failures while resolving default recipients are returned as 400 "no email" instead of a server error. This misclassifies internal failures as client input errors.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At lib/emails/validateSendEmailBody.ts, line 74:

<comment>Database failures while resolving default recipients are returned as 400 "no email" instead of a server error. This misclassifies internal failures as client input errors.</comment>

<file context>
@@ -60,9 +69,24 @@ export async function validateSendEmailBody(
 
+  let to = result.data.to ?? [];
+  if (to.length === 0) {
+    const ownRows = await selectAccountEmails({ accountIds: authContext.accountId });
+    to = ownRows.map(row => row.email);
+    if (to.length === 0) {
</file context>

[sweetmantech]

Added subject optional (3dca3b50), matching the merged docs#252 contract.

Resend requires a non-empty subject (CreateEmailBaseOptions.subject: string), so a new resolveEmailSubject() defaults one server-side when the caller omits it: provided subject → else the body's first heading/line (text preferred, then HTML with tags stripped) → else Message from Recoup. validateSendEmailBody now returns an always-string subject; the schema marks it optional.

Tests: resolveEmailSubject unit (provided / derived / html / fallback / 120-char cap) + validator subject-defaulting cases; removed the now-obsolete "rejects a missing subject" 400 test. 155 emails/notifications tests green; tsc 0 new errors; lint clean. processAndSendEmail / MCP send_email / /api/notifications unaffected (they keep their own required-subject schemas).

This PR now covers both to and subject optional.

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@lib/emails/resolveEmailSubject.ts`:
- Around line 18-25: stripHtml currently leaves non-visible content in place, so
resolveEmailSubject can derive a subject from <style> or <script> text instead
of visible email copy. Update stripHtml in resolveEmailSubject.ts to remove
hidden/non-visible blocks before whitespace normalization, then keep the
existing tag-to-text cleanup so the first visible line is used when deriving the
subject.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: a83f0de8-8b21-4d48-a60f-f268c9377473

📥 Commits

Reviewing files that changed from the base of the PR and between 27f0532 and 3dca3b5.

⛔ Files ignored due to path filters (2)

• lib/emails/__tests__/resolveEmailSubject.test.ts is excluded by !**/*.test.*, !**/__tests__/** and included by lib/**
• lib/emails/__tests__/validateSendEmailBody.test.ts is excluded by !**/*.test.*, !**/__tests__/** and included by lib/**

📒 Files selected for processing (2)

• lib/emails/resolveEmailSubject.ts
• lib/emails/validateSendEmailBody.ts

[cubic-dev-ai]

2 issues found across 4 files (changes from recent commits).

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="lib/emails/resolveEmailSubject.ts">

<violation number="1" location="lib/emails/resolveEmailSubject.ts:11">
P2: Heading stripping is too broad and mutates non-heading first lines starting with '#'. Restrict the regex to actual Markdown heading syntax (hashes followed by whitespace or end-of-line).</violation>

<violation number="2" location="lib/emails/resolveEmailSubject.ts:21">
P2: The `stripHtml` function strips HTML tags but preserves the text content of `<script>` and `<style>` blocks. An HTML email like `<style>.btn{color:red}</style><h1>Report</h1>` would derive the subject as `.btn{color:red}` rather than `Report`. Add a preliminary replacement to remove script/style blocks entirely:
```ts
.replace(/<(script|style)\b[^>]*>[\s\S]*?<\/\1\s*>/gi, " ")
```</violation>
</file>

<sub>Reply with feedback, questions, or to request a fix.

Re-trigger cubic</sub>

[cubic-dev-ai]

P2: Heading stripping is too broad and mutates non-heading first lines starting with '#'. Restrict the regex to actual Markdown heading syntax (hashes followed by whitespace or end-of-line).

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At lib/emails/resolveEmailSubject.ts, line 11:

<comment>Heading stripping is too broad and mutates non-heading first lines starting with '#'. Restrict the regex to actual Markdown heading syntax (hashes followed by whitespace or end-of-line).</comment>

<file context>
@@ -0,0 +1,51 @@
+function firstMeaningfulLine(value?: string): string {
+  if (!value) return "";
+  for (const line of value.split("\n")) {
+    const cleaned = line.replace(/^\s*#+\s*/, "").trim();
+    if (cleaned) return cleaned;
+  }
</file context>

[cubic-dev-ai]

P2: The stripHtml function strips HTML tags but preserves the text content of <script> and <style> blocks. An HTML email like <style>.btn{color:red}</style><h1>Report</h1> would derive the subject as .btn{color:red} rather than Report. Add a preliminary replacement to remove script/style blocks entirely:

.replace(/<(script|style)\b[^>]*>[\s\S]*?<\/\1\s*>/gi, " ")

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At lib/emails/resolveEmailSubject.ts, line 21:

<comment>The `stripHtml` function strips HTML tags but preserves the text content of `<script>` and `<style>` blocks. An HTML email like `<style>.btn{color:red}</style><h1>Report</h1>` would derive the subject as `.btn{color:red}` rather than `Report`. Add a preliminary replacement to remove script/style blocks entirely:
```ts
.replace(/<(script|style)\b[^>]*>[\s\S]*?<\/\1\s*>/gi, " ")
```</comment>

<file context>
@@ -0,0 +1,51 @@
+function stripHtml(html?: string): string {
+  if (!html) return "";
+  return html
+    .replace(/<\/(h[1-6]|p|div|li|tr)\s*>/gi, "\n")
+    .replace(/<br\s*\/?>/gi, "\n")
+    .replace(/<[^>]+>/g, " ")
</file context>

[sweetmantech]

Preview test — to + subject optional, both verified ✅

Tested on the branch preview https://api-git-feat-emails-to-optional-recoup.vercel.app (commit 3dca3b50). Minted a short-lived key on the preview (same-env auth), ran the matrix, deleted the key after (delete → 200).

Case	Request	Result
A regression	to + subject provided	✅ 200, delivered (Resend 8c119f90)
B to omitted	{ subject, text } (no to)	✅ 200, delivered to the account's own email sweetmantech@gmail.com (Resend e36691b1) — selectAccountEmails resolution works on the deployment
C subject omitted	{ to, text: "# Pulse Report\n\n…" }	✅ 200 (Resend 9b52bfb7) — subject defaults to Pulse Report
D both omitted, empty body	{}	✅ 200, to self (Resend eae21684) — subject defaults to Message from Recoup
E bad to shape	{ to: "not-an-array" }	✅ 400 expected array, received string — type validation intact

Note on subject verification: the API response doesn't echo the subject and there's no GET-email-by-id route exposed (and no Resend key in this harness), so the exact defaulted subject can't be read back programmatically. The subject values are covered deterministically by the resolveEmailSubject unit tests (provided / first-heading / html / Message from Recoup fallback / 120-char cap) and are visible in the recipient inbox — cases C and D above landed as 4 real emails for visual confirmation.

Conclusion: POST /api/emails now accepts omitted to (→ account's own email) and omitted subject (→ body first line, else Message from Recoup), delivers in every case, and still rejects malformed input. Matches the merged docs#252 contract. 155 unit tests green; tsc 0 new errors.

[sweetmantech]

SRP - new lib file for firstMeaningfulLine.ts

[sweetmantech]

Done — extracted to lib/emails/firstMeaningfulLine.ts (with its own test). 31d885d5

[sweetmantech]

SRP - new lib file for stripHtml

[sweetmantech]

Done — extracted to lib/emails/stripHtml.ts (with its own test). 31d885d5

[cubic-dev-ai]

0 issues found across 5 files (changes from recent commits).

<sub>Requires human review: Auto-approval blocked by 3 unresolved issues from previous reviews.

Re-trigger cubic</sub>