Introduction

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

PHP 5 Requirement

Keep in mind that CiviMail requires PHP 5 compiled with the SOAP and DOM extensions; it won't work with PHP 4.

Enabling the CiviMail Component and Assign Mailing List Groups

Go to Administer CiviCRM → Global Settings → Components and add the CiviMail component to the enabled components.

Go to Administer CiviCRM → Edit Domain Information and edit the values to your liking.

Go to CiviCRM → 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.

Setting Up the SMTP Configuration

Go to Administer CiviCRM → Global Settings → SMTP Server and provide proper values. For the default setup, insert localhost as the SMTP server and 25 as the SMTP Port. If your SMTP server requires authorisation, provide it there.

Setting Up the Return Channel

This is the tricky part. CiviMail requires the return email channel to work, so that the mailing recipients can unsubscribe or opt-out if they want to; the return channel is also required for bounce tracking.

AMaViS

Installation: Debian/Ubuntu Systems

- Debian 3.1 (sarge) / Ubuntu 6.06 (Dapper) : Make sure you have the following packages installed: debconf | debconf-2.0, adduser (>= 3.34), file, libmime-perl (>= 5.417), libmime-perl (<< 5.419) | libmime-perl (>= 5.420), libconvert-tnef-perl (>= 0.06), libconvert-uulib-perl (>= 1.0.5), libcompress-zlib-perl (>= 1.35), libarchive-tar-perl, libarchive-zip-perl (>= 1.14), libmailtools-perl (>= 1.58), libunix-syslog-perl, libnet-perl (>= 1:1.16) | perl-modules (>= 5.8.1), libnet-server-perl, libtime-hires-perl, libdigest-md5-perl, libmime-base64-perl, libio-stringy-perl, libberkeleydb-perl, postfix, perl (>= 5.6.0-16), libsoap-lite-perl, libmail-verp-perl, procmail.
  - For Debian 3.1 (sarge) you might need to get yourself a newer libcompress-zlib-perl, as sarge ships 1.34-1.
  - For Ubuntu 6.06 (Dapper) you might need to either downgrade or upgrade libmime-perl, as Dapper ships the broken 5.419-1 version.
- for ubuntu 7.04 (Feisty) the package installation list is more likely to be something like sudo apt-get install libmailtools-perl libunix-syslog-perl libberkeleydb-perl libsoap-lite-perl libmail-verp-perl libio-stringy-perl libarchive-zip-perl libnet-server-perl libarchive-tar-perl libconvert-uulib-perl libconvert-tnef-perl libio-multiplex-perl libnet-cidr-perl libio-zlib-perl postfix procmail.
- for all debian/ubuntu-like distributions, you will probably be best served by doing an install of the packages that your OS thinks are best likely to meet the dependencies of the inscrutable amavsid .deb file. the command for this is apt-get -f install, which will helpfully install all the dependencies of any package you try to install. A lot easier, and a lot less error-prone.
Download our pre-built amavisd-new_2.4.2-6.1civimail2_all.deb and install it with `dpkg -i amavisd-new_2.4.2-6.1civimail2_all.deb`.

Installation: Non-Debian/Ubuntu Systems

Install AMaViS 2.4.2 as per your distribution.
Replace the amavisd-new or amavisd file (found in /usr/sbin or /usr/local/sbin) with our modified copy. Make sure the file is executable.
Install the Perl modules SOAP::Lite and Mail::Verp, either from your system repositories or CPAN.

Configuration: Debian/Ubuntu Systems

Copy /etc/amavis/conf.d/40-civimail to /etc/amavis/conf.d/41-civimail and edit to your liking. (The values in the file prefiex with "41" will override the ones in the files prefixed "40".) The login and password for the SOAP interface must be your Drupal/Joomla login for a user with CiviMail access privileges. Also, make sure you point $civicrm_soap_proxy to the proper CiviCRM instance.

Configuration: Non-Debian/Ubuntu Systems

If your copy of AMaViS installed with the conf.d directory (under /etc/amavis or /usr/local/etc/amavis), copy the 40-civimail file there and edit to your liking. The login and password for the SOAP interface must be your Drupal/Joomla login for a user with CiviMail access privileges. Also, make sure you point $civicrm_soap_proxy to the proper CiviCRM instance.

If your copy of AMaViS did not install with the conf.d directory (under /etc/amavis or /usr/local/etc/amavis), append the contents of the 40-civimail file to your amavisd.conf file and adjust to your liking. The login and password for the SOAP interface must be your Drupal/Joomla login for a user with CiviMail access privileges. Also, make sure you point $civicrm_soap_proxy to the proper CiviCRM instance.

Multi-site CiviMail Installs

Multi-site CiviMail Installs

The current AMaViS does not support multi-site CiviMail installs. If you need this functionality, you have to use the previous version, from CiviCRM 1.5.

Postfix

Install Postfix as per your distribution (Debian/Ubuntu: install the postfix package).

Create a user in your system (for example, civimail).

Configuration Paths

In the below examples, adjust the configuation path to your system's specifics (for example, /usr/local/etc/postfix instead of /etc/postfix).

`virtual`

Create an /etc/postfix/virtual file that will forward the CiviMail-targeted email to the civimail account:

/etc/postfix/virtual

/^(bounce|confirm|optOut|reply|subscribe|unsubscribe|resubscribe)\..*@example\.com$/ civimail@example.com

Compile the file with the `postmap virtual` command.

`main.cf`

Append the following to the main.cf file to make Postfix use the virtual aliases and pass emails through AMaViS listening on port 10024:

/etc/postfix/main.cf

virtual_alias_maps = regexp:/etc/postfix/virtual
content_filter = smtp:127.0.0.1:10024
receive_override_options = no_address_mappings

`master.cf`

Append the following to the master.cf file to make Postfix listen on port 10025 and not pass the mails received there to AMaViS (for outbound mail):

/etc/postfix/master.cf

localhost:10025 inet n - - - - smtpd
 -o content_filter=
 -o receive_override_options=

Fall-back Bounce Handling

For certain types of bounces (particularly after repeated failed delivery attempts), Postfix will generate error messages internally and bypass the content filter. To catch these messages, a Perl script is provided that will forward the bounce message back to the content filter. This script is located at tools/procmail/original-to.pl in our repository. Copy it to your server (for example, to /home/your-username), adjusting 'smtpsend' inside the script if the script is not on the same server as SMTP. The following procmail recipe (adjusting /home/your-username to where you put the script) needs to be placed in the directory of the user created in the first Postfix step and set in virtual to receive bounce (and other) notifications for CiviMail (civimail and civimail@example.com in that example, so .procmailrc would be put in /home/civimail):

.procmailrc

:0:
* ^X-Original-To: bounce\..*$
| /home/your-username/original-to.pl

Restart Postfix and AMaViS

Debian/Ubuntu Systems

Restart Postfix and AMaViS with the `/etc/init.d/postfix restart` and `/etc/init.d/amavis restart` commands.

Non-Debian/Ubuntu Systems

Restart Postfix and AMaViS according to their scripts in your system (for example, use `/usr/local/etc/rc.d/postfix.sh restart` and `/etc/rc.d/amavisd restart`).

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. An example cron job can be found in our repository. This file should also be in your civicrm distro: look for bin/civimail.cronjob.php.

Since CiviCRM 1.8 the scripts in the bin/ directory have a line added to authenticate against a valid CMS user account before running the script. If your preference is to run the scripts from the command line, you'll need to pass or hard code a username and password. Alternatively, you can simply call the script with wget like

wget 'http://your-domain.org/path/to/civicrm/bin/civimail.cronjob.php?name=civimailuser&pass=civimailuserpassword'

The civimailuser and civimailuserpassword is the user name and password of a Drupal/Joomla user that has permissions to access CiviCRM and CiviMail.

I just got my mail to fire in 2.0 Beta1 by running the URL below in my browser. I used the CMS (Drupal) admin userid and password.

Note, if you are using Joomla, the com_civicrm that you might have created in your webroot while uploading and/or installing the component IS NOT the path\to\civicrm, which should look something like:

wget 'http://blah/site/administrator/components/com_civicrm/civicrm/bin/civimail.cronjob.php?name=user&pass=thepassword'

For testing, you should be able to get this URL to fire off any pending jobs by running it in your browser. If that works, the easiest way to get Cron firing is to just put the wget in front and add the quotes around the URL.

If you use cPanel, this is really easy. Click Cron jobs on the cPanel home page, and put the wget string, just like above, but with your user and pass, and path, into the Command to run: field, and set the time preferences below for how often you want the cron to run.

A bug in CiviCRM v1.9 makes the cronjob process only one mailing a a time. This has been fixed for v2.0

Changing the Outgoing SMTP Port

If you don't want your outgoing mail to go through AMaViS (which is undesirable), you may now change the outgoing SMTP port. Go to Administer CiviCRM → Global Settings → SMTP Server and insert 10025 as the SMTP Port value.

Alternative Configuration

There's an alternative configuration, which is easier to set up and doesn't require AMaViS, but hasn't been tested by us and is not supposed to work as reliably on mass-scale mailings as the above Postfix+AMaViS configuration at the moment. Your mileage might vary; for at least one user on a fairly low-powered server, this amavis configuration was very unstable and crashed with large mailouts, whereas the the alternative configuration, which adapts to server load, has been a lot more reliable on mass-scale mailing.