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

Send emails with Forgejo

Point Forgejo's mailer at PostShiba.

What you'll build

A self-hosted Forgejo instance that sends its notification mail, such as registration confirmations, password resets, and issue and pull request notifications, through PostShiba over SMTP. Use a Transactional cluster for this mail.

Before you start

  • 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 FROM address must be on it.
  • A cluster that is ready to send (sending_ready is true). See Clusters.
  • Access to Forgejo's app.ini, or to the container environment for a Docker install.

Install

Nothing to install. Forgejo has SMTP support built in.

Send your first email

  1. Set the [mailer] section in app.ini. PROTOCOL = smtp+starttls on port 587 upgrades the connection with STARTTLS. Wrap the password in backticks if it has special characters. The keys follow Forgejo's config cheat sheet.
app.ini
1[mailer] 2ENABLED = true 3FROM = "Forgejo <hello@mail.example.com>" 4PROTOCOL = smtp+starttls 5SMTP_ADDR = smtp.postshiba.com 6SMTP_PORT = 587 7USER = smtp_9 8PASSWD = `YOUR_PASSWORD` 9FORCE_TRUST_SERVER_CERT = false

Keep FORCE_TRUST_SERVER_CERT at false so Forgejo checks the server certificate. Leave ENVELOPE_FROM unset, so the envelope sender is the FROM address. Forgejo has no auth-method setting. It picks one from what the server offers and uses AUTH PLAIN with PostShiba.

To keep the password out of app.ini, replace PASSWD with PASSWD_URI pointing at a file, such as PASSWD_URI = file:/etc/forgejo/mailer_passwd. Set one or the other, not both.

  1. To mail issue and pull request notifications, set ENABLE_NOTIFY_MAIL = true in the [service] section. To make new users confirm their address, set REGISTER_EMAIL_CONFIRM = true there too.

  2. Restart Forgejo so it reloads the config. On a systemd install:

restart.sh
1sudo systemctl restart forgejo
  1. In Forgejo, go to Site administration → Configuration → Summary. Under Mailer configuration, enter your address in Send test email and choose Send. The message goes through PostShiba and shows under Events in the dashboard.

Every SMTP setting is on Send emails with SMTP.

Docker

The Forgejo container image reads FORGEJO__<section>__<KEY> environment variables into app.ini on container startup. Set the same keys in docker-compose.yml, then run docker compose up -d to recreate the container.

docker-compose.yml
1services: 2 server: 3 environment: 4 - FORGEJO__mailer__ENABLED=true 5 - FORGEJO__mailer__FROM=hello@mail.example.com 6 - FORGEJO__mailer__PROTOCOL=smtp+starttls 7 - FORGEJO__mailer__SMTP_ADDR=smtp.postshiba.com 8 - FORGEJO__mailer__SMTP_PORT=587 9 - FORGEJO__mailer__USER=smtp_9 10 - FORGEJO__mailer__PASSWD=YOUR_PASSWORD

Troubleshooting

When the cluster reaches its hourly throttle or 24-hour cap, 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. Retry once the cap has room. See What happens at your cap.

What the test email or Forgejo log shows What to do
SMTP server does not support AUTH, but credentials provided Forgejo did not start TLS. Set PROTOCOL = smtp+starttls and SMTP_PORT = 587.
failed to authenticate SMTP Check USER and PASSWD. Wrap the password in backticks if it has special characters.
454 4.7.0 too many failed logins, try again later Too many wrong passwords. Fix PASSWD, then try again.
failed to start TLS connection with a certificate error Check that SMTP_ADDR is smtp.postshiba.com. Keep FORCE_TRUST_SERVER_CERT = false.
550 unverified domain or 550 from header not aligned with verified domain Set FROM to an address on your verified domain, and leave ENVELOPE_FROM unset.
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 Production approval.
550 suppressed or 550 firewall: <rule> The recipient is on the suppression list or failed an email firewall check.
Test email arrives, but no issue or pull request notifications Set ENABLE_NOTIFY_MAIL = true in [service] and restart Forgejo.

Next steps