Aller directement à la fin des métadonnées
Aller au début des métadonnées

Documentation Search

CiviCRM 4.3 Documentation

Developer Resources

CiviCRM books!

Make sure to check out our Online User/Administrator and Developer Guides! You can also support this project by ordering a hard copy.

Or support us by buying an eBook or hard copy of Using CiviCRM from Packt Publishing.

Not Up to Date

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.

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.


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).


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):


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:

Or like me you might have forgotten to setup

The Mail Accounts in CiviCRM Admin Mail area.