This documentation refers to an older version of CiviCRM (3.4 / 4.0). View latest version.

Skip to end of metadata
Go to start of metadata
This page refers to CiviCRM 3.4 and 4.0, current STABLE version.

Documentation Search

CiviCRM 3.4 and 4.0 Documentation

Support and Participation

Developer Resources

CiviCRM books!

Make sure to check out the FLOSS Manual Understanding CiviCRM as well! 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.


The email processor is a script that will attempt to parse emails in an email account (e.g. a POP3/IMAP inbox) and record a copy as an activity in the contact records that correspond to the To:, Cc:, Bcc:, and From: fields. If no matching contact record is found, a new contact will be created and the email filed under that record.

Note that the EmailProcessor.php script also performs bounce mail processing. Take note of how the mail accounts are setup to distinguish those used for activity auto-filing vs. bounce processing.


  1. If you don't already have it enabled, enable CiviMail under Administer >> Configure >> Global Settings >> Enable CiviCRM Components. You don't need to fully configure or use CiviMail functionality, but it must be enabled in your system in order to activate the email autofiling tool. If you are using Drupal, set permissions to give you access to CiviMail.
  2. Under Administer CiviCRM >> CiviMail >> Mail Accounts, configure one or more email accounts. In the "Used For" field select Email-to-Activity Processing.
  3. Test it by invoking the processor's url:
    Drupal: http://domain/sites/all/modules/civicrm/bin/EmailProcessor.php?name=username&pass=password&key=site_key&emailtoactivity=1
    Joomla: http://domain/administrator/components/com_civicrm/civicrm/bin/EmailProcessor.php?name=username&pass=password&key=site_key&emailtoactivity=1
    1. "domain" is the site domain name
    2. "username" is some valid username
    3. "password" is that user's password
    4. "site_key" is the site key as described under Command Line Script Configuration
  4. The first time you run the script you should see folders created in your email account to designate processed and ignored emails. After testing, visit the contact record you emailed to and confirm the presence of the email activity.
  5. Optionally set it up to run regularly via cron. You may want to redirect the output to a log file.
Tip #1

If you do not intend to utilize the autofiling email activity feature you can remove the &emailtoactivity=1 portion from the above URLs. Doing so will cause the script to only utilize the Bounce Processing functions.

Tip #2

In the typical implementation you will create a single email account that is used solely for the purpose of autofiling as activities. As you interact with constituents using your email client, you may cc or bcc this account in order to have the email processed for the contact. While you may choose to process your normal incoming email accounts using this tool, doing so may unnecessarily clutter your system, as many inbound emails are not important enough to attach to a contact record in this way.

Another possible implementation to consider if your mail server supports IMAP is:

  1. Create a mail folder that will be used to indicate to the processor what emails should be processed. Let's call it "civicrm".
  2. In step 2) above, in the Source field, enter the path to this folder. Note it will typically be "INBOX.civicrm", not just "civicrm".
  3. If you want an email in your inbox to be autofiled, move it into this folder. If your mail client supports it, make a copy of the email rather than simply move it, as you likely will want the email to remain in your Inbox or be filed in your primary folder structure.
  4. The processor will create subfolders INBOX.civicrm.CiviMail.processed and INBOX.civicrm.CiviMail.ignored, and will move the email into one of those when done.

Tip #3

If you are using Thunderbird as your email program, there is a Bounce plugin that allows you to send a copy of the email to another address (in this case the single email address set up in Tip 2) with the headers intact the same as when it was sent to you. This is different from forwarding where you lose the original From, To, and Cc information, and so will allow the email processor to file it correctly.

Tip #4

Another possibility if you are having trouble configuring a mail account to work with your specific server, is to use an intermediary. For example you could write a script to use a program like getmail to pull from the account into a local unix maildir, and then configure the CiviMail account to use the maildir protocol.

  • None