After reading the Phabricator documentaton for Configuring Inbound Email you may be forgiven for simply running up an account on Mailgun or Sendgrid. On the flipside, if you don't want your email to be routed through a third party provider, then a local MTA is the only answer. Don't get too scared by the documentation, it's actually fairly easy:
- Phabricator up and running.
- A server hosting your Phabricator email, it may be the same server as Phabricator is installed on or it may be somewhere else. For instance 'phab.example.com' or similar. It's assumed you've got all the MX records set up for mail delivery.
- A catch-all IMAP mailbox on that relevant mail server.
- Mail being delivered to that catch-all mailbox.
- Root access on your Phabricator server (you've got that, haven't you?) or be nice to your sysadmin. Required so you can install Fetchmail.
- Ability to get a shell on your server for the same user that Phabricator is installed under.
If you send an email to that catch-all mailbox and it arrives, then you can go ahead, configure Phabricator and install Fetchmail:
- Set up your metamta settings per the Phabricator configuring inbound email page. E.g set your metamta.default-address setting to firstname.lastname@example.org.
- On your mail server or control panel for the mail server, set up a catch all, something boring like "email@example.com". This will scoop up all email sent to that domain. Note: There are so many methods and web panels to do the set up of a catch-all for a domain, I'll leave this up to you to work out.
- Next you'll, need to install fetchmail:
sudo aptitude install fetchmail
(or yum, apt-get etc etc depending on your distro and personal taste)
Then create a .fetchmailrc file in the home directory of the user that phabricator is installed under. Let's call our user 'phab' for this example.
$ sudo su phab
// e.g /home/phab (for instance, your ~ may vary)
$ touch .fetchmailrc
$ chmod 0600 .fetchmailrc
$ vim .fetchmailrc
The contents should look something like this
set daemon 60
set logfile "/home/phab/fetchmail.log"
poll mail.phab.example.com protocol imap port 143:
user "catchall" pass "some.password"
I'll go through the lines one by one:
- set daemon 60 : The fetchmail daemon will poll the configured server every 60 seconds. Change the value as you think necessary.
- set logfile "/home/phab/fetchmail.log" : sets up a log file location for fetchmail. Helps with debugging. Optional.
- poll mail.phab.example.com protocol imap port 143: : means 'poll' the mail server mail.phab.example.com using IMAP on port 143. Your mail server will not be mail.phab.example.com.
- user "catchall" pass "some.password" : using this username and password for the catchall mailbox
- mda "/home/phab/path/to/phabricator/scripts/mail/mail_handler.php" : redirect the mail found to this script
- sslproto tls1 : use TLS1. If you specify an "ssl" command in the fetchmailrc and you have both SSL2 and 3 disabled (See POODLE) then this will fail. Using sslproto on it's own without ssl does the trick and forces TLS usage.
- no rewrite : do not allow fetchmail to rewrite any mail headers, this is important.
- no keep : delete email off the server after downloading, this is important.
- fetchall : get all email, regardless of whether it's been viewed or not. If you log into the mail server and view emails, you still want fetchmail to download them.
Finally, a semicolon ends the rules for the "poll" settings.
Once this is done, run "fetchmail -v". Fetchmail will background and daemonise per the settings. If you don't wan't verbose mode, omit the "-v".
If all goes well, you should be able to see email replies going into Phabricator within 60 seconds. Phabricator helpfully bounces email with details back to you if something went wrong.
Gotchas and helpers:
- There is a bug with using a "Personal (IMAP)" account in the Gmail App for Android in that it doesn't respect the Reply-To header. This means you can't reply to emails using the Android Gmail app for Personal IMAP accounts and possibly the legacy Email app as well.
- Run Fetchmail with fetchmail -v to log requests to your fetchmail log file
- Tail your system mail logs, if you can, to check that the email connection is being made. If you experience errors or auth issues they will be logged here.
- Run ./phabricator/bin/mail list-inbound to check inbound email status.