Skip to main content

Email delivery

This page explains how to configure outbound email for Better Comply.

Who this is for

Operators setting up a deployment. Email is used for the weekly supervisor digest and, if configured, other operational notifications.

Email provider options​

Better Comply supports two email providers:

ProviderWhen to use
resendProduction - sends real email via the Resend HTTPS API.
consoleLocal development and preview - logs the message to the server console. No email is sent.

Auto-detection​

You do not need to set EMAIL_PROVIDER explicitly. The backend resolves it at startup:

  • If EMAIL_API_KEY is set to a non-empty value: use resend.
  • Otherwise: use console.

This means a missing API key is never a hard failure - the supervisor report scan will run and log what it would have sent, rather than crashing.

To force a specific provider, set EMAIL_PROVIDER=resend or EMAIL_PROVIDER=console explicitly. This overrides the auto-detection.

Configuring Resend​

  1. Create an account at resend.com and generate an API key.
  2. Add and verify a sending domain in the Resend dashboard.
  3. Set the following environment variables on your Cloud Run service:
EMAIL_PROVIDER=resend
EMAIL_API_KEY=re_xxxxxxxxxxxxxxxxxxxx
EMAIL_FROM_ADDRESS=no-reply@your-domain.example
EMAIL_FROM_NAME=Better Comply
APP_BASE_URL=https://app.your-domain.example

APP_BASE_URL is optional but recommended - it populates the "View your team" link in the supervisor digest email.

See Environment variables for the full variable reference.

The console fallback​

When EMAIL_PROVIDER=console (or no key is set), the email client logs a structured representation of each message to the server's standard output instead of sending it. This is useful for:

  • Local development where you want to inspect what would be sent.
  • Preview / staging environments where you do not want to deliver real email.

You can observe these log lines in Cloud Logging if you deploy to Cloud Run with the console provider in a non-production environment.

What emails are sent​

Currently the only outbound email path is the weekly supervisor digest, triggered by the POST /v1/supervisor-report-scan endpoint. See Scheduled jobs for the cadence and setup.

The digest:

  • Is sent to each team lead and line lead.
  • Contains their direct reports' training completion status for the current period.
  • Includes a link back to the Reports page in the application (requires APP_BASE_URL).
  • Is scoped strictly to the supervisor's own team - a supervisor never sees another team's data.

Emailless or pseudonymous supervisors (those using the PIN-based login without an email address) are skipped gracefully. A skipped recipient is recorded in report_deliveries as skipped_no_email and does not cause the rest of the batch to abort.

Deliverability notes​

  • Verify your sending domain in Resend to avoid spam filtering.
  • The From address must match a domain you have verified in Resend.
  • Each send is recorded in the report_deliveries table with an outcome code, making it auditable without relying on Resend's dashboard.