Skip to main content

Configure SMTP (CLI)

SMTP is the outbound email your deployment uses for user invitations and password resets. On a self-hosted deployment you configure it yourself, live, with no restart and no redeploy. Changes take effect on the very next email.

This guide assumes you have already installed and pointed the CLI at your deployment. If not, follow System Administration (CLI) first.

Prefer to set it at install time? On an on-premises Docker deployment you can also seed SMTP through the SMTP_* variables in .env while you set up the container, no CLI required. See Enable email notifications. Those env vars are the default layer; anything you set here with the CLI takes precedence over them, so the CLI is the right tool for a live change or a quick delivery test on a running deployment.

See what is currently set​

List the current email settings and where each value comes from:

da admin config list --group Email

The Source column tells you whether a value comes from the settings store (something you set), from an environment variable (the deployment default), or from a built-in default.

Set your mail server​

Use --secret for the password so it is prompted and never stored in your shell history:

da admin config set smtp.host smtp.your-provider.com
da admin config set smtp.port 587
da admin config set smtp.user your-smtp-username
da admin config set smtp.password --secret
da admin config set smtp.from no-reply@your-company.com

Send a test email​

Always confirm the configuration works before relying on it:

da admin config test-email you@your-company.com

Once SMTP is configured, the app enables email invitations and password resets automatically.

Revert a setting​

To drop a value you set and fall back to the deployment default, use unset:

da admin config unset smtp.from

Troubleshooting SMTP​

  • test-email fails: the message shown carries the SMTP error (authentication, a blocked port, or a wrong host). Fix the offending setting and test again.
  • Cannot store the SMTP password (encryption not configured): your deployment needs a CREDENTIAL_ENCRYPTION_KEY to store secrets at rest. Contact us, or set it in your deployment configuration; non-secret settings still work without it.
  • Invitations or password resets still disabled in the app: the app enables them once smtp.host resolves. Confirm with da admin config get smtp.host, then send a test email.

For connection or authentication errors with the CLI itself (401, 403, timeouts), see Troubleshooting the CLI.