fix: preserve safe headers through SMTP proxy

[KMKoushik]

Summary

• preserve safe end-to-end and custom headers when the SMTP proxy rebuilds an email through the useSend API
• unfold raw folded header values before forwarding them
• map parsed Cc and Bcc recipients to the API's first-class fields
• reject MIME, trace, stale authentication, internal useSend, and SES control headers at both the SMTP and API boundaries
• add SMTP header-forwarding tests and extend API header-sanitization coverage

Why

The SMTP proxy currently reconstructs an API payload from a small subset of Mailparser fields. That silently drops unsubscribe, threading, automation, feedback, and application-specific headers.

Forwarding every raw header without a policy is unsafe because content/transport headers are rebuilt downstream, authentication signatures become stale, and provider control headers must not be client-controlled. This keeps useful end-to-end headers by default while excluding the categories that useSend, Nodemailer, or SES owns.

This includes @mattstein's original commit from #428 with its original authorship, then builds the general fix on top.

Verification

• pnpm --filter smtp-server test
• pnpm --filter smtp-server exec tsc --noEmit
• pnpm --filter web exec vitest run -c vitest.unit.config.ts src/server/utils/email-headers.unit.test.ts
• Prettier check on changed files
• git diff --check

No migrations or build commands were run.

---

Summary by cubic

Preserves safe end-to-end headers through the SMTP proxy and blocks unsafe ones, so unsubscribe, threading, automation, and custom headers make it to the API. Also maps Cc/Bcc correctly and unfolds folded header values.

• Bug Fixes

  • Forward safe headers via the API headers field and unfold folded values.
  • Map parsed Cc/Bcc to first-class API fields.
  • Block MIME, transport/trace, auth signatures, SES, and internal x-usesend* headers at SMTP and API boundaries.
  • Add unit tests for SMTP header forwarding and header sanitization.

• Dependencies

  • Add vitest and enable apps/smtp-server tests.

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

Summary by CodeRabbit

• New Features

  • Forwarded safe email headers are now included in outgoing messages.
  • Outgoing messages now preserve CC and BCC recipients more reliably.

• Bug Fixes

  • Improved filtering of restricted and security-sensitive email headers.
  • Strengthened protection against header-injection attempts.

• Tests

  • Added coverage for forwarded headers, recipient handling, and expanded header sanitization rules.
  • Added automated test execution for the SMTP server.

[vercel]

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

Project	Deployment	Actions	Updated (UTC)
unsend-marketing	Ready	Preview, Comment	Jul 20, 2026 9:22pm

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: bb025b94-8007-401f-93bf-3b4876b3e008

📥 Commits

Reviewing files that changed from the base of the PR and between 89cba7f and fc1784c.

⛔ Files ignored due to path filters (1)

• pnpm-lock.yaml is excluded by !**/pnpm-lock.yaml

📒 Files selected for processing (6)

• apps/smtp-server/package.json
• apps/smtp-server/src/email-headers.ts
• apps/smtp-server/src/email-headers.unit.test.ts
• apps/smtp-server/src/server.ts
• apps/web/src/server/utils/email-headers.ts
• apps/web/src/server/utils/email-headers.unit.test.ts

---

Walkthrough

The SMTP server now extracts eligible forwarded headers, unfolds and validates their values, and includes them with CC and BCC fields in outbound email payloads. Vitest is configured for SMTP tests. Web header sanitization now rejects a broader set of reserved names and prefixes, with additional test coverage for content, DKIM, ARC, and SES-related headers.

Possibly related PRs

• usesend/useSend#405: Both changes extend the SMTP server’s outbound UseSend email payload construction.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly captures the main change: preserving safe email headers through the SMTP proxy.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
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.

Warning

There were issues while running some tools. Please review the errors and either fix the tool's configuration or disable the tool if it's a critical failure.

🔧 ESLint

If the error stems from missing dependencies, add them to the package.json file. For unrecoverable errors (e.g., due to private dependencies), disable the tool in the CodeRabbit configuration.

ESLint install timed out. The project may have too many dependencies for the sandbox.

---

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.}

[cloudflare-workers-and-pages]

Deploying usesend with    Cloudflare Pages

Latest commit:	fc1784c
Status:	✅  Deploy successful!
Preview URL:	https://c6878728.usesend.pages.dev
Branch Preview URL:	https://codex-smtp-header-forwarding.usesend.pages.dev

View logs