Email delivery
Facet sends email for the credential flows: password reset, invites, first credentials, and multi-factor setup links. Delivery goes through one mail adapter. The default adapter prints email to stdout. Production requires real delivery over SMTP. In-app notifications are a separate system that never uses email.
When to use this
Section titled “When to use this”Configure email when:
- You set up SMTP for a new install.
- You move an install from stdout delivery to a relay.
- You change the sender address without a restart.
Before you start
Section titled “Before you start”- You have an SMTP relay account: host, port, username, password.
- You know the
APP_ENVof the deployment. - The
mail:keys are hot keys. A settings save overrides the file without a restart — see System settings.
1. Set the mail section
Section titled “1. Set the mail section”Put the SMTP values in config.{env}.yml:
mail: adapter: smtp from_address: no-reply@your-company.tld from_name: Facet smtp: host: smtp.example.tld port: 587 username: relay-user password: !env FACET_SMTP_PASSWORD use_tls: trueThe keys and their defaults:
| Key | Default | Meaning |
|---|---|---|
mail.adapter |
dev |
dev prints to stdout. smtp delivers. |
mail.from_address |
no-reply@facet.local |
The sender address. |
mail.from_name |
Facet |
The sender display name. |
mail.smtp.host |
localhost |
The relay host. |
mail.smtp.port |
587 |
The relay port. |
mail.smtp.username |
none | The relay user, when the relay asks for one. |
mail.smtp.password |
none | The relay password. Use !env to keep it out of the file. |
mail.smtp.use_tls |
true |
Use TLS towards the relay. |
2. Pass the production gate
Section titled “2. Pass the production gate”The boot refuses adapter: dev when APP_ENV=production and the file does
not set the escape hatch. The error names the exact keys for both paths:
- Set
mail.adapter: smtpwith themail.smtp.*keys — the normal path. - Or set
mail.allow_dev_adapter_in_production: true— the air-gapped path. Email stays on stdout.
The same gate runs at write time. A runtime save that switches the effective
adapter to dev under APP_ENV=production is refused, unless the file sets
the same hatch. The hatch itself stays file-only.
3. Change values without a restart
Section titled “3. Change values without a restart”The mail.* keys are hot. Pin them on the
Configure → Platform → Settings page, or save the settings document:
curl -k -X PATCH -H "Authorization: Bearer $FACET_API_KEY" \ -H "Content-Type: application/json" \ -d '{"mail": {"from_address": "no-reply@your-company.tld"}}' \ "https://facet.localhost:3443/Api/core/SystemSettings/settings"A settings save rebuilds the adapter, so the next email uses the new values.
The write gate checks the merged state: mail.adapter: smtp needs a
non-null mail.smtp.host.
4. Test delivery
Section titled “4. Test delivery”Drive a password reset from the sign-in page. The reset link arrives by
email only, so a delivered email proves the whole path: adapter, relay,
sender address, and link TTL. The link TTL is
iam.change_password_expiration, 24 hours by default.
Example
Section titled “Example”An air-gapped install that must keep stdout delivery, with the hatch set:
mail: adapter: dev allow_dev_adapter_in_production: true from_address: no-reply@your-company.tld from_name: FacetEvery email prints to stdout. Pair this with an operator flow that watches the backend logs, because password-reset and invite links never reach an inbox.
Troubleshooting
Section titled “Troubleshooting”The boot fails with a mail adapter error.
Production refuses the dev adapter without the hatch. Follow the two
paths in the error message, or see step 2.
Email does not arrive.
Check the backend logs for the send attempt. Then check the relay: wrong
port, use_tls: false against a TLS-only relay, and relay authentication
failures are the common causes. Drive a password reset to re-test.
A runtime save of the adapter is refused.
The write gate needs a non-null mail.smtp.host when the adapter is
smtp, and refuses dev in production without the file hatch.
The new sender address does not apply.
A pinned value wins over the file. Check the pins on the settings page, or save the new value through the settings document.
The reset link is expired.
The link TTL is iam.change_password_expiration, 86,400 seconds by
default. Request a fresh link.
Related
Section titled “Related”- Configuration files — where the
mail:section lives. - System settings — the runtime tier that overrides the file.
- In-app notifications — the separate notification system.
- Sessions, tokens and lockouts — the link TTLs and the lockout rules.
- Bootstrap and CLI tasks —
seed:admin, which prints its password instead of emailing it. - Internals on GitHub: config.md, system-settings.md.