Configure Postfix to use Gmail as a Mail Relay

If you have a Gmail account, you can configure your MTA to relay outgoing mail through Gmail. This gives you the benefit of Gmail's reliability and robust infrastructure, and provides you with a simple means of sending email from the command line.

In this tutorial, we will use Postfix as our MTA. Postfix is a free, open-source, actively maintained, and highly secure mail transfer agent.

At each step, we'll cover instructions specific to the following operating systems:

  • Debian 8
  • Ubuntu 15.10
  • CentOS 7
  • OpenSUSE 13.2
  • Arch Linux 2016.02.01
  • FreeBSD 10.2

We will also install mailutils/mailx so that we can send a test email. Where necessary, we will install supplemental SASL libraries.

All commands beginning with # require root privileges.

1. Install Required Software

Debian, Ubuntu:

apt-get update && apt-get install postfix mailutils

When prompted for "General type of mail configuration," choose Internet Site.

When prompted for a "Mail name," choose a hostname to be used in mail headers as the origin of your emails. A fully-qualified domain name is preferred, but using your machine's simple hostname is OK. Regardless of what you enter here, your return address will appear to recipients as your Gmail address.

You may be prompted to set the "Root and postmaster mail recipient." Enter root, or another user who should receive mail subsystem notifications.

For any other prompts, you can choose the default values.


dnf update && dnf install postfix mailx


yum update && yum install postfix mailx cyrus-sasl cyrus-sasl-plain


zypper update && zypper install postfix mailx cyrus-sasl

Arch Linux:

pacman -Sy postfix mailutils


Compile Postfix from the ports collection to incorporate support for SASL:

portsnap fetch extract update

cd /usr/ports/mail/postfix

make config

In the configuration dialogs, select SASL support. All other options can remain the same. Then:

make install clean

Mailx can be installed from the binary package:

pkg install mailx

2. Configure Gmail Authentication

Create or modify a password file which will be used by Postfix to establish authentication with Gmail. In the authentication information below, replace username with your Gmail username and password with your Gmail password. If you are using a custom Gmail Apps domain name, you may replace with your Google Apps domain.

The password file will reside in the Postfix configuration directory. The file can be named whatever you like, but the recommended filename is sasl_passwd.

Debian, Ubuntu, Fedora, CentOS, OpenSUSE, Arch Linux:

Postfix configuration files reside in the directory /etc/postfix. Create or edit the password file:

vi /etc/postfix/sasl_passwd

Add the line:

[]:587    [email protected]:password

Save and close the file. Your Gmail password is stored as plaintext, so make the file accessible only by root:

# chmod 600 /etc/postfix/sasl_passwd


Postfix configuration files reside in the directory /usr/local/etc/postfix. Create or edit the password file:

vi /usr/local/etc/postfix/sasl_passwd

Add the line:

[]:587    [email protected]:password

Save and close the file. Make it accessible only by root:

chmod 600 /usr/local/etc/postfix/sasl_passwd

3. Configure Postfix

There are six parameters which must be set in the Postfix configuration file The parameters are:

relayhost, which specifies the mail relay host and port number. The host name will be enclosed in brackets to specify that no MX lookup is required.

smtp_use_tls, which enables (or disables) transport layer security.

smtp_sasl_auth_enable, which enables (or disables) SASL authentication.

smtp_sasl_security_options, which in the following configuration will be set to empty, to ensure that no Gmail-incompatible security options are used.

smtp_sasl_password_maps, which specifies the password file to use. This file will be compiled and hashed by postmap in a later step.

smtp_tls_CAfile, which specifies the list of certificate authorities to use when verifying server identity.

Debian, Ubuntu, Arch Linux:

Edit the main Postfix configuration file:

vi /etc/postfix/

Add or modify the following values:

relayhost = []:587
smtp_use_tls = yes
smtp_sasl_auth_enable = yes
smtp_sasl_security_options =
smtp_sasl_password_maps = hash:/etc/postfix/sasl_passwd
smtp_tls_CAfile = /etc/ssl/certs/ca-certificates.crt

Save and close the file.

Fedora, CentOS:

Edit the main Postfix configuration file:

vi /etc/postfix/

Add or modify the following values:

relayhost = []:587
smtp_use_tls = yes
smtp_sasl_auth_enable = yes
smtp_sasl_security_options =
smtp_sasl_password_maps = hash:/etc/postfix/sasl_passwd
smtp_tls_CAfile = /etc/ssl/certs/ca-bundle.crt

Save and close the file.


Edit the main Postfix configuration file:

vi /etc/postfix/

Add or modify the following values:

relayhost = []:587
smtp_use_tls = yes
smtp_sasl_auth_enable = yes
smtp_sasl_security_options =
smtp_sasl_password_maps = hash:/etc/postfix/sasl_passwd
smtp_tls_CAfile = /etc/ssl/ca-bundle.pem

Save and close the file.

OpenSUSE also requires that the Postfix master process configuration file be modified. Open it for editing:

vi /etc/postfix/

Locate the line which reads:

#tlsmgr unix - - n 1000? 1 tlsmg

Uncomment it, so it reads:

tlsmgr unix - - n 1000? 1 tlsmg

Save and close the file.


Edit the main Postfix configuration file:

vi /usr/local/etc/postfix/

Add or modify the following values:

relayhost = []:587
smtp_use_tls = yes
smtp_sasl_auth_enable = yes
smtp_sasl_security_options =
smtp_sasl_password_maps = hash:/usr/local/etc/postfix/sasl_passwd
smtp_tls_CAfile = /etc/mail/certs/cacert.pem

Save and close the file.

4. Process Password File

Use postmap to compile and hash the contents of sasl_passwd. The results will be stored in your Postfix configuration directory in the file sasl_passwd.db.

Debian, Ubuntu, Fedora, CentOS, OpenSUSE, Arch Linux:

postmap /etc/postfix/sasl_passwd


postmap /usr/local/etc/postfix/sasl_passwd

5. Restart Postfix

Restart the Postfix service, putting your changes into effect.

Debian, Ubuntu, Fedora, CentOS, OpenSUSE, Arch Linux:

systemctl restart postfix.service


To start the Postfix service for this session only:

service postfix onestart

To start Postfix automatically when the system initializes, open /etc/rc.conf for editing:

vi /etc/rc.conf

Add the line:


Save and close the file. You may then run:

service postfix start

To start Postfix.

6. Enable "Less Secure Apps" In Gmail

By default, only the most secure sign-ins, such as logging in to Gmail on the web, are allowed for your Gmail account. To permit relay requests, log in to your Gmail account and turn on Allow less secure apps.

For more information, review the Google Support document "Allowing less secure apps to access your account."

7. Send A Test Email

Test your new configuration by sending an email using the mail command. Run:

mail -s "Test subject" [email protected]

You will be presented with a blank line (or a CC: field, which you can bypass by pressing Enter). Type the body of your message, pressing Enter for new lines. When you are finished composing the email, type CTRL-D to send it. To cancel the email, press CTRL-C twice.

To send a precomposed email, use the command:

mail -s "Subject Here" [email protected] < textfile

Where textfile is the name of a file containing the text to be sent.


If it's not working, check the logs for any Postfix errors:


less /var/log/mail.log

Ubuntu, Fedora, CentOS, OpenSUSE, Arch Linux:



less /var/log/maillog

If you receive authentication errors from Gmail, verify that Allow Less Secure Apps is turned on in your Gmail account settings, as specified in Step 6.

Verify that the password file sasl_passwd exists, and that its contents are formatted correctly, as specified in Step 2. If you make any changes to the password file, make sure to repeat Steps 4 and 5 to hash the new password file and restart Postfix.

If you see any TLS errors, double check the configuration in as specified in Step 3. If you make any configuration changes, restart Postfix as specified in Step 5.

Share this page:

Suggested articles

36 Comment(s)

Add comment


From: sjau at: 2016-03-01 09:16:01

I tried this once a while back but I noticed that GMail replaces the sender automagically with the GMail email account you're relaying through. Is this still the case?

From: Karen at: 2016-03-01 11:55:54

For Ubuntu 14.04.x, do not use `systemctl restart postfix.service` but:

$ sudo service postfix restart

From: JS at: 2016-04-06 10:21:05

Is it possible to setup postfix, if I don't want to use Step 6: Allowing less secure apps to access your account?

From: Ronan at: 2016-04-20 03:48:21

Thanks - great writeup.

For Debian, I also needed to install libsasl2-modules for it to send the mail out.

apt-get install libsasl2-modules



From: Vale at: 2016-04-21 20:17:51

Following this guide I ontain on Centos 7 server the error message "...remote host said 550 relay through this server without authentication.." and postfix don't send emails.Some helps?

From: melih at: 2016-04-22 12:39:50

I've tried on Debian 8, seems okay. Thank you.

From: ustoopia at: 2016-05-01 06:17:57

Can I perform these installation instructions after having installed ispconf3 on Ubuntu 16.04 ? Will it break anything important if I do?

I only run the server locally at the moment to test webs so I don't need the email setup, but at the same time I would like to receive important system messages.

From: Tim Ryan at: 2016-05-17 10:34:10

Worked like a charm, thank you.

From: Scott Mullen at: 2016-06-12 22:42:58

Instead of enabling 'Less Secure Apps" In Gmail you can just use app passwords.

From: Carlo at: 2016-07-29 19:57:38

In Ubuntu, I think heirloom-mailx is better than mailutils, and heirloom-mailx in ubuntu = mailx in CentOS~

Sorry for my language!

From: Alcor at: 2016-07-31 09:44:14

Works in ubuntu server 14.10 LTS!!.

Very, very thanks.

From: Lukasz at: 2016-07-31 23:56:35

Thanks for this tutorial. It worked (Ubuntu 12.04)!

From: Tony at: 2016-08-21 05:45:32

Great tutorial done on Debian Jessie oa Raspberry PI and worked first up

From: newbridgeman at: 2016-08-24 21:08:57

Thanks for the tutorial. It was very easy to follow. I got mine working.

From: Jaques Viljoen at: 2016-09-07 15:00:48

Thanks very much for the clear and concise instructions :-)

I have tested the Ubuntu version for Raspbian Jessie on a Pi model B running nagios and I was able to get the test e-mail sent.



From: Amit khurchay at: 2016-09-20 10:20:26

I did same setting, there is no mail in gmail account.

From: mira at: 2016-11-05 12:38:36

Hello I made configuration on centos. Ok, but after I have send first email Gmail blocked my account because of "failure to comply with terms and conditions". Is this somethnig to do with settings or this way can be used anymore ?

From: Robin at: 2016-11-18 11:54:10

Hi, Great instructions.  I am on OpenSuse Leap 42.1 and every step in your instructions worked flawlessly.

Many thanks

From: Dan Ziemecki at: 2017-01-08 14:06:39

Awesome write-up.  Worked first time through.  Thanks!

From: Amit Khurchay at: 2017-01-10 11:37:11


I had been installed postfix on my local server, but  dont know how to configure this?  Please help me I am using ubuntu 16.04 lts


From: Robert Klebe at: 2017-02-25 11:40:59

This article is GOLDEN. It WORKS. So happy. ^^

From: Mahita at: 2017-02-28 06:09:15

Awesome saved my day

From: John at: 2017-04-23 10:06:14

i got an error saying "Invaild Email Address"

huh? Could it be "-" in email address?

From: Guybrush at: 2017-04-26 11:06:15

I had this error to avoid it do the following:# status=bounced (host[] said: 530 5.7.0 Must issue a STARTTLS command first. m201sm9925851wmd.15vi /etc/postfix/tls_policy# add encrypt#then runchown root:root /etc/postfix/tls_policy && chmod 600  /etc/postfix/tls_policypostmap /etc/postfix/tls_policysystemctl restart postfix

From: Mike R at: 2017-04-26 17:34:46

Thank you!  Works perfectly once I figured out how to read and solve a small issue :)

I used the wrong paths in the config file the first time (copied the FreeBSD config lines into my Raspbian config so paths were wrong.)  Once i did that, I noticed an error in the postfix log file regarding cert file cannot be found. For my Raspbian jesse, I left out the cert line in the postfix conf file:

smtp_tls_CAfile = /etc/ssl/certs/ca-certificates.crt

Also had to turn on Allow less secure apps in Google.

All worked well after that!


From: Thomas at: 2017-04-29 14:30:00

I receive mails on my mailbox (gmail) however when someone try to contact me  the FROM  field instead of


I have


config: only postfix relay via smtp gmail 

Any idea ?

From: Max at: 2017-07-14 09:26:17


From: Daniel at: 2017-07-27 06:37:36

I have a question: It's known that the Google App service have certain limits per day. Are those limits affected by this method? 

From: David at: 2017-09-04 04:35:17

You saved my nec.

May the force be with you !!!


From: Lado at: 2017-11-13 09:48:09

postfixt was bouncing outgoing mail saying "Must issue a STARTTLS command first". On I found suggestion to use:  "mailsmtp_enforce_tls = yes" in instead "smtpd_use_tls=yes" as instructed above.

I did that, now it works like a charm.

Thank for great tutorial!

From: Neil at: 2017-12-05 08:03:20

Worked for Ubuntu 17.04. It took me F O R E V E R, and one reinstall, but finally got joy. Good luck.

From: shareef at: 2017-12-11 13:12:47


all sent emails are in mail queue with:

TLS is required, but was not offered by host[])

 What to do?


Thanks and Regards,

From: Joshua S at: 2017-12-31 21:33:25

Thank you so very much for this great tutorial.  I got it working on Ubuntu 17.10 Budgie.  I placed the file: sasl_passwd in /etc/postfix/sasl/ instead of /etc/postfix/.  Also, tailing the logs (tail -f /etc/mail.*) was very helpful in helping to diagnose any issues I had.  I made the hostname to the email address username and I had to re-run postfix install a couple of times before I got it working (dpkg-reconfigure postfix). I also set to IPv4 only instead of All during postfix setup.

From: Michael at: 2018-01-06 05:50:56

You do not need to do step 6. Step 6. Should be setting an app password then instead of using your regular password in sasl_passwd, you use the app password provided by gmail. Voila it works no need to turn on lesser secured apps choice.

From: hajro at: 2018-01-30 14:17:25

Thanks, it's the only one working tutorial I've found.

From: Elicia Nesmith at: 2018-02-18 23:11:48

I liked your article. Did you know that Google has introduced Gmail Go? Go not only takes up significantly less space on your phone, but uses less data than the standard Gmail app.