Email: Send emails via SMTP Relay

All recent TurnKey servers ship with Postfix MTA (Mail Transfer Agent) pre-installed and configured to send emails directly from your server. By default, this includes system emails, such as info about installed security updates as well as application specific emails - e.g. MediaWiki, WordPress and most other included software.

However in this day and age (with so many spammers), ensuring that your emails arrive can be really hard. Many mail providers will silently block/drop mail from random IP addresses (i.e. your TurnKey servers). Even if they do arrive, the chances of them automatically being flagged as spam are very high.

If your server has a static IP, it is possible to configure your server appropriately to increase the chances of them being delivered and not flagged as spam. E.g. by configuring all the relevant acronyms - such as PTR, DKIM, SPF, DMARC and possibly MX - if you want to also receive mail (how to do all that is beyond the scope of this doc page). However, you will also need to monitor mail blocklists to ensure that your server's IP doesn't get blacklisted.

So for most users, it's much easier and generally more reliable to send emails via an SMTP relay. This doc page covers the basics, but if you have more specific queries, please start a new thread in the forums.


As noted, all recent TurnKey servers include Postfix MTA. Confconsole (our custom CLI config tool) supports simple SMTP relay configuration. Assuming that you configure it correctly - using the relevant credentials provided by your SMTP relay service, that should "just work".

As well as system emails, the specific appliance software within your TurnKey server (e.g. MediaWiki, WordPress, etc.) should also be pre-configured to use the local Postfix MTA. So unless you wish to use an alternate SMTP relay to send application specific emails, beyond possibly configuring a relevant application specific "from" address (within the software itself) no additional email configuration will be required. If you wish to use an alternate SMTP relay for your appliaction itself, most software should be able to configure that, but will be different for each software. Please see the relevant application documentation for how to do that.

Configuring the system email "FROM" address

As noted above, most of the specific appliance software within the TurnKey library (e.g. MediaWiki, WordPress, etc.) has facility to configure the "FROM" address (see specific application configuration for further details). However, when using a configuration such as that, the system emails will default to be being sent from root@hostname (where 'hostname' is the actual hostname of your server - if desired, that can also be configured in Confconsole). Personally, that's how I leave my servers and so long as each server you run has a unique hostname, that will be sufficient for many users. However, some users may want a specific from address. In fact, some SMTP relay services may even require that your mails comes from a specific email domain/address.

To configure a custom "from" address for the generic system emails - rather than the default "root@localhost" - please follow the below steps. Note that a text editor will be required. CLI text editors nano and vim-tiny (a minimalist vim) are preinstalled in TurnKey by default, although I personally install neovim these days ('apt update && apt install neovim -y'). Using Webmin's built in text editor is another option if you prefer a web UI. The below example config assumes you wish to send emails as ''.

Firstly edit the main Postfix config file; /etc/postfix/ and add this line:

smtp_generic_maps = hash:/etc/postfix/generic

Then create a /etc/postfix/generic file as below (where 'hostname' is your server hostname and '' is the from address that you desire):


Generally, for system emails you will only need to add the above for root. However, additional Linux users can be added if desired/required. Do that by adding addition lines like this (where 'userA' is the local Linux user and assuming the same custom "FROM" address as above):


Then to apply the updated Postfix config, run Postmap & restart Postfix (assuming running as root user - if not, prefix each line with 'sudo'):

postmap /etc/postfix/generic
systemctl restart postfix

Now all outgoing emails previously sent from root@hostname (and userA@hostname if configured) will automatically have the FROM SMTP field sent as

The below are for configuring specific STMP relay services. Please note that this documentation is quite dated and may no longer be relevant - simply using the Confconsole MTA plugin as noted above should be sufficient. However, the below is likely still relevant if you'd prefer to manually configure things. If you are trying to use any of this documentation and find errors or problems, please feel free to open a new thread in the forums to get assistance. Alternatively, if you succeed to configure one of the below services and the below are not quite right, please feel free to edit this documentation (must be logged in).

Other Configuration

The following postfix configuration is general for all smtp relay services tested to date:

append config to /etc/postfix/ :

cat >> /etc/postfix/ <<EOF

smtp_sasl_auth_enable = yes
smtp_sasl_security_options = noanonymous
smtp_sasl_password_maps = hash:/etc/postfix/sasl_passwd
smtp_tls_CAfile = /etc/ssl/private/cert.pem
smtp_use_tls = yes
inet_protocols = ipv4

Depending on what relay service you're using the following steps might be slightly different. The following examples show how to setup using the Gmail SMTP relay service, Elasticemail's service and Amazon SES. If you have a different service, then hopefully the below will give you some ideas to check.



(It is recommended that you DO NOT use your personal gmail account for this)

add Gmail as the SMTP relay in /etc/postfix/ :

sed -i "s|^relayhost =.*|relayhost = []:587|" /etc/postfix/

then add your username and password to /etc/postfix/sasl_passwd Replace USERNAME with your username (note for Google Apps accounts replace with USERNAME@YOUR_DOMAIN.TLD) and PASSWORD with your password.

cat > /etc/postfix/sasl_passwd <<"EOF"

run postmap on your new password file

postmap /etc/postfix/sasl_passwd

If for whatever reason you disabled TLS you'll need to allow access to your gmail account from postfix, to allow that go to the following link when logged into your google account and click "Turn On" However it is highly recommended you don't do this.

Finally restart postfix"

service postfix restart

and you're done!



First of all as with the gmail setup you'll need to edit /etc/postfix/ and set your relayhosts to the relevant host, in this case

sed -i "s|^relayhost =.*|relayhost = []:587|" /etc/postfix/

and then you'll need to set your login details inline with the ones you find at in your /etc/postfix/sasl_passwd file
 like so (replace USERNAME and PASSWORD with your username & password).

cat > /etc/postfix/sasl_passwd <<"EOF"

now run postmap on your /etc/postfix/sasl_passwd file

postmap /etc/postfix/sasl_passwd

and restart postfix and you should be good to go!

service postfix restart


Amazon SES

Firstly you'll need to choose your preferred region and obtain your SMTP account details (not the same as your amazon account details). You can read about this from the following links. Region List SMTP Credentials

You'll also need to authenticate the email address you wish to use to send mail, you can do this from Amazon Console by clicking SES, then "Email Addresses" under "Identity Management"


now we'll need to edit /etc/postfix/

if you see a line with "relayhost =" replace that, otherwise add the following to the end

relayhost = [region-you-selected]:25

now you'll need to edit /etc/postfix/sasl_passwd so it has authentication to access the server with.

[region-you-selected]:25    smtp-username:smtp-password

now run

postmap /etc/postfix/sasl_passwd

and restart postfix and your server should be working


If you are still in sandbox mode you'll have to authenticate the addresses you send mail too as well as the addresses you send mail from.


Jeremy Davis's picture

Hopefully I've fixed it now :)