learning_ai_common_plat/services/platform-service/POSTAL_SMTP_SETUP.md

Postal SMTP Setup

Use Postal as the long-term outbound email backend for platform-service.

Architecture

platform-service owns:

• email templates
• auth-triggered email events
• delivery logs
• SMTP submission

Postal owns:

• SMTP/API delivery
• outbound queueing
• bounce and reputation handling
• domain signing and mail-server operations

platform-service should talk to Postal over SMTP. No separate ByteLyst email relay is needed.

Environment

Set these variables for platform-service:

EMAIL_PROVIDER=smtp
EMAIL_FROM_ADDRESS=noreply@your-domain.com
EMAIL_FROM_NAME=ByteLyst
SMTP_HOST=postal.your-domain.internal
SMTP_PORT=587
SMTP_SECURE=false
SMTP_USER=your-postal-smtp-username
SMTP_PASSWORD=your-postal-smtp-password

Use SMTP_SECURE=true only if your Postal endpoint expects implicit TLS, typically on port 465.

Postal Mapping

Create one SMTP credential in Postal for the sender/server you want platform-service to use.

Map the values like this:

• SMTP_HOST: Postal SMTP host
• SMTP_PORT: Postal submission port
• SMTP_USER: Postal SMTP username
• SMTP_PASSWORD: Postal SMTP password
• EMAIL_FROM_ADDRESS: verified sender address or domain-backed sender

Operational Notes

• Keep EMAIL_PROVIDER=console for local development if you do not want real delivery.
• Use a local SMTP catcher such as Mailpit only for development inbox inspection.
• For production, Postal still requires DNS and mail operations outside this repo: SPF, DKIM, DMARC, reverse DNS, and clean outbound IP reputation.

Current Repo Wiring

The SMTP delivery path is implemented in:

• src/modules/delivery/channels/email.ts
• src/modules/delivery/dispatcher.ts
• src/modules/delivery/subscribers.ts
• src/server.ts

Auth-driven flows such as password reset and email verification now depend on the delivery subscribers being registered at service startup.