---
title: "Set up SMTP for self-hosted Sentry"
description: "mail.* keys in config.yml, SENTRY_MAIL_HOST for the From domain, and a test from the admin Mail page."
url: https://www.unitpost.com/docs/smtp/sentry
section: SMTP
updated: 2026-11-02
---
# Set up SMTP for self-hosted Sentry

## 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 SMTP for self-hosted Sentry

> mail.* keys in config.yml, SENTRY_MAIL_HOST for the From domain, and a test from the admin Mail page.

Self-hosted Sentry emails issue alerts, weekly reports and the links that verify a user's email address. Outbound mail comes from the `mail.*` keys in `sentry/config.yml`, which point at the bundled `smtp` relay container until you change `mail.host`. The catch: `sentry/sentry.conf.py` builds `mail.from` from `SENTRY_MAIL_HOST`, and that wins over anything you put in `config.yml`.

### 1. Create a send-only key

In Unitpost, open Settings → SMTP and create a send-only key. Copy it now; it's shown once. Mail goes out as `sentry@` plus the domain in `SENTRY_MAIL_HOST`, so that domain must be verified (/docs/domains).

### 2. Set the From domain in .env

`sentry/sentry.conf.py` sets `mail.from` to `sentry@` plus `SENTRY_MAIL_HOST`. Set that variable in the `.env` at the root of your self-hosted checkout to your verified domain.

```env
SENTRY_MAIL_HOST=yourdomain.com
```

> Want another address, such as `alerts@yourdomain.com`? Delete the `mail.list-namespace` and `mail.from` lines under `# Mail #` in `sentry/sentry.conf.py`, then set `mail.from` in `config.yml`.

### 3. Point mail.* at Unitpost

In `sentry/config.yml`, replace `mail.host: 'smtp'` (the bundled relay) and uncomment the connection keys. `mail.use-tls` is STARTTLS on port 587 and `mail.use-ssl` is implicit TLS on 465. The file warns they must not appear together, so uncomment only one.

```yaml
mail.backend: 'smtp'
mail.host: 'smtp.unitpost.com'
mail.port: 587
mail.username: 'unitpost'
mail.password: 'pk_live_...'
mail.use-tls: true
```

> For port 465, set `mail.port: 465` and `mail.use-ssl: true`, and leave `mail.use-tls` commented out.

### 4. Rebuild and restart

The containers read `.env` and `config.yml` when they start. Re-run the installer from your self-hosted checkout; it rebuilds and restarts them.

```bash
./install.sh
```

### 5. Send a test from the admin Mail page

As a superuser, open `/manage/status/mail/` on your instance. SMTP Settings lists the host, port, username and STARTTLS or SSL flag that loaded. Under Test Settings, the Send a test email button mails your own account address; find it in Unitpost Emails.

### 6. If the test fails

`535 5.7.8 Username must be 'unitpost'` means `mail.username` holds an email address. `550 5.7.1` means the From domain isn't verified, so check `SENTRY_MAIL_HOST`. A hang on port 465 usually means `mail.use-tls` is set where `mail.use-ssl` belongs.

## Related

- [Configure GitLab to send email over SMTP](https://www.unitpost.com/docs/smtp/gitlab): gitlab_rails['smtp_*'] in /etc/gitlab/gitlab.rb, a reconfigure, then Notify.test_email in the Rails console.
- [Configure Ghost transactional email over SMTP](https://www.unitpost.com/docs/smtp/ghost): mail.transport SMTP in config.production.json for staff invites, password resets and member login links.
- [Keycloak SMTP settings for realm email](https://www.unitpost.com/docs/smtp/keycloak): Realm settings → Email: host, port, Enable StartTLS for 587, then Test connection to your own address.