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

Send emails with Gitea

Point Gitea's mailer at PostShiba.

What you'll build

A self-hosted Gitea 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 Gitea's app.ini, or to the container environment for a Docker install. The keys here are for Gitea 1.18 and later.

Install

Nothing to install. Gitea 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 Gitea's config cheat sheet.
app.ini
1[mailer] 2ENABLED = true 3FROM = "Gitea <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 Gitea checks the server certificate. Leave ENVELOPE_FROM unset, so the envelope sender is the FROM address. Gitea has no auth-method setting. It picks one from what the server offers and uses AUTH PLAIN with PostShiba.

  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 Gitea so it reloads the config. On a systemd install:

restart.sh
1sudo systemctl restart gitea
  1. In Gitea, go to Site Administration → Configuration → Summary. Under Mailer Configuration, enter your address in Send Testing 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 official Gitea image reads GITEA__<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 - GITEA__mailer__ENABLED=true 5 - GITEA__mailer__FROM=hello@mail.example.com 6 - GITEA__mailer__PROTOCOL=smtp+starttls 7 - GITEA__mailer__SMTP_ADDR=smtp.postshiba.com 8 - GITEA__mailer__SMTP_PORT=587 9 - GITEA__mailer__USER=smtp_9 10 - GITEA__mailer__PASSWD=YOUR_PASSWORD

To keep the password out of the compose file, append __FILE to the name and point it at a file, such as a Docker secret: GITEA__mailer__PASSWD__FILE=/run/secrets/smtp_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 Gitea log shows What to do
SMTP server does not support AUTH, but credentials provided Gitea 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 Gitea.

Next steps