# Authenticated SMTP Configuration Guide

## Security requirements

In production, BCOS requires either TLS or SSL encryption and SMTP LOGIN authentication. `NONE` modes exist only to support isolated local testing and are rejected when `APP_ENV=production`.

The SMTP password is encrypted with libsodium and the application `APP_KEY`. The API never returns it after storage.

## Information required from the email provider

Obtain:

- SMTP hostname
- SMTP port
- Encryption mode: TLS or SSL
- SMTP username
- SMTP password or application-specific password
- Approved sender email
- Approved sender display name
- Optional reply-to email

Common arrangements are port 587 with STARTTLS or port 465 with implicit SSL, but the actual provider settings are authoritative.

## Recommended sender identity

```text
From name: Baffoe Consulting Management Company Limited
From email: an authenticated company mailbox on baffoes.com
Reply-to: a monitored company mailbox
```

The authenticated account should be authorized to send using the selected From address. Configure SPF, DKIM and DMARC through the email provider and DNS administrator before production launch.

## Test procedure

1. Save the configuration as inactive.
2. Enter a mailbox you can inspect as the test recipient.
3. Run the SMTP test.
4. Confirm delivery and inspect spam placement.
5. Confirm the From and Reply-To values.
6. Activate the configuration.
7. Queue a low-risk internal message.
8. Run the worker and inspect the delivery log.

## Failure handling

Temporary network and server failures are retried with increasing delays. Permanent SMTP failures and jobs exceeding the configured maximum attempts are marked `FAILED`. Administrators should investigate the logged SMTP response; credentials must never be copied into support tickets or screenshots.