Application email (SMTP)

Application email sends invitations, password resets, verification emails, and notifications from your own mail server. Any SMTP provider works, such as Amazon SES, Postmark, Mailgun, SendGrid, Google Workspace, or your company relay.

Optional, but recommended. Without email, Helpin still works: invitations become copyable links, and password reset reports that email is unavailable.

Option 1: Configure in the app (recommended)

Server admins can set up email without touching the server.

Go to Settings → System status → Application email.
Enter the server, port, username, password, sender address, and security mode.
Select Save, then Send test email.

Changes apply immediately, without a restart. The password is stored encrypted and is never shown again or returned by the API.

Option 2: Configure with the CLI

helpin configure --dir /srv/helpin

The wizard asks for the host, port, TLS mode, username, password, and sender. Passwords are read without echo and saved only to your private .env.

For automation:

HELPIN_SMTP_PASSWORD="$(cat /run/secrets/smtp)" helpin configure --yes --dir /srv/helpin \
  --smtp-host smtp.example.com --smtp-username helpin --smtp-from "Helpin <help@example.com>"

Option 3: Environment variables

SMTP_HOST=smtp.example.com
SMTP_PORT=587
SMTP_USERNAME=helpin
SMTP_PASSWORD=your-password
SMTP_FROM=help@example.com
SMTP_TLS_MODE=starttls

Run helpin restart afterwards. While SMTP_* variables are set, the in-app settings are read-only and show the server's configuration. To manage email in the app again, remove the variables and restart.

Security modes

`SMTP_TLS_MODE`	Use it when
`starttls` (default)	Your provider uses port 587 with STARTTLS. This is the most common setup.
`tls`	Your provider uses implicit TLS, usually on port 465.
`none`	Only for an unauthenticated relay on a trusted local network.

Certificates are always verified. Authenticated delivery requires TLS and AUTH PLAIN. Servers that support only AUTH LOGIN aren't supported.

Test delivery

The Send test email button sends to your own address. You can also call the API:

POST /api/instance/email/test                 # server admins
POST /api/workspaces/{id}/email/test          # workspace admins

You can send at most one test every 30 seconds and five per hour. The email_outbound capability in helpin doctor shows ready only after a successful test of the current settings. Changing any setting requires a new test.

Require verified email addresses

Once email works, you can turn on verification:

AUTH_EMAIL_VERIFICATION_REQUIRED=true

New users then receive a verification email. The Approved email domains signup policy always requires a verified address, whatever this setting says.

Troubleshooting

Problem	Check
Test email fails with an authentication error	Username and password, and whether the provider needs an app-specific password
Connection times out	Port and firewall. Many clouds block outbound port 25, so use 587 or 465
TLS errors	`SMTP_TLS_MODE` matches the port, and the server presents a valid certificate
Mail sent but never arrives	The provider's delivery logs, and SPF, DKIM, and DMARC for your sender domain

Was this article helpful?