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.

Set the application URL as well. SMTP only decides that an email is delivered. The links inside invitations and password resets are built from the application URL, and if that is not set they point at the wrong host, so recipients cannot click through. Configure both together: Configure the application URL.

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

Use whatever host, port and credentials your mail provider gave you. Encryption is chosen automatically from the port, so there is nothing else to set: port 465 is encrypted from the moment it connects, and every other port connects and then upgrades. Both are secure.

If your mail server needs something different

Rare, and only worth touching if a send fails. smtp.security accepts:

Value	Behaviour
auto	Default. Picks the right mode from the port.
ssl	Always encrypt from the start, for a server using a non-standard port for it.
starttls	Always connect first and then upgrade.
none	No encryption. Only for a trusted server on a private network.

da admin config set smtp.security none

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.

Next, check that the links inside that email point at your deployment. If they do not, set the application URL.

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.
• test-email reports that the server does not offer STARTTLS: the server will not encrypt the connection on that port. Check with your provider whether they offer port 465 instead, or, if it is a trusted server on a private network, allow an unencrypted connection with da admin config set smtp.security none.
• test-email times out: the deployment cannot reach your mail server on that port at all. This is a network path problem, such as a firewall rule or an outbound restriction on SMTP ports, rather than a settings problem, so re-entering the credentials will not help. An authentication or relay error points at a setting; a timeout points at the network.
• Emails arrive but their links point at the wrong address: the application URL is not set. See Configure the application URL.
• 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.