What's this page about
This page describes the PHP-based counterpart to imap2soap for polling a IMAP/POP3/Maildir mail source for CiviMail-targetted emails and processing them in the context of a given CiviCRM/CiviMail installation.

This method isn't the recommended one. Use the MailProcessor method instead

The purpose behind the CiviMail Processor

When you have a CiviMail install that's actually sending mail, it's a good idea to have a processor for the return channel - so at least you can track bounces and replies to your mailings (and get the benefit of SMTP actions, like subscribe, unsubscribe, resubscribe and opt-out working as well).

In the past, the only solutions for a working return channel was to either setup our patched version of AMaViS or use imap2soap, a third-party Perl solution. CiviMail Processor is the PHP counterpart of imap2soap, in that it polls periodically the given mail source and processes all CiviMail-related messages found there.

CiviMail Processor's capabilities

CiviMail Processor is able to poll IMAP and POP accounts, as well as local Maildir directories.

When polling POP and Maildir sources, the messages are removed from the source and put in CiviMail.processed and CiviMail.ignored subdirectories of your Custom Files directory (usually ...files/civicrm/custom).

When polling an IMAP source, the messages are moved from INBOX to INBOX.CiviMail.processed and INBOX.CiviMail.ignored mailboxes in the IMAP account (where the dot represents the hierarchy separator; in GMail's case this is represented as labels).

Usage

The accounts to poll are configured in CiviCRM Admin → CiviMail → Mail Accounts. Note that to catch bounces, you must use a catchall account unless your mail server supports sub-addressing (a.k.a. plus addressing, address extensions, recipient delimiter (Postfix)) i.e. using a separator such as '+' to enable addresses of the form civimailuser+b.123.456.abcdef0123456789@xxx.org.

Once you do this, you can test whether the polling works by visiting CiviCRM-Resource-URL/bin/CiviMailProcessor.php?name=username&pass=password&key=key (with the bold parts replaced by your site's CiviCRM Resource URL, credentials pair of a user with CiviMail access and your site's key).

make sure the username and password are for the drupal or joomla user. And that this user has the proper permissions for civicrm and civimail.

Making it run periodically

If you're sure your script is working, the easiest way to make it run periodically is to add a cronjob entry utilizing the wget or curl commands. To poll the mailbox every ten minutes, the entry would look something like the below (you might want to setup different wget and curl options - like wget's --delete-after - if you want to discard the results):

*/10 * * * * wget '...resource-URL.../bin/CiviMailProcessor.php?name=...&pass=...&key=...'

or

*/10 * * * * curl '...Resource-URL.../bin/CiviMailProcessor.php?name=...&pass=...&key=...'

Also you still need to setup the out-going Cron job. This is what tells CiviMail to send scheduled mailings.

http://wiki.civicrm.org/confluence/display/CRMDOC/CiviMail+Installation

Trouble Shooting

Cron Job

incase the above does not work for you I had to wrap my wget like this

*/10 * * * * wget -O - -q 'URL INSIDE HERE'

Missing Protocol Options

For Sites upgraded from previous versions of CiviCRM, you may need to run this SQL (via phpMyAdmin or the command-line) to populate the Mail protocol options:

INSERT INTO `civicrm_option_group` (`name`, `label`, `description`, `is_reserved`, `is_active`) VALUES
('mail_protocol', NULL, 'Mail Protocol', 0, 1);

SELECT @option_group_id_mp := max(id) FROM civicrm_option_group WHERE name = 'mail_protocol';

INSERT INTO `civicrm_option_value` (`option_group_id`, `label`, `value`, `name`, `grouping`, `filter`,
 `is_default`, `weight`, `description`, `is_optgroup`, `is_reserved`, `is_active`, `component_id`,
 `visibility_id`) VALUES
( @option_group_id_mp, 'IMAP', '1', 'IMAP', NULL, 0, NULL, 1, NULL, 0, 0, 1, NULL, NULL),
( @option_group_id_mp, 'Maildir', '2', 'Maildir', NULL, 0, NULL, 2, NULL, 0, 0, 1, NULL, NULL),
( @option_group_id_mp, 'POP3', '3', 'POP3', NULL, 0, NULL, 3, NULL, 0, 0, 1, NULL, NULL);

Or like me you might have forgotten to setup http://yoursite.org/civicrm/admin/mailSettings?reset=1&action=browse

The Mail Accounts in CiviCRM Admin Mail area.

Oops