Sign in to fill these examples with your own keys. Sign in Start free trial

Send emails with Discourse

Point Discourse's SMTP settings at PostShiba.

What you'll build

A self-hosted Discourse forum that sends its sign-up confirmations, password resets, notifications, and summary emails through PostShiba over SMTP.

Before you start

  • A Transactional cluster. Forum notification mail belongs on a transactional cluster, and the type is locked after create. See Clusters.
  • An SMTP username and password. Open your cluster in the dashboard, go to its SMTP credentials, and choose Create SMTP credential. Copy the password right away, because it is shown once. You can also use the SMTP credentials API.
  • A verified sending domain. See Add and verify a domain. The notification email address must be on it.
  • A cluster that is ready to send (sending_ready is true).
  • Shell access to a standard Docker install of Discourse, so you can edit /var/discourse/containers/app.yml.

Install

Nothing to install. Discourse has SMTP support built in.

Send your first email

  1. Open /var/discourse/containers/app.yml and set these keys in the env section. Keep the other keys as they are. Port 587 with DISCOURSE_SMTP_ENABLE_START_TLS set to true upgrades the connection with STARTTLS. Leave DISCOURSE_SMTP_FORCE_TLS unset, because it is for port 465.
app.yml
1env: 2 DISCOURSE_SMTP_ADDRESS: smtp.postshiba.com 3 DISCOURSE_SMTP_PORT: 587 4 DISCOURSE_SMTP_USER_NAME: smtp_9 5 DISCOURSE_SMTP_PASSWORD: "YOUR_PASSWORD" 6 DISCOURSE_SMTP_ENABLE_START_TLS: true 7 DISCOURSE_SMTP_AUTHENTICATION: plain 8 DISCOURSE_NOTIFICATION_EMAIL: hello@mail.example.com

Keep the password in double quotes. A # outside quotes starts a YAML comment. DISCOURSE_NOTIFICATION_EMAIL sets the From address and locks the notification email site setting to it.

You can also run ./discourse-setup from /var/discourse. It asks for the SMTP server address, port, user name, password, and notification email address, then writes them to app.yml.

  1. Rebuild the container so Discourse reads the new settings.
rebuild.sh
1cd /var/discourse 2./launcher rebuild app
  1. Sign in as an admin and open /admin/email/server-settings. Enter your own address and select Send test email. The message shows under Events in the PostShiba dashboard.

Every SMTP setting is on Send emails with SMTP.

Troubleshooting

Discourse emails activity summaries to members who have not visited recently, weekly by default. On a large forum, summaries add up to many messages on top of notifications. Size the cluster so its 24-hour cap covers them. When a cap is full, SMTP answers 451 4.7.0 hourly send limit reached or 451 4.7.0 daily send limit reached and does not keep the message. Select Resize on the cluster page if you need more room. See What happens at your cap.

Discourse handles bounces with a VERP return address that it reads by POP3 or direct-delivery incoming mail. With PostShiba, the return path is PostShiba's, so bounces come back to PostShiba and do not show under bounced emails in Discourse. PostShiba suppresses addresses that hard bounce or report spam. Later sends to them are refused with 550 suppressed.

What you see in the Discourse log What to do
Authentication fails Check DISCOURSE_SMTP_USER_NAME and DISCOURSE_SMTP_PASSWORD, and set DISCOURSE_SMTP_AUTHENTICATION to plain. PostShiba accepts AUTH PLAIN only. Rebuild after each change.
550 unverified domain or 550 from header not aligned with verified domain Set DISCOURSE_NOTIFICATION_EMAIL to an address on your verified domain. If the reply by email address site setting contains +, Discourse sends from that address as the envelope sender, so it must be on your verified domain too.
550 domain_suspended The From domain is paused. Resume it from Managing domains.
550 kyc_required Your team is pending production approval. Until then, send only to team members, live inbox addresses, and inbox forward-to addresses. See Does PostShiba require production approval?.
550 suppressed or 550 firewall: <rule> The recipient is on the suppression list or failed an email firewall check.
451 4.7.0 hourly send limit reached or 451 4.7.0 daily send limit reached The cluster is at its cap and did not keep the message. Retry later, or resize the cluster.

Next steps