Introduction

CiviMail installation consists of four parts: enabling the CiviMail component, setting up the SMTP configuration options, defining a cron job that will actually send the scheduled mailing, and choosing and setting up the return email channel.

If you want to have an email system that works properly we strongly recommend you read this entire chapter. Skiping over any of these steps can result in high bounce rates, which can get your domain blacklisted. If after following these instructions your email system does not work, please read this chapter again. An older, yet more detailed version of these instructions, can be found at http://en.flossmanuals.net/CiviCRM/SystemConfigurationhttp://en.flossmanuals.net/civicrm/ch042_system-configuration/ 

Setting Up CiviMail

If the CiviMail component is not enabled, go to CiviCRM > Administer > System Settings > Enable CiviCRM Components and enable CiviMail.

Make sure your Organization Address and Contact info is set under /civicrm/admin/domain?action=update&reset=1

Go to CiviCRM > Contacts > Manage Groups and click the "settings" link for the group you want to make available to CiviMail. Check the box that says "Mailing List". Save your settings and repeat for each additional group you would like to send mailings. If you do not complete this step, you will not see any groups when you try to send a mailing.

Drupal User and Role

For CiviMail to work in Drupal you must create a Drupal user with permissions to

• view all contacts
• access CiviCRM
• access CiviMail

You can use an existing drupal user and role however we recommend that you use a dedicated user and role (name them something like 'mailsender')

Setting Up the SMTP Configuration

Outbound email setting are configured at: Administer > System Settings > Outbound Email (SMTP/Sendmail). The choices here are:

• mail().  This is the default option and if it works for you, you should use it.
• SMTP.  If you have a dedicated external mail server, specify its details here. Bounce messages generated with SMTP are slightly more complete than the ones from mail(), but there is no practical benefit to using SMTP if you can use mail().
• Sendmail.  This option is kept for compatibility with older CiviCRM versions.
• Disable Outbound Email. Works as expected.

Setting Up the Cron Job

To have your mailing actually send, set up a cron job that will periodically poke CiviMail to send all of the mailings that are past their scheduled date.  See Managing Scheduled Jobs for more details.

There are two methods to run the cron: From a Control Panel or from a command line interface (CLI) which is the preferred way.

Make sure php-cli is installed by running the following command in the shell:

If you see (cli) in the returned result, as in:

This means you have php-cli installed and you should use it instead of a control panel because it offers several advantages:

• You can run a PHP script at a lower priority than your web server, so that even if it takes a lot of CPU, it won't interfere with the regular users of your site.
• You can set different memory limits for the php-cli process and the PHP process used by your web server.
• You avoid the overhead of the web server and the HTTP layer.
• You won't have any timeout problems.

The following is complete cron configuration to handle CiviCRM's mail requirements. Put it into your crontab and adjust as needed. 

The user that run the scripts (www-data in this example) needs to be able to write into the temporary folder. Your configuration might specify a different user.

You don't have to run both scripts at the same frequency. The preceding crontab file verifies every 5 minutes whether mail messages need to be sent, but only every 15 minutes whether bounced email needs to be processed.

PARAMS contains:

1. The site you used, which is -sdefault on Drupal. If you run multiple CiviCRM sites on a single server, you need to specify your site's domain, such as -sexample.org.
2. The user login account (-umailprocess).
3. The password you defined (-pseol-lzprm42amv-psyc).
4. The scheduled job (-a)

Using wget

The script to process CiviMail messages is cron.php in CiviCRM's bin directory. You can run this script using either "GET" or "POST" methods. However, using "POST" with the authentication values stored in a file on your server is generally considered to be better security practice. Learn more ...

You can also trigger CiviMail to send scheduled mailings by navigating to this URL with your browser:

Drupal: http://<site>/index.php?q=civicrm/mailing/queue&reset=1 Joomla: http://<site>/administrator/index.php?option=com_civicrm&task=civicrm/mailing/queue&reset=1

Setting Up the Return Channel

Do You Need the Return Channel?

If you send emails and don't manage the bounce, you will be flagged as a spammer at one point or another. If you don't want that, you do want a return channel.

The return channel is required at least in two cases.

First, the return channel is required to track bounces and have the bouncing emails put on hold, as well as to track replies; if you don't need this functionality (you will still get the replies, you just won't be able to have stats about them), you don't need return channel handling.

Second, the return channel is required if you want to handle SMTP (i.e., email-based) actions such as (un-, re-)subscribes and opt-outs - note that these actions have their HTTP (i.e., link-based) equivalents.

Possible Solutions for the Return Channel

There are four possible solutions for handling of the return channel.

The current supported CiviCRM solution is CiviMail Processor, which polls the email account specified in Administer CiviCRM → Mail Accounts in defined intervals.

If you absolutely need real-time return channel handling, there's our patched AMaViS solution.

If you prefer a CiviMail-Processor-like solution in Perl for polling a given IMAP account, the community-supported imap2soap can handle the return channel for you.

Finally, the easiest and most hands-free (albeit paid) solution is to setup an CiviSMTP account.

There are two important limitations on your ability to track bounces via return channel. First, as gleaned from this forum thread, bounce tracking does not work when using the sendmail delivery method. Second, some SMTP services (notably google) insert their own Return-Path address headers, superseding the headers set by civiMail and effectively disabling bounce tracking. For Google Apps, however, see http://wiki.civicrm.org/confluence/display/CRMDOC40/Step-by-step+Return+Channel+on+Drupal+-+Google+Apps+-+CentOS for directions how to setup the return channel