Learn how to send a test email in your self-hosted instance of GitLab through the command line to test your SMTP configuration.

How to test the SMTP configuration in Gitlab CE through the CLI sending a test email

GitLab stands out as a powerful code management tool in the world of software development nowadays. In the last few days, I was configuring my self-hosted instance of GitLab and quickly needed to configure an important aspect of its setup, the configuration of email notification through an SMTP server (Simple Mail Transfer Protocol). Aimed at both newcomers and seasoned GitLab administrators, in this article, I will explain to you how to easily test whether your SMTP configuration is working properly to send emails in GitLab, and in case it's not properly configured, show you how to easily configure it with the most common SMTP providers out there.

1. Access your server via SSH

To test your SMTP configuration, you will need to launch the GitLab Rails Console using the following command in your installation server:

gitlab-rails console -e production

This will launch the GitLab Rails console in production mode. In this console, you will run the rest of the commands that I will mention throughout the article:

Gitlab Rails Cli

2. Verify the configured SMTP

The first thing that you need to do is to check the current SMTP configuration of your GitLab instance. You can print out the current settings with the following instruction:


This will generate an output similar to the following one in case that you already configured something:

SMTP Configuration

In case you don't know where to configure it, you need to add the following configuration information to /etc/gitlab/gitlab.rb and run gitlab-ctl reconfigure afterward (in my case, I use the Zoho Mail SMTP, so the configuration looks like this):

gitlab_rails['smtp_enable'] = true
gitlab_rails['smtp_address'] = "smtp.zoho.com"
gitlab_rails['smtp_port'] = 587
gitlab_rails['smtp_user_name'] = "[email protected]"
gitlab_rails['smtp_password'] = "P@ssw0rd"
gitlab_rails['smtp_domain'] = "smtp.zoho.com"
gitlab_rails['smtp_authentication'] = "plain"
gitlab_rails['smtp_enable_starttls_auto'] = true
gitlab_rails['gitlab_email_from'] = '[email protected]'
gitlab_rails['gitlab_email_reply_to'] = '[email protected]'

There's an official document on Gitlab that specifies the configuration of multiple email providers such as AWS SES, Google SMTP relay, Zoho Mail etc. You can find the whole list here. Depending on your setup, whether you're running GitLab on your bare metal server, or with Docker, you may either restart the service to get the new parameters of your SMTP configuration:

gitlab-ctl restart

Or in case you're using Docker Compose, rebuild the stack:

docker compose down && docker compose up --build -d

3. Send a test email

GitLab offers a method to test the current SMTP configuration by simply delivering a test email. This method is Notify.test_email and expects 3 parameters:

  • Email address.
  • Subject.
  • Content.

You can send a test email from the CLI using the mentioned command (replace the email address with your email where the test email should be delivered):

Notify.test_email('[email protected]', 'Castle of Glass', 'Leave out all the rest').deliver_now

In case of success

If your SMTP was properly configured, the utility should be able to deliver the email and generate an output similar to the following one:

GitLab SMTP Success

In your inbox you should have a new email with the message you sent:

GitLab Test Email

In case of error

If your SMTP is misconfigured, you will obtain an EOFError through the execution:

GitLab SMTP Delivery Error

This means that either the configuration is not correct or maybe your SMTP is Down. If that's the case, I'd recommend you check the SMTP configuration guide of GitLab here.

4. Test in production

Now after verifying that the SMTP configuration works, you can test in production using GitLab by simply triggering an action that sends an email notification, such as the creation of a new account on GitLab, where the registered user should receive an email with the details:

GitLab Account

Happy coding ❤️!

Senior Software Engineer at Software Medico. Interested in programming since he was 14 years old, Carlos is a self-taught programmer and founder and author of most of the articles at Our Code World.