Enabling postfix for outbound relay via Gmail on OS X Lion (and newer OSX versions)

Update on Oct 25, 2014: Updated For OS X Yosemite.

Update on Dec 21, 2013: I have posted an update to the launchd setup for postfix. You should still read through this post, as most of the setup remains common to both posts.

The background

Mac OSX comes with the postfix MTA, which is a fully featured SMTP server. Under normal circumstances, there is usually no need to enable or configure this software, as most email access is usually done via GUI clients such as the Mail.app – which uses the POP/IMAP and SMTP settings to connect with the email service provider.

However, there are certain circumstances in which having a local SMTP server is very useful, such as:

  1. Allowing the batch logs and output from the cron daemon or other scripts to be sent via Internet email (this is otherwise delivered locally)
  2. Testing email based code; which requires a local sendmail like SMTP server to be present

For such use cases, the postfix server is ideal, as it provides all the features needed (and much more), and is also a nice drop-in replacement for the sendmail program.

While postfix can be used as a full-fledged SMTP server that connects directly to the mail-servers on the Internet, for the use cases above, it is usually better to redirect (i.e., relay) the emails via an authenticated and known server (such as Gmail), as this helps avoid a lot of constraints around open-relays, which are mostly blocked these days to prevent email spam.

Note that configuration of postfix does require dropping down to the command-line, and fiddling with system files. While not complicated, it is definitely not for faint of the heart (though much easier than configuring sendmail).

What you need to know (pre-requisites)

Some of the basic pre-requisites are:

  1. Understanding of the shell prompt and the Terminal.app program
  2. Usage of the sudo program (all the configuration files are owned by root, and hence usage of sudo is essential)
  3. Usage of any command line editor such as vim, Emacs, nano, or any other editor of your choice, that can be invoked with super-user rights (usually via sudo)
  4. A basic understanding of the Apple launchd service manager
  5. The configuration files
  6. A Gmail email ID (actually, any SMTP server credentials will do)

While this article will go step-by-step with the configuration process, knowledge of the above will allow a deeper understanding of the “why” for the changes done.

In the steps below. the $ character before any command represents the shell prompt. Also, I will assume usage of the vim editor in the steps below.

The configuration Files

The configuration files that will be changed are:

Name Location Purpose
org.postfix.master.plist /System/Library/LaunchDaemons launchd Configuration for postfix
main.cf /etc/postfix The main postfix configuration
aliases /etc/postfix Local recipient aliases
generic /etc/postfix Sender aliases (for external mail)
passwd /etc/postfix/sasl Relay host authentication

Note that the “/etc/postfix/sasl” directory might not exist, in which case, we will need to create it from the shell prompt:

$ sudo mkdir /etc/postfix/sasl

Step 1: Update the launchd configuration

Update Dec 21, 2013 : While this setup still works, you might want to also see an alternate configuration of postfix’s launchd setup, which I have documented in a follow-up article. The new configuration also allows postfix to be launched when network activity happens on the local SMTP port 25.

The org.postfix.master.plist file located at /System/Library/LaunchDaemons/ is used to start or stop the postfix program on demand, as and when any email is submitted to the mail system for processing. The basic Apple setup is fine, but may need a little tweaking (in my case, the file had a couple of tags which prevented postfix from being started.)

We need to edit the file (as a super user) to match the following content:

$ sudo vim /System/Library/LaunchDaemons/org.postfix.master.plist
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple Computer//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">

Step 2: Edit the /etc/postfix/main.cf file

The next step is to edit the main configuration file for postfix. Do make a backup of the current file before editing.

$ cd /etc/postfix
$ sudo cp main.cf main.cf.orig
$ sudo vim main.cf

Note that the main.cf file is a pretty large one, and has a lot of commented out sections, which should be left as is. Please add the following lines at end of the file.

# Set the relayhost to the Gmail Server.  Replace with your SMTP server as needed
relayhost = [smtp.gmail.com]:587
# Postfix 2.2 uses the generic(5) address mapping to replace local fantasy email
# addresses by valid Internet addresses. This mapping happens ONLY when mail
# leaves the machine; not when you send mail between users on the same machine.
smtp_generic_maps = hash:/etc/postfix/generic

# These settings (along with the relayhost setting above) will make
# postfix relay all outbound non-local email via Gmail using an
# authenticated TLS/SASL session.
smtp_sasl_security_options = noanonymous
smtp_sasl_mechanism_filter = plain

Step 3: Edit the /etc/postfix/aliases file

We need to make a minor edit here, to allow mails sent to the root ID to your local user mailbox.

$ cd /etc/postfix
$ whoami                # This will provide your local user name
$ sudo cp aliases aliases.orig
$ sudo vim aliases
$ sudo newaliases

Find the line in the file which is:

#root:              you

and replace the “you” with the username provided by the whoami command above.  Also, remove the “#” from beginning of the line.

Remember to run the newaliases command (the last command above), or else changes will not take effect!

Step 4: Edit the /etc/postfix/generic file

This file maps the local user address (usually of the form yourid@machine.local) to a valid Internet email address you would like to use when sending mails to the outside world. In our case, it would basically map your Unix user name to the Gmail ID.

$ cd /etc/postfix
$ whoami                # This will provide your local user name
$ hostname              # This will provide your machine name
$ sudo cp generic generic.orig
$ sudo vim generic
$ sudo postmap generic

In the file, add the following lines at the end of the file (replacing the <username> with the output of the whoami command, and <machinename> with output of the hostname command):

# Translate my primary email address to the Gmail address
# This is ONLY for the outbound email, and does not apply to
# local email.
<yourusername>@<machinename>  <your gmail ID, e.g. user@gmail.com>
@<machinename>                <your gmail ID, e.g. user@gmail.com>

Remember to run the last command (postmap) as otherwise the changes will not be picked up!

Step 5: Edit/Create the /etc/postfix/sasl/passwd file

In this step, we store the SMTP authentication (user ID and password) for Gmail, so that postfix can connect as any other SMTP client to Gmail via an authenticated session.

Note that the file may not exist prior to this step, in which case we will create it.

$ sudo mkdir -p /etc/postfix/sasl    # In case the directory does not exist
$ cd /etc/postfix/sasl
$ sudo vim passwd
$ sudo postmap passwd

Create the following file, replacing <gmailusername> with the ID you use for Gmail (with the “@gmail.com” added at the end), and <gmailpassword> with the password you use to login to Gmail.

[smtp.gmail.com]:587    <gmailusername>:<gmailpassword>

Note that if you use two-factor authenication with Google, then the password to use will be a new application specific password generated via Google’s account settings.

Final Step: Test the settings

We are now good to go. Lets test our settings from the terminal:

$ cd /System/Library/LaunchDaemons
$ sudo launchctl load -w org.postfix.master.plist
$ cd ~                             # Just to be safe, move to your home directory
$ mail <your_id>  # Output of the `whoami' command
# Type in a test email and hit Control-D on a new line
$ mail
# Check whether the email has arrived. Hit 'q' on the '?' prompt to quit

$ mail <your gmail ID>       # Lets now try to send an external mail.
# Type in a test email and hit Control-D on a new line

After the second step above, check your Gmail account for the test mail. If it has arrived, then we have a good configuration.


Setting up the postfix system on OSX is not particularly hard, but does require some steps. Also, this is just the basic setup to get things up and running. Postfix is an industrial strength mail server has a lot of features (and a corresponding number of configurations). Thankfully, the documentation at http://www.postfix.org/documentation.html is pretty good.

For more details on this specific setup, additional documentation is available at http://www.postfix.org/SOHOREADME.html.

[Updated on 19th Feb 2012]: Corrected a typo.  Thanks to jamrok for pointing it out.


118 thoughts on “Enabling postfix for outbound relay via Gmail on OS X Lion (and newer OSX versions)

  1. Hello,

    Thanks for sharing this, i’ve been lookin for such precise instructions. smpt, postfix, sendmail can be very very tricky to configure. Anyway i have one issue . I’m a on mac os x lion 10.7.3 FYI. On step 5 i modified the passwd file accordingly, but when i hit , sudo portmap passwd i get this error message : portmap: command not found . i tried to find the command with : locate portmap and which portmap but the system can’t find any portmap binaries on my os . Do you know if it’s a package messing ? or something else ?

    1. Hi Jamrok,

      I am happy that this was useful to you. Also, my apologies for the typo around the ‘portmap‘ command. It should actually be ‘postmap‘! Many thanks for pointing this out, and hopefully you should be able to now proceed with setting up postfix.

  2. Thanks so much for this. I had almost broken down an spent too much money on a test server app. Thank you again!

  3. Thanks so much for this! I almost broke down and purchased a too-expensive test server app. Thanks again!

    1. I just found I had to do a tweak to get this working with the web app I’m developing in grails:

      Comment out the line that looks like this:
      imap_submit_cred_file = /etc/postfix/submit.cred

  4. Also, I figured out how to rewrite all outbound addresses to your own address:

    1) in /etc/postfix/, create a file (rewrite) with these contents:
    /.*/ your.email@gmail.com

    2) parse this configuration in main.cf:
    smtp_generic_maps = regexp:/etc/postfix/rewrite

    3) reload postfix:
    sudo postfix reload

  5. Very interesting tutorial. Unfortunately, it does not work for me. tail -f /var/log/mail.log shows the error below. It says that the username and password are not accepted, which is weird as I followed the tutorial entering the username and password with which I connect to my gmail account. Checked twice, no error.
    Would you have any advice? Thanks in advance.

    Apr 17 21:36:07 mbp-i5 postfix/smtp[86224]: setting up TLS connection to smtp.gmail.com[]:587
    Apr 17 21:36:07 mbp-i5 postfix/smtp[86224]: certificate verification failed for smtp.gmail.com[]:587: untrusted issuer /C=US/O=Equifax/OU=Equifax Secure Certificate Authority
    Apr 17 21:36:08 mbp-i5 postfix/smtp[86224]: Untrusted TLS connection established to smtp.gmail.com[]:587: TLSv1 with cipher RC4-SHA (128/128 bits)
    Apr 17 21:36:09 mbp-i5 postfix/smtp[86224]: 043ED1CBB41B: to=, relay=smtp.gmail.com[]:587, delay=8.8, delays=0.01/0.2/8.6/0, dsn=4.7.1, status=deferred (SASL authentication failed; server smtp.gmail.com[] said: 535-5.7.1 Username and Password not accepted. Learn more at?535 5.7.1 http://support.google.com/mail/bin/answer.py?answer=14257 w10sm46501085wiy.3)

  6. Very interesting tutorial. Unfortunately, it does not work for me. tail -f /var/log/mail.log shows the error below. It says that the username and password are not accepted, which is weird as I followed the tutorial entering the username and password with which I connect to my gmail account. Checked twice, no error.

    Would you have any advice? Thanks in advance.

    Apr 17 21:36:07 mbp-i5 postfix/smtp[86224]: setting up TLS connection to smtp.gmail.com[]:587
    Apr 17 21:36:07 mbp-i5 postfix/smtp[86224]: certificate verification failed for smtp.gmail.com[]:587: untrusted issuer /C=US/O=Equifax/OU=Equifax Secure Certificate Authority
    Apr 17 21:36:08 mbp-i5 postfix/smtp[86224]: Untrusted TLS connection established to smtp.gmail.com[]:587: TLSv1 with cipher RC4-SHA (128/128 bits)
    Apr 17 21:36:09 mbp-i5 postfix/smtp[86224]: 043ED1CBB41B: to=, relay=smtp.gmail.com[]:587, delay=8.8, delays=0.01/0.2/8.6/0, dsn=4.7.1, status=deferred (SASL authentication failed; server smtp.gmail.com[] said: 535-5.7.1 Username and Password not accepted. Learn more at?535 5.7.1 http://support.google.com/mail/bin/answer.py?answer=14257 w10sm46501085wiy.3)

  7. This is a FANTASTIC tutorial for Mac OS X Postfix setup. I spent many years setting up Postfix from scratch on several Linux server and this is by far the most painless setup and well written instructions I have seen. I especially appreciate you included info pertaining to Google Two-Step Authentication. I thought for sure when I started this setup I was going to run into that as a snag down the road. Nope – you thought of it. Much appreciated for this great article you wrote.

      1. Hmmm… I’m using it to send mail via shell scripts via localhost and it works fine. Is that different.

      2. Yes, you’re probably using “mail” from the command time. I’m talking about connecting to the mail server. What happens when you run “telnet localhost 25”?

      3. Ok – – I see – telnet yields “Connection Refused”

        Following the instructions you listed – you create the submit.cred file with format:


        Would the host be listed as “localhost”

        Also – isn’t that one big burrito to be hanging out there with your password in cleartext?

      4. You don’t actually need to include any credentials in the submit.cred file—it just needs to exist, and the permissions need to be set properly, and it must include this line: “submitcred version 1”

        It’s a slight security risk, but setting the permissions with “chmod 600” ensures that you’re the only one who can access the file.

      1. in the submit.cred file, what is the user|host|password to be entered? Is that local credentials or remote credentials?

  8. Excellent tutorial – thank you. I found that when I attempted to launch postfix initially with the new settings, that I received a “No socket()” error. Digging through the logs, I could see that postfix hadn’t been running for two days. I wasn’t sure how to properly resurrect the daemon, so I resorted to the old holdover from my windows days and restarted the machine. Once complete, postfix was running properly and everything worked as advertised – thanks again!

  9. Hi there
    Whereas sending local mails works fine, outbound messages won’t get delivered with a: host smtp.gmail.com[] said: 530-5.5.1
    Authentication Required. Learn more at 530 5.5.1
    I followed your instructions and double checked the passwd file in /etc/postfix/sasl

    I’m almost sure I’m missing something obvious.. but what?

      1. Yes I did (several times, just to be sure) 😉
        I somehow have the feeling that my main.cf might be the cause… Before I found this tutorial I played around with the lion mailserver configuration tool..
        Is there any default main.cf that I could check mine against?

  10. Alex,

    That might be one of the reasons. Unfortunately, I am not sure of the changes that the Lion mailserver tool makes; however, I assume it makes a backup of the file somewhere (usually in the same directory, with a different extension). Your best bet is to look at the tool’s documentation and find out if it makes a backup, and then diff the backup with the current file to check on any changes.

    Another thing that you might want to check is on whether you are using the right password (especially if you are using two-factor authentication with Gmail, where you will need to generate an application specific password, and use that).

    1. After searching around a bit I found a default main.cf into (which I had to complete with a few paths etc.) but after that everything started working like a charm 🙂

      thanks again!

  11. This tutorial is great! I am interested in learning more about unix and being able to control my mac more fully, what books would you recommend reading…

    1. Johnny,

      Great that you found the tutorial to be useful. There are many (literally, thousands) of books on Unix. Many of the books also focus on Linux, which can be useful to an extent for understanding the OSX Unix underpinnings. A good and comprehensive book is the A Practical Guide to UNIX for Mac OS X Users. Another good resource is the unixFAQ for OS X.

      I actually moved from being a Linux user (Slackware) to the Mac, partly because the new environment still lets me use the shell and a true Unix (BSD flavored).

      Hope you have a good time ahead with the Unix foundations of OSX!

  12. Thanks for the potentially useful tutorial (I’ve not gotten it to work for me yet, but I’m still trying).

    I notice a couple minor typos you might want to correct: in a couple of places you’ve accidentally omitted the ‘sudo’ when making a backup copy.

    Anyway, thanks. Back to figuring out why it’s not worked for me yet….

      1. Don,

        Thanks for catching the missing ‘sudo’. I have updated the post accordingly.

  13. Thank you for this tutorial, even though it hasn’t been of use to me yet. I’m a complete newbie so I guess I should maybe not be trying this as I don’t fully understand what I’m doing.

    I’m trying this on a 10.6 machine. Postfix delivers the mails fine locally but not at all when I try to send them to an external address. The strange thing is that I don’t even get a delivery failure notification which I used to get before I went through this process.

  14. Worked like a charm, on Mountain Lion, had to do:
    sudo launchctl stop org.postfix.master
    sudo launchctl start org.postfix.master

  15. It works great.

    My question is – I have postfix running the relay on another server. I have a UPS I want to send me email alerts. I want to use the postfix server to do that because the UPS must use a local SMTP server to push.

    What is the local smtp server address I use? From address? I’m getting confused if I should use gmail or the local postfix accounts.

  16. Many many thanks! Worked perfectly. I even got a nice backlog of emails I’d tried to send from a few websites I’d been working on locally.

  17. Everything works except starting postfix on demand. I need to “sudo postfix start”. I’ve tried rebooting, launchctl unload and load sequences, but the OnDemand thing doesn’t seem to work. Checked and re-checked org.postfix.master.plist. Any ideas for troubleshooting would be appreciated.

    1. Same problem here – after a restart I have to manually stop/start postfix to get it working – does anyone have a solute to get the launch agent running again?

  18. After upgrading to ML I Postfix started throwing this error:

    send-mail: fatal: chdir /Library/Server/Mail/Data/spool: No such file or directory

    I followed these direction to get it up an running again (basically recreating dir and changing permissions):


    Everything seems to be working fine but I am still seeing this non-critical error:

    postfix/postfix-script: warning: group or other writable: /Library/Server/Mail/Data/mta

    Is there something I can do to alleviate that last error?

  19. Doesn’t work for me, either:


    root: mnewman


    mnewman@bleach.local mygmail@gmail.com
    @bleach.local mygmail@gmail.com

    But all mail sent to both root and mnewman ends up in the mnewman local mailbox. The mail never gets forwarded to the remote gmail address. So, it appears that the aliases file is working, but that generic is not.

    I have run newaliases and postmap generic and postfix reload.

    bleach:postfix mnewman$ hostname
    bleach:postfix mnewman$ whoami

    == mail.log ==
    Sep 22 10:06:25 bleach postfix/pickup[1225]: 395323508C4A: uid=502 from=
    Sep 22 10:06:25 bleach postfix/cleanup[1230]: 395323508C4A: message-id=
    Sep 22 10:06:25 bleach postfix/qmgr[1226]: 395323508C4A: from=, size=321, nrcpt=1 (queue active)
    Sep 22 10:06:25 bleach postfix/local[1232]: 395323508C4A: to=, orig_to=, relay=local, delay=0.06, delays=0.04/0.02/0/0, dsn=2.0.0, status=sent (delivered to mailbox)

    This on a Mac running OSX 10.8.2.

    What did I do wrong?

  20. Hello,

    i use Mountain Lion with the Server Application.
    looking in the mail.log file, i just realized that MacOSX Server didn’t set all rights like i should do…

    1. look in the log file

    tail -f /var/log/mail.log

    2. if you get this message, you have the same problem that i had

    Oct 3 11:48:54 MacOsX.Server postfix/postfix-script[59779]: warning: not owned by _postfix: /Library/Server/Mail/Data/mta/./guid_device_maps.plist

    3. check the rights and privileges of the file guid_device_maps.plist

    sudo ls -al /Library/Server/Mail/Data/mta/./guid_device_maps.plist
    -rw-r—– 1 root mail 181 Sep 18 07:40 /Library/Server/Mail/Data/mta/./guid_device_maps.plist

    4. change the owner to _postfix user

    sudo chown _postfix /Library/Server/Mail/Data/mta/./guid_device_maps.plist

    5. check your changes 😉

    sudo ls -al /Library/Server/Mail/Data/mta/./guid_device_maps.plist
    -rw-r—– 1 _postfix mail 181 Sep 18 07:40 /Library/Server/Mail/Data/mta/./guid_device_maps.plist

    6. open the Server Application, go to Email, check the Authentication method, i set it as “Automatic”

    7. finally restart it switching on/off

    sorry if the description isn’t 100% correct, i have my system in german, but i think you know what i mean…


  21. Evolve 75, great tutorial. It worked well for me in ML.
    I am quite new to Unix and Postfix in particular.
    How can I set this up so that users on the network can connect to the postfix server and relay via smtp.gmail.com to their own accounts? This is to let them send scanned documents from a machine which does not support TLS and, therefore, cannot send direct to their gmail accounts.

    Best wishes


  22. When I get to this step:

    sudo /usr/sbin/postfix set-permissions

    I’m getting this error:

    chown: /usr/share/man/man1/postalias.1.gz: No such file or directory

  23. Hi,
    thanks for the tutorial.
    I’m on Os Lion, I perform all the stuff described.
    When I send an email with email myUserName it works (in Local)
    When I try to send to my gmail adress, the field ‘to’ in my mail is …@new-host.home
    And then it is rejected by gmail server.
    Do you know how to configure postfix in order it create a correct adress ?

    1. Hi,

      This usually happens if the changes in the /etc/postfix/generic file have not been applied/picked up by Postfix. Can you recheck the step 4, and ensure that the postmap command has been run correctly?

  24. Worked well on 10.8.2 once I used the right syntax in the launchctl command and replaced both instances of “smtp.gmail.com” with an IP address for it. For some reason, I was getting this error:

    Dec 24 22:33:17 box.home postfix/smtp[60826]: AD5AF48D2722: to=, relay=none, delay=264, delays=251/0.2/12/0, dsn=4.4.3, status=deferred (Host or domain name not found. Name service error for name=smtp.gmail.com type=AAAA: Host not found, try again)

  25. I got it to work perfectly on my server thank you for this! I wondered what kind of changes I would need to make this to work on a generic SMTP server (via SSL). Please let me know.

  26. Nobody else seemed to have this problem, but after following this (excellent) guide I still had an error in /var/log/mail.log when sending external emails through the smtp relay. Delivery of local mail was not affected.

    error: unsupported dictionary type: sdbm

    fatal: dictionary sdbm:/var/lib/postfix/smtp_tls_session_cache is not a regular file

    The fix is to edit /etc/postfix/main.cf to disable sbdm and enable btree for the TLS request cache.

    smtp_tls_session_cache_database = btree:/var/run/smtp_tls_session_cache
    #smtp_tls_session_cache_database = sdbm:/var/run/smtp_tls_session_cache

  27. Tutorial was easy enough to follow, but I can’t seem to get it working. Getting the following error:

    Jan 20 10:17:36 unknownf81edfe4dce3 Mail[1098]: [ mechanism: PLAIN security layer: no] Failed to start the SASL connection

    1. Let me provide a little further info here: My primary reason for enabling postfix was so that I could test the outgoing emails for a website that I’m developing on my local machine. While looking at some of the difficulties others were having, I started postfix with – sudo postfix start. During the process I received the following warnings:

      $ sudo postfix start
      postfix/postfix-script: warning: not owned by root: /etc/postfix/aliases copy
      postfix/postfix-script: warning: not owned by root: /etc/postfix/generic copy
      postfix/postfix-script: warning: not owned by root: /etc/postfix/main.cf copy
      postfix/postfix-script: warning: not owned by root: /etc/postfix/sasl
      postfix/postfix-script: warning: not owned by root: /etc/postfix/sasl/passwd
      postfix/postfix-script: warning: not owned by root: /etc/postfix/sasl/passwd.db
      postfix/postfix-script: starting the Postfix mail system

      However, after starting Postfix, I found that the outgoing mail from the website I was developing began working, but I still could not sent email from the terminal and I’m still seeing the error log message reported in my original post.

      1. Joe,

        can you check the ownership of the files under the /etc/postfix directory? They should belong to root user, and the wheel group.

        If they belong to another user (as is being pointed out by the error message), then use the chown Unix command to change the ownership to root.

  28. Thank for the quick feedback, especially on a Sunday with playoff football.

    I changed the root ownership and was able to successfully send an internal email ($ mail # Output of the `whoami’ command), but I still cannot send an external email through gmail from terminal. The problem seems to be that the local user address is not mapping to a valid Internet email address. (I did run postmap after editing the generic file.) The returned email shows that postfix is attempting to send the email to:




  29. Thanks for the detailed steps. Just one thing I had to correct on my computer:
    This line below, whenever it is used
    needs to be replaced by
    because my system and library directories are all small letters.

  30. if you replace this section of the .plist


    with this

    it keeps the service running otherwise it shuts down after 60 secs

  31. Hi evolve75, Nice Tutorial!! But I’m getting this in the mail log:

    relay=smtp.gmail.com[]:587, delay=2.2, delays=0/0/2.2/0, dsn=4.7.8, status=deferred (SASL authentication failed; server smtp.gmail.com[] said: 535-5.7.8 Username and Password not accepted. Learn more at?535-5.7.8 http://support.google.com/mail/bin/answer.py?answer=14257?535 5.7.8 {BADCREDENTIALS} x52sm14029434yhh.18 – gsmtp)
    Jun 15 19:33:50 localhost postfix/master[299]: master exit time has arrived

    Can you help me?

    1. Ocombita,

      Can you recheck the user ID and password? Specifically, the user ID does need to have the “@gmail.com” fragment at the end. Also, if you have enabled Google’s two-factor authentication, then you will need to generate an application specific password for using in Postfix, as the web password will not work.

  32. hi,
    Please i try to send external mail after configuration but i have this: MAILER-DAEMON@MacBoo…”Undelivered Mail Retu”
    Somebody can help me?

  33. Anyone else having trouble with step 5?

    > sudo postmap passwd
    > postmap: fatal: open database passwd.db: Permission denied

    I’m on a Powerbook pro running 10.7.5

  34. Hello,
    Thank you for the great tutorial, but it is not working for me. When I type “launchctl load -w org.postfix.master.plist”, I get an error:
    $ launchctl: no plist was returned for: org.postfix.master.plist
    $ launchctl: no plist was returned for: org.postfix.master.plist
    nothing found to load

    Running OS X 10.6.8. Everything else matched up as expected with the tutorial.


    1. I found my problem, I had a typo in the org.postfix.master.plist file. If you use the following command, it should output the line number you have a problem with.
      ( plutil -lint org.postfix.master.plist )
      You may need to put in the full path to the plist file if you are not in the LaunchDaemons directory.


      1. Also, make sure the email ports are not being blocked by the Firewall. I work from different sites throughout the week, and the site I was trying to test from was blocking the SMTP ports. So even if you did everything right, you may not be able to send external email. Use the “tail” command posted above to try and isolate the problem you may be having. ( tail -f /var/log/mail.log ) If you see an error about “no route to host”, then your ports may be blocked. Do a port check on the following site: http://www.yougetsignal.com/tools/open-ports/


  35. Thanks! It worked! I have another os x 10.8.4 macmini I just set up for web development, and I tried and tried to get php mail to work with zero experience and success. I got PHP working pretty easily but not PHP Maill!!! Took me tons of web searching and fussing, and nothing worked until I found your very detailed instructions, which are actually quite educational, too, indirectly and beyond blindly typing the commands.

    After I ran the test at the end, I received all the queued outgoing messages from my test website’s contact form that uses PHP mail and that runs on the macmini.. Hurray! My contact form and PHP processing work, and I don’t have to FTP upload the new site to the webhost to find out.

    VIM is insane, though. What a VCR-like piece of garbage. I worked at Sun Microsystems back in 1988 but not programming and people back then bragged about using VI. Complete and utter clubby ridiculous BS and the type of hubris and outlook that cost Sun its life, in my opinion. MS should never have had so many whacks at Windows while Sun and NeXT self-pleasured away from the wider market mocked by people who love VI. VI sucked and still does.

    To use your guide, I ended up using TextWranger and Nano because I didn’t feel like wasting my time trying to figure out how use VIM (e.g., hitting ESC didn’t bring up a menu prompt); I’m sure I could have found all the VIM instruction I needed online, but that’d be like reading a VCR manual after the VCR’s been dead for years.

  36. Hi, I am looking forward to getting this to work! Just cause its really cool.. Seems I cannot get past.. the following command. Im not sure what Im missing. ( I did try and read all the post to see if someone else mentioned it. Im am running OSX 10.8.4. Everything seemed fine till i execute this.

    $ sudo newaliases

    $ newaliases: fatal: bad string length 0 < 1: mydomain_fallback =

    So then I do this:

    $ grep mydomain_fallback /etc/postfix/main.cf
    mydomain_fallback = localhost

    Did I miss a step?



  37. Thanks for this great tutorial! Have been trying to get this to work for a few hours. I’m getting this error when I access the log (tail -f /var/log/mail.log)

    connect to smtp.gmail.com[]:587: Operation timed out
    Sep 27 19:59:37 Abrahams-MacBook-Pro.local postfix/smtp[376]: warning: BF53D260783: defer service failure
    Sep 27 19:59:37 Abrahams-MacBook-Pro.local postfix/smtp[376]: BF53D260783: to=, relay=none, delay=2856, delays=2795/0.05/60/0, dsn=4.4.1, status=deferred (connect to smtp.gmail.com[]:587: Operation timed out)

    Anybody have any ideas?

    I’m running OS X 10.8.4 on a 15″ mac book pro retina.

    There was a comment somewhere about a main.cf.default file possibly being a problem – this file exists for me in the /etc/postfix directory. I also had tried to install an email account in the mail, contacts and calendars system preferences, which I then deleted – not sure if that made problematic changes?

    Any help would be appreciated!

    1. Things I would look for are:
      1. Make sure the ports are open on your firewall. Do a port check on: http://www.yougetsignal.com/tools/open-ports/
      2. There may be a problem with your Gmail account. Create a new temp Gmail account with a single / easy password, update your postfix files and see if it works.
      3. There may be other router or firewall issues that you are not aware of. Does this work from another location? Can you configure a Mac laptop for testing and do it from somewhere else with the same Gmail account?

  38. Using smtp_tls_security_level=encrypt is “strictly discouraged”, according to http://www.postfix.org/TLS_README.html

    I set mine up using smtp_tls_security_level = secure, which requires one to acquire certificates for these settings:

    smtp_tls_CApath = /etc/postfix/certs
    smtp_tls_CAfile = /etc/postfix/cacert.pem

    I also added

    smtpd_tls_session_cache_database = btree:/var/lib/postfix/smtpd_scache
    smtp_tls_session_cache_timeout = 3600s

    to cut down on overheads.

    I don’t really understand the purpose of setting up smtp_generic_maps. All the tests work without it. Certainly using the mail command to send local mail works and never tries to go outside the machine, so it never uses the mapping.

  39. I am trying to configure Jenkins to send email notifications using postfix.
    I have followed your tutorial as everything works using the terminal.
    My question is how do I use the postfix with other applications e.g jenkins . as an smtp server.
    How do I refer to it? is it which does not work or something else I am missing?

    1. You might want to check out my follow-up article, which has an alternate configuration for launchd, and which allows postfix to listen into the local SMTP port 25.

      This will allow you to use postfix as the local SMTP server for other applications such as Jenkins.

      Hope this helps, and happy holidays!

  40. I configured everything properly,however outbound mails are not being delivered. Is there anything am missing? Is the problem due to my “sender” local hostname?

  41. Hi,

    How about incoming email also coming via gmail or another ISP mail server?

    The local users would have account with the local postfix which would be mapped (in the postfix config) to the ISP mail server account. When exchanging emails with the outside world, the local users would be known by the ISP mail address, for both receiving and sending.

    How can be done?

    Thank you,

  42. I’m getting this: delivery temporarily suspended: TLS is required, but our TLS engine is unavailable

  43. Didn’t sent any external email at first.. checked the log (/private/var/log/mail.log). And found: “… etc/postfix/sasl/passwd.db: No such file or directory”

    must have forgotten to run the: ‘sudo postmap passwd’ command.

    sudo postmap /etc/postfix/sasl/passwd
    sudo postfix reload

    and it works like a charm!

    Thank you for your help!

  44. I too was getting that “530-5.5.1 Authentication Required” message until I changed all instances of gmail.com to googlemail.com (which is what my account was originally set up as, when gmail was someone else’s trademark)

  45. Thanks for the tut goy my postfix finally working
    After many hours, was about to give up but thanks to you got it working

  46. Hi, very good tutorial, but I can not test the email. At the end of the tutorial is confusing to me that Control-D. I put the mail command and my user_id, but not out of it. Control-D does not work, and press enter, the following error appears:

    -bash: syntax error near unexpected token `newline ‘

  47. To get this working for me on Yosemite, I needed to add “/Library/Server/Mail/Data/spool/maildrop” to the QueueDirectories list.

    1. Also, I recommend deleting the “passwd” file after running “sudo postmap passwd”. I don’t like leaving a plain text password file lying around, and this isn’t used after running postmap.

  48. Hi,

    Just wanted to thank you for your tutorial. It is very well done.

    I implemented this so that I can use the PHP mail function in the projects I am working on my local system with a XAMPP server. I am able to send mail via my command line, but whenever I use the php mail function it always returns false. In my log file There are no errors. I just see notifications of postfix starting up and stopping. Any suggestions?

Leave a Reply to cposey Cancel reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s

This site uses Akismet to reduce spam. Learn how your comment data is processed.