Email delivery

Email is off by default. Without it, pfCentral shows invite and reset links once, and an admin passes them on by hand. With it on, pfCentral also emails the link to the person, retries if delivery fails, and still shows the link once as a fallback.

pfCentral only sends two kinds of mail: member invites and password resets. It sends no alerts.

Turn it on

Pick a transport.
- SMTP: any relay you already run. The right choice for on-premises and air-gapped installs.
- Resend or Cloudflare Email Service: HTTPS APIs, for installs with internet access.
Verify the sender domain with your relay or provider and publish its SPF, DKIM and DMARC records. pfCentral does not sign mail itself.
Generate an encryption key. Queued links are encrypted at rest with it.
Terminal window
```
openssl rand -base64 32
```
Store it with your other secrets and back it up. If it changes, queued emails cannot be decrypted and their links must be issued again.
Set the public URL. PFCENTRAL_SERVER_BASE_URL must be the address people can open, such as https://pf.example.com. Emailed links use it as is.
Add the settings for your transport and restart:
PFCENTRAL_EMAIL_ENABLED=true PFCENTRAL_EMAIL_ENCRYPTION_KEY=<from step 2> PFCENTRAL_EMAIL_FROM=no-reply@example.com PFCENTRAL_EMAIL_FROM_NAME=pfCentral PFCENTRAL_EMAIL_PROVIDER=smtp PFCENTRAL_EMAIL_SMTP_HOST=smtp.example.com PFCENTRAL_EMAIL_SMTP_PORT=587 PFCENTRAL_EMAIL_SMTP_TLS=starttls # or implicit (port 465) PFCENTRAL_EMAIL_SMTP_AUTH=plain # plain, login or none PFCENTRAL_EMAIL_SMTP_USERNAME=pf-central PFCENTRAL_EMAIL_SMTP_PASSWORD=<relay password>
For an internal relay without authentication, set PFCENTRAL_EMAIL_SMTP_AUTH=none.
PFCENTRAL_EMAIL_ENABLED=true PFCENTRAL_EMAIL_ENCRYPTION_KEY=<from step 2> PFCENTRAL_EMAIL_FROM=no-reply@example.com PFCENTRAL_EMAIL_PROVIDER=resend PFCENTRAL_EMAIL_RESEND_API_KEY=re_…
PFCENTRAL_EMAIL_ENABLED=true PFCENTRAL_EMAIL_ENCRYPTION_KEY=<from step 2> PFCENTRAL_EMAIL_FROM=no-reply@example.com PFCENTRAL_EMAIL_PROVIDER=cloudflare PFCENTRAL_EMAIL_CLOUDFLARE_ACCOUNT_ID=… PFCENTRAL_EMAIL_CLOUDFLARE_API_TOKEN=…
The sending domain must use Cloudflare DNS. Cloudflare’s SMTP endpoint (smtp.mx.cloudflare.net:465, user api_token) also works with the SMTP provider and PFCENTRAL_EMAIL_SMTP_TLS=implicit.
The server checks the settings at start. A missing key, From address or credential stops it with an error instead of silently queueing mail.

Check it

The start-up log contains notification worker started provider=smtp (or your provider).
Invite a test member. The Members page still shows the link, and the email arrives.
If it does not arrive, look for the notification.failed audit event and the error in the server log.

How delivery works

 invite / reset ──▶ notifications table (link encrypted) ──▶ worker ──▶ SMTP / API
                         pending → sending → accepted                │
                                     ▲            └── failed ◀───────┘ after 5 tries
                                     └──────── retry 1m, 5m, 15m, 1h, 4h

PostgreSQL is the queue. With several replicas, each email is still sent once.
Network errors, 4xx and 429 answers are retried. Permanent errors fail at once.
Accepted means the provider took the message, not that it reached the inbox.
Finished rows are deleted after PFCENTRAL_EMAIL_RETENTION (default 30 days).

Firewall rules for the server

Transport	Allow outbound
SMTP with STARTTLS	TCP 587 to the relay
SMTP with implicit TLS	TCP 465 to the relay
Resend	HTTPS to `api.resend.com`
Cloudflare	HTTPS to `api.cloudflare.com`