# 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`:

```env
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.