Purpose

Kvary uses a provider-safe outbound email seam so transactional and system emails do not call Resend directly from business logic.

Current architecture

• Shared provider boundary: @kvary/mail-layer
• Auth emails: services/svc-auth/src/email/sender.ts
• Communication stack emails: apps/web/src/server/communication/infrastructure/adapters/emailAdapter.ts
• Communication diagnostics: apps/web/src/app/api/communication/test/route.ts

Server-only env

• RESEND_API_KEY
• RESEND_FROM_EMAIL
• RESEND_FROM_NAME optional
• RESEND_REPLY_TO optional
• RESEND_BASE_URL optional, defaults to https://api.resend.com

Web communication stack also accepts:

• EMAIL_MODE=DRY_RUN|LIVE
• EMAIL_PROVIDER=AUTO|RESEND|SENDMAIL

Initial rollout

• Auth account activation / password setup email
• Auth email verification
• Auth password reset
• Communication email channel for existing templates such as:
  • payment.failed
  • auction.starts.soon
  • subscription.welcome
  • subscription.confirm_email
  • system.admin_alert

How to add a new email type

1. Add or extend a normalized communication template under packages/core/communication/templates.ts
2. Add policy routing under packages/core/communication/policies.ts if needed
3. Dispatch through the communication layer or the auth sender boundary
4. Do not call Resend directly from domain/business code

Diagnostics

• GET /api/communication/test returns emailDiagnostics for admin/dev checks
• POST /api/communication/test with action=send_test_email sends a real test email through the communication layer

Local testing

Dry-run:

EMAIL_MODE=DRY_RUN npm --prefix apps/web run dev

Live:

EMAIL_MODE=LIVE \
EMAIL_PROVIDER=RESEND \
RESEND_API_KEY=... \
RESEND_FROM_EMAIL=notifications@kvary.network \
npm --prefix apps/web run dev

For auth:

RESEND_API_KEY=... \
RESEND_FROM_EMAIL=notifications@kvary.network \
npm --prefix services/svc-auth run dev

Deferred

• delivery webhooks
• retry workers / queue-backed retries
• bounce/suppression reconciliation
• audience/newsletter sync
• multi-provider routing policy beyond AUTO|RESEND|SENDMAIL