Email & SMTP
Configure the SMTP transport that delivers verification and password-reset email. In deployed environments the verification email gates sign-in, so a misconfigured transport blocks every new sign-up. Oxagen logs that failure where you can find it.
Why this matters
In deployed environments, email verification is required. Every new account must click an emailed verification link before it can sign in. SMTP delivers that link. If the SMTP transport is missing or misconfigured in production, Oxagen never sends the verification email, and those people cannot finish signing in.
Oxagen also sends email for password resets over the same transport.
Required environment variables
Set all of the following to turn on transactional email. The schema marks them optional (not every service sends mail), but if any are missing the transport refuses to build and logs an error naming the gap.
| Variable | Required | Description |
|---|---|---|
SMTP_HOST | Yes | SMTP server hostname (for example, smtp.postmarkapp.com). |
SMTP_PORT | Yes | SMTP server port. 465 uses implicit TLS. Other ports (for example, 587) use STARTTLS. |
SMTP_USERNAME | Yes | SMTP auth username. |
SMTP_PASSWORD | Yes | SMTP auth password or API token. |
SMTP_FROM_EMAIL | Yes | The From: address on outgoing mail (must be a verified sender on your provider). |
SMTP_FROM_NAME | No | Optional display name shown beside the from address. |
TLS behavior
- Port
465: the transport opens an implicit TLS connection immediately. - Any other port (commonly
587): the transport upgrades the connection with STARTTLS and requires TLS. It never delivers in plaintext.
Failures are logged
The auth layer has to answer right away, so it sends verification and password-reset email in the background instead of waiting on it. A background send that fails still leaves a record:
- Background sends go through a helper that logs every send failure with the
purpose(verificationorpassword-reset) and the recipient. Search your logs forsendEmail failed (fire-and-forget)to find delivery failures. - A startup or health probe can call
isEmailTransportConfigured()to catch a deployed environment that would drop every transactional email, so you find the misconfiguration before a new member does.
Local development
Email verification is disabled locally (see Local development),
so you do not need the SMTP_* variables to sign up and sign in on your machine.
Set them locally only to exercise the real delivery path.
Verifying your configuration
After you set the variables in a deployed environment:
- Trigger a sign-up (or password reset) for a test address.
- Confirm the email arrives, or check the logs for
sendEmail failed (fire-and-forget). - If the transport is unconfigured, the error names the missing
SMTP_*keys.
Environments & secrets
Scope secret values per environment: encrypted vault keys with per-environment overrides.
Local development
How Oxagen detects a developer machine through OXAGEN_LOCAL_DEV and relaxes deployed-only controls the same way every time, and which signals must stay out of deployment configuration.