This page isn't up to date anymore as it references a deprecated script: /bin/CiviMailProcessor.php. The new method of handling incoming mail is described on this book page.

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.


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.


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

The catch-all account has to be marked as the default account using the checkbox. Otherwise, Civimail ignores the mail account information, generates a Return-Path with a blank domain, which leads to a 501 - Recipient not recognized SMTP error when mailing is attempted. (As of Civicrm 3.2.5).

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/EmailProcessor.php?name=...&pass=...&key=...'


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

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

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

The Mail Accounts in CiviCRM Admin Mail area.