pn-new-crm/docs/operations/outbound-comms-safety.md

Outbound communications safety net

Last reviewed: 2026-05-03 Owner: matt@portnimara.com

This doc enumerates every channel through which the CRM can produce outbound communication (email, document signing, webhooks) and describes how each channel respects the EMAIL_REDIRECT_TO env var. The goal: a single environment flip pauses all outbound traffic, so a production data import, dedup migration dry-run, or staging environment can run against real data without anyone getting paged or spammed.

Single env switch: when EMAIL_REDIRECT_TO is set to an address, all outbound communication is rerouted there or short-circuited. Unset it in production.

---

Channels

1. Direct email (sendEmail)

Path: src/lib/email/index.ts → sendEmail() → nodemailer SMTP transport.

Safety: YES — covered.

When EMAIL_REDIRECT_TO is set, sendEmail() rewrites the to header to the redirect address and prefixes the subject with [redirected from <orig>]. The original recipient is logged.

Call sites (all flow through sendEmail, so all are covered):

• src/lib/services/portal-auth.service.ts — portal activation + reset
• src/lib/services/crm-invite.service.ts — CRM user invitations
• src/lib/services/document-templates.ts — template-generated PDFs sent as attachments (the PDF body is generated locally; the email itself goes through SMTP)
• src/lib/services/email-compose.service.ts — ad-hoc emails composed in the in-app UI
• src/lib/services/gdpr-export.service.ts — GDPR export delivery

2. Documenso e-signature recipients

Path: src/lib/services/documenso-client.ts → createDocument() / generateDocumentFromTemplate() → Documenso REST API.

Safety: YES — covered as of 2026-05-03.

Documenso's own server sends the signing-request email on our behalf. We can't intercept that at the SMTP layer because it's external. The fix is at the REST-call boundary: when EMAIL_REDIRECT_TO is set, createDocument rewrites every recipient's email to the redirect address and prefixes the recipient name with (was: <orig email>) so the doc is still traceable to its intended recipient. generateDocumentFromTemplate does the same for both shapes the template-generate endpoint accepts (v1.13 formValues.*Email keys and v2.x recipients array).

The redirect happens before the API call, so even if Documenso has its own retry logic the original email never leaves our process.

3. Webhooks (outbound to user-configured URLs)

Path: src/lib/queue/workers/webhooks.ts → BullMQ job → fetch(webhook.url, ...).

Safety: YES — covered as of 2026-05-03.

When EMAIL_REDIRECT_TO is set, the webhook worker short-circuits before the HTTP call. The delivery row is marked dead_letter with a human-readable reason so it's still visible in the deliveries listing. The SSRF guard remains in place independently.

4. WhatsApp / phone deep-links

Path: <a href="https://wa.me/..."> and <a href="tel:..."> in client / interest detail headers.

Safety: N/A — user-initiated only.

These are deep links the user explicitly clicks. No automated dispatch. A deep link click opens the user's WhatsApp / phone app, which is the intended interaction. No safety net needed.

5. SMS

Not implemented. The interests.preferredContactMethod enum includes 'sms' as a value but no sending path exists. If/when SMS is added (e.g. via Twilio), the new send function should respect EMAIL_REDIRECT_TO the same way sendEmail does — log the original number, drop the message, or reroute to a configurable SMS_REDIRECT_TO env.

---

Verification checklist before importing real data

• .env has EMAIL_REDIRECT_TO=<my-address> set.
• Restart dev server (or worker) so the new env is picked up — env vars are read at import time in some paths.
• Send a test email via pnpm tsx scripts/dev-trigger-portal-invite.ts or similar. Confirm subject is prefixed with [redirected from ...].
• Trigger an EOI send through the UI (any client). Confirm Documenso shows the redirect address as recipient (not the real client email).
• If any webhooks are configured, trigger an event that fires one and confirm the delivery is recorded as dead_letter with the "EMAIL_REDIRECT_TO is set" reason.
• Run the NocoDB migration --dry-run to count clients/interests; the --apply step is what creates real records but emails/webhooks are still gated by the redirect env.

Production cutover

When ready to go live:

1. Run a final dry-run of the data migration with EMAIL_REDIRECT_TO set to a sandbox address.
2. Verify the snapshot looks right (counts, client coverage).
3. Unset EMAIL_REDIRECT_TO in the production env.
4. Restart the app + worker.
5. Run the migration with --apply. From this point forward, real recipients will receive real comms.

If you ever need to re-pause outbound (e.g. handling a security incident, re-importing on top of existing data), set EMAIL_REDIRECT_TO again.