Scenario: Drupal 6 running on a Fedora 8 VPS requiring to send outgoing mail only via a Bluehost mail server.

Intro

This is a very common scenario. Our web server is running on one box and our email server on another. Like every CMS out there Drupal needs outgoing mail access to send out user notifications.

Note that if you are setting up a new domain that has no existing email server then you have no option but to configure postfix as a fully fledged SMTP server. This is not covered here.

Setup Drupal

Under Drupal Administer menu Site configuration - Site information enter the name that will appear in the from address of all Drupal generated emails. In this case we will use webmaster@example.com. Make sure that whatever address you use represents a valid account on your email server.

Enable Postfix

Authenticate as root and start postfix for the first time.

Enable it to start at run time.

When postfix encounters a problem or cannot relay a message correctly then check out the log file. It is the main source for troubleshooting diagnostic info.

Basic Postfix Configuration

Postfix is to be configured not to accept any mail but to act solely as an SMTP client (also known as a null client: http://www.postfix.org/STANDARD_CONFIGURATION_README.html). In this mode postfix will accept no mail whatsoever.

To configure as null client (send mail only) we need to edit main.cf.

Modify main.cf to define the domain you want to send your email from. myorigin = $mydomain means that email origin is me@example.com not me@www. example.com

Modify main.cf to specify what host to send (relay) your email to. In this case postfix will consult the DNS zone for example.com and retrieve its MX record - let's say the MX resolves to mail.example.com. So all our outgoing mail will be routed through mail.example.com. Note that our email provider uses non standard SMTP port 26.

The inet_interfaces setting means that network mail will only be accepted from the local host.

You may also find it useful to turn on verbose debug logging for the localhost at this stage. So in main.cf:

Save main.cf.

Now configure master.cf. This file controls which postfix sub components are active.

Modify master.cf to prevent any local mail delivery. Comment out the local delivery agent.

Save master.cf and restart postfix

Postfix should now be able to relay mail. Try sending mail from Drupal or from a terminal using mail or sendmail. Then examine the maillog. You will almost certainly encounter something along the lines of:

(www.example.com) [an.ip.add.ress] is currently 550-not permitted to relay through this server. Perhaps you have not logged 550-into the pop/imap server in the last 30 minutes or do not have SMTP 550 Authentication turned on in your email client. (in reply to RCPT TO command))

Just like any SMTP client postfix needs to authenticate.

Authentication

Postfix uses the SASL module for authentication. In Fedora 8 postfix comes with cyrus SASL compiled in. In any case you can check if cyrus SASL is installed with:

Modify main.cf. The following entries probably will not have pre-existing defaults.

Now create the file, etc/postfix/sasl_passwd, that will hold our SMTP username and password for the example domain. Note that the domain entry must match the resultant value of main.cf's relayhost, including the port number. Note also that for this ISP the SMTP account username is of the form username+domain rather than username@domain.

Save sasl_passwd and convert to a lookup table.

Postfix should now be able to perform SMTP authentication against your mail server. Restart postfix and try sending another test email, but don't be surprised if it still doesn't succeed. If so, check the maillog and you may see something like (with debug_peer_list = 127.0.0.1):


May 29 15:39:24 vm610 postfix/qmgr[370]: 7676E3675A: from=<apache@example.com>, size=678, nrcpt=1 (queue active)
May 29 15:39:25 vm610 postfix/smtp[381]: 7676E3675A: to=<somedummy@yahoo.com>,
relay=mail.example.com[69.89.31.117]:26, delay=1.1, delays=0.04/0.01/0.91/0.16, dsn=5.0.0,
status=bounced (host mail.example.com[69.89.31.117] said:
550-Verification failed for <apache@example.com>
550-No Such User Here 550 Sender verify failed (in reply to RCPT TO command))


Our SMTP server is complaining that apache@example.com does not exist. To remedy this issue we need to do an address rewrite.

Canonical Mapping

In Drupal we entered webmaster@example.com as the from address in automated emails. However, when Drupal sends an email it is the httpd daemon user that issues the mail request to postfix. On Fedora the default name of the httpd daemon user is apache.

Fortunately we can use the postfix canonical map file to rewrite our email addresses so that whenever apache@example.com sends an email postfix substitutes webmaster@example.com in its place.

Edit main.cf to include

Edit the canonical map file and enter addresses to be mapped.

Reload postfix and try sending mail. If mail delivery still fails then validate that your SMTP authentication details are correct and review your edits in main.cf, master.cf, sasl_passwd and canonical.

Sources

There are lots of postings with regard to configuring postfix as an SMTP client only. Some I found most useful were:

http://www.postfix.org/SASL_README.html
http://www.teknolio.com/blog/how-to/set-up-postfix-with-a-remote-smtp-relay-host/
http://wiki.zimbra.com/index.php?title=Outgoing_SMTP_Authentication

For a decent overview of postfix see:
http://www.akadia.com/services/postfix_mta.html

For postfix debugging info see:
http://www.postfix.org/DEBUG_README.html

If you need paper try: Postfix: The Definitive Guide (Paperback) by Kyle Dent.