---
title: "Set up Discourse email over SMTP"
description: "DISCOURSE_SMTP_* in containers/app.yml, a rebuild, then Send test email from the admin Emails page."
url: https://www.unitpost.com/docs/smtp/discourse
section: SMTP
updated: 2026-11-02
---
# Set up Discourse email over SMTP

## Connection settings

- **Host**: smtp.unitpost.com
- **Username**: unitpost (always this literal value)
- **Password**: Your Unitpost API key (must carry emails:send)
- **Port (STARTTLS)**: 587 (or 2587 if blocked, or 25)
- **Port (implicit TLS)**: 465 (or 2465 if blocked)
- **Security**: TLS 1.2 or 1.3 (required before AUTH)
- **From address**: Any address on a verified domain

## Set up Discourse email over SMTP

> DISCOURSE_SMTP_* in containers/app.yml, a rebuild, then Send test email from the admin Emails page.

Discourse uses outgoing mail to validate new accounts and to send notifications and digests. A standard install reads `DISCOURSE_SMTP_*` from `/var/discourse/containers/app.yml`, and the port defaults to 25 unless you set it. The From address defaults to `noreply@` plus your forum's hostname, so either verify that hostname or set `DISCOURSE_NOTIFICATION_EMAIL`.

### 1. Create a send-only key

In Unitpost, open Settings → SMTP and create a send-only key, then verify the domain (/docs/domains) your notification address uses.

### 2. Edit containers/app.yml

Under `env:`, set the SMTP keys. Discourse uses STARTTLS by default, so port 587 needs nothing more. For port 465, set `DISCOURSE_SMTP_PORT: 465` and `DISCOURSE_SMTP_FORCE_TLS: true`; Discourse turns STARTTLS off by itself when implicit TLS is forced.

```yaml
env:
  # ...your existing keys
  DISCOURSE_SMTP_ADDRESS: smtp.unitpost.com
  DISCOURSE_SMTP_PORT: 587
  DISCOURSE_SMTP_USER_NAME: unitpost
  DISCOURSE_SMTP_PASSWORD: "pk_live_..."
  DISCOURSE_NOTIFICATION_EMAIL: noreply@yourdomain.com
```

> Keep the password in quotes: the sample file warns that a `#` in an unquoted value can be misread.

### 3. Rebuild the container

Changes to `app.yml` only apply after a rebuild, which takes the forum offline while it runs.

```bash
cd /var/discourse
./launcher rebuild app
```

### 4. Send a test email

In the admin panel, open Emails (`/admin/email`), enter your address in the test field and click Send test email. On the server, `./discourse-doctor` checks the mail configuration too.

### 5. If the test fails

A `Net::ReadTimeout` on port 465 usually means `DISCOURSE_SMTP_FORCE_TLS` is missing. `535 5.7.8` means `DISCOURSE_SMTP_USER_NAME` isn't `unitpost`. `550 5.7.1` means the From domain isn't verified.

## Related

- [Configure Mastodon to send email over SMTP](https://www.unitpost.com/docs/smtp/mastodon): SMTP_* in .env.production with SMTP_ENABLE_STARTTLS=always on 587, then restart Sidekiq.
- [Nextcloud SMTP settings for the email server](https://www.unitpost.com/docs/smtp/nextcloud): Basic settings → Email server or the mail_* keys in config.php; the From address is split in two.
- [Configure Directus email over SMTP](https://www.unitpost.com/docs/smtp/directus): EMAIL_TRANSPORT=smtp and EMAIL_SMTP_* variables; EMAIL_SMTP_SECURE means port 465, not STARTTLS.