Configure Xcode Server to send SMTP Email

In my previous post on Xcode Server, I discussed the Xcode Server feature to send issue notification and summary email messages, and how to configure email triggers as part of integration configuration. In this post, I’ll discuss how to configure a MacOS Xcode Server machine to actually route email messages to the development team.

The Documented Way to Configure Xcode Server

As of this writing, the Xcode 10 documentation provides a single — and sparse — manual page on configuring Xcode Server to send email via SMTP:

This seems very straightforward. You should add your outgoing SMTP server information and send from info — and Xcode server will send email. It should just work, right?

There’s only one problem with this procedure…for many people — including me — this doesn’t work.

Most likely this simple configuration can work in some environments, but Apple provides no information in the documentation regarding prerequisites and what type of SMTP environment this configuration is designed for.

No worries, though — next I’ll cover how to configure your Xcode server to work with any type of SMTP-based email infrastructure.

Note: if you know how to get the default Xcode configuration to work with authenticated, TLS-based email back-ends, please let me know in the comments!

Configuring Xcode Server to Send Email via Postfix

If you’ve installed Xcode 10 on macOS Mojave (and probably previous versions of both — though I’m only covering Xcode 10 here), your Xcode server hardware should already have a dormant installation of Postfix pre-installed. We’ll use that existing install of Postfix to get email delivery going with Xcode server.

Note: I use SMTP2GO as my SMTP provider for Xcode server, so the following instructions are specific to that service. This same procedure can work with other providers like Gmail, Office 365, and other services that provide SMTP with or without an encrypted SMTP connection. Adapt the settings below as required to match the requirements of your SMTP provider.

#1 Don’t configure Xcode’s email options

First, don’t configure Xcode’s email settings at all — just leave them blank. On your Xcode server, open Xcode Server configuration and ensure all fields are left blank, as in the documentation image above.

#2 Add your SMTP server credentials to the Postfix password file

Next configure your Xcode server Postfix installation with the username/password needed to authenticate with your SMTP server when sending e-mail.

Create or modify the /etc/postfix/sasl_passwd file using your favorite editor, for example:

$sudo nano /etc/postfix/sasl_passwd

Add a line that provides a valid username/password combination and corresponding server/port, with your own SMTP authentication credentials, similar to the following:

#3 Run Postmap agains the password file

sudo postmap /etc/postfix/sasl_passwd

#4 Add Configurations to Postfix

Open the Postfix configuration file with your favorite text editor, for example nano:

$ sudo nano /etc/postfix/

Add correct configuration lines as required by your email provider. For smtptogo, I use the following:

relayhost =

Note that the relayhost in should match the url:port in the previous password file exactly.

It’s OK to add these configurations to the bottom of the file, but search the file and comment out any existing settings that would duplicate what you add.

#5 Start Postfix server on the Xcode Server machine

$ sudo postfix start

#6 Set Postfix to Auto-Start on the Xcode Server machine

Edit the postfix service configuration file using your favorite text editor, e.g. nano:

$ sudo nano

When Postfix is running, and your security configurations are correct — and the Xcode server mail settings are left blank — Xcode server will successfully send email when your email triggers are fired in Xcode integrations!

Rob Kerr
App development for iOS, creating applications for my own development studio (Cuvenx Inc.), and consulting with awesome clients to build their mobile applications.
Ann Arbor, Michigan, USA

Copyright © 2021 Rob Kerr