---
title: "Configure GitLab to send email over SMTP"
description: "gitlab_rails['smtp_*'] in /etc/gitlab/gitlab.rb, a reconfigure, then Notify.test_email in the Rails console."
url: https://www.unitpost.com/docs/smtp/gitlab
section: SMTP
updated: 2026-11-02
---
# Configure GitLab to send 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

## Configure GitLab to send email over SMTP

> gitlab_rails['smtp_*'] in /etc/gitlab/gitlab.rb, a reconfigure, then Notify.test_email in the Rails console.

Self-managed GitLab (Linux package) sends notifications, password resets and confirmations with the `gitlab_rails['smtp_*']` keys in `/etc/gitlab/gitlab.rb`. The common mistake is turning on both TLS flags: `smtp_enable_starttls_auto` is for 587, `smtp_tls` is for 465, and setting both to `true` fails with `:enable_starttls and :tls are mutually exclusive`.

### 1. Create a send-only key

In Unitpost, open Settings → SMTP and create a send-only key. GitLab sends as `gitlab_email_from`, so pick that address on a verified domain (/docs/domains).

### 2. Add the SMTP block to gitlab.rb

Edit `/etc/gitlab/gitlab.rb` on the GitLab server. For port 587, keep `smtp_enable_starttls_auto` on and `smtp_tls` off.

```ruby
gitlab_rails['smtp_enable'] = true
gitlab_rails['smtp_address'] = "smtp.unitpost.com"
gitlab_rails['smtp_port'] = 587
gitlab_rails['smtp_user_name'] = "unitpost"
gitlab_rails['smtp_password'] = "pk_live_..."
gitlab_rails['smtp_domain'] = "yourdomain.com"
gitlab_rails['smtp_authentication'] = "login"
gitlab_rails['smtp_enable_starttls_auto'] = true
gitlab_rails['smtp_tls'] = false
gitlab_rails['smtp_openssl_verify_mode'] = 'peer'

gitlab_rails['gitlab_email_from'] = 'gitlab@yourdomain.com'
gitlab_rails['gitlab_email_reply_to'] = 'noreply@yourdomain.com'
```

> For port 465, set `smtp_port` to `465`, `smtp_tls` to `true` and `smtp_enable_starttls_auto` to `false`.

### 3. Reconfigure GitLab

Changes in `gitlab.rb` apply only after a reconfigure.

```bash
sudo gitlab-ctl reconfigure
```

### 4. Send a test from the Rails console

Open the console with `sudo gitlab-rails console`, then send a message with `Notify.test_email`. A failure prints the SMTP error right there; a success shows up in Unitpost Emails.

```ruby
Notify.test_email('you@example.com', 'Unitpost SMTP test', 'Sent from GitLab').deliver_now
```

### 5. If it fails

In the same console, `ActionMailer::Base.smtp_settings` shows what GitLab loaded. `535 5.7.8` means `smtp_user_name` isn't `unitpost`. `550 5.7.1` means `gitlab_email_from` isn't on a verified domain. The `mutually exclusive` error means both TLS flags are `true`.

## Related

- [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.
- [Set up Strapi email over SMTP](https://www.unitpost.com/docs/smtp/strapi): @strapi/provider-email-nodemailer in config/plugins, then fix the Users & Permissions shipper email.