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. |
| Alternative configuration
Note that the Alternative configuration (imap2Soap) discussed further down replaces the main process for setting up the return channel. The other three steps are still required if you go down this path |
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.
There is also an experimental unsupported php return mail solution for civiCRM 2.1 (requiring hard coding) that replaces AMaViS and could be easier - and would enable a return channel on shared hosts without root access. This will be part of civiCRM 2.2.
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:
/^(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:
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):
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):
: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 are authenticated 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. Starting with versions 2.0.7 and 2.1.2, you will also need to configure a site key to run this script (learn more...).
You can call the script with wget like this:
The user and password values must be the user name and password of a Drupal/Joomla user that has permissions to access CiviCRM and CiviMail.
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=password&key=sitekey'
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. |
 | You can also trigger CiviMail to send scheduled mailings by navigating to this URL with your browser:
Drupal: http:Joomla: http:
|
|
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.
for ubuntu/debian rather than just asserting that a new version of amavisd is necessary, it would be helpful if this documentation explained what exactly was special about the version of amavis that is attached. this would help people on different platforms (say, 64-bit or non-intel architectures) make a choice about what to do - and would also let us know if, say, the amavis package patch has been superseded by amavis 2.5, or if the patched version provides functionality truly specific to Civimail
Hah. One week into my new CivicRM mail installation and I'm finding amavis crashes a lot, say every day or two. (ubuntu amd64, 7.04) And every time it crashes, mail for the ENTIRE SITE (or at least, any parts of the site that don't know about CivicRM's custom SMTP service on port 10025. That means no drupal mail, no local mail, but civimail sending still seems to work..) I'm going to continue to debug the problem here when i have a moment, but i thought i might post this up instantly in case it save enyone else time.
there is another page about this, mysteriously, at http://wiki.civicrm.org/confluence/display/CRM/CiviMail+Configuration
..does anyone else find the organisation of this wiki a bit confusing?
I've deleted the old page. We created a new documentation space (CRMDOC) and hence there are some older versions of documents in the old CRM space.
The wiki is editable by logged in users. So feel free to help clean up and make it a bit less confusing
Hi,
Does CiviMail "play nice" with clamd? I ask because the 40-civimail addition to amavisd.conf turns off av-scanning. Can I just enable it?
Also, when I start the with the amavisd and the debug option it's complaining:
[root@myhost/]# amavisd debug
Config file "Not a directory: --list" does not exist, at /usr/sbin/amavisd line 1264.
I don't know perl I but for what it's worth, line 1264 is here:
1252 # read and evaluate configuration files (one or more) 1253 sub read_config(@) { 1254 my(@config_files) = @_; 1255 for my $config_file (@config_files) { 1256 my($msg); 1257 my($errn) = stat($config_file) ? 0 : 0+$!; 1258 if ($errn == ENOENT) { $msg = "does not exist" } 1259 elsif ($errn) { $msg = "is inaccessible: $!" } 1260 elsif (-d _) { $msg = "is a directory" } 1261 elsif (!-f _) { $msg = "is not a regular file" } 1262 elsif ($> && -o _) { $msg = "is owned by EUID $>, should be owned by root"} 1263 elsif ($> && -w _) { $msg = "is writable by EUID $>, EGID $)" } 1264 if (defined $msg) { die "Config file \"$config_file\" $msg," } 1265 $! = 0; 1266 if (defined(do $config_file)) {} 1267 elsif ($@ ne '') { die "Error in config file \"$config_file\": $@" } 1268 elsif ($! != 0) { die "Error reading config file \"$config_file\": $!" } 1268 }And the only instance of --list I find is here:
2039 # my($old_path) = $ENV{PATH}; 2040 # $ENV{PATH} = "/bin:/usr/bin"; 2041 foreach my $dir (@dirs) { 2042 push(@config_files, `run-parts --list "$dir"`); 2043 }If it makes a difference, my set up is as follows:
CiviCRM 2.0.4 w/Joomla 1.0.15
vps centos-5-x86-eapps
Packages:
postfix 2.3.3-2
amavisd-new 2.5.4-1.el5.rf
dovecot 1.0-1.2.rc15.el5
mysql 5.0.51-1eapps
php 5.2.5-1eapps
perl 5.8.8-10.el5_0.2
perl-SOAP-Lite 0.71-1.el5.rf
Email/Verp version 0.06
./usr/lib/perl5/site_perl/5.8.8/Mail/Verp.pm
spamassassin 3.2.4-1.el5.rf
clamav-db 0.93.1-1.el5.rf
clamd 0.93.1-1.el5.rf
clamav 0.93.1-1.el5.rf
And the many dependencies. . .
test mail account:
Webmail: http://impeachproject.com/webmail/
username: test
password: !test123
smtp server: mail.impeachproject.com
please use the forums for support questions
I suggest we move "Changing the Outgoing SMTP Port" to a point within the Amavis instructions, rather than a separate heading of its own. Currently it seems like it might be one of the "other three steps (which) are still required" mentioned in the note to the introduction.
Would love to have some clarification of the phrase "is not supposed to work as reliably on mass-scale mailings" referring to the alternate configuration - should it read "is not reported to work as reliably"? I read "supposed" as "intended" in this context, but that seems wrong
We took the alternate configuration route because we had an existing mail setup (with Exim), our experience has been that the alternate configuration is very effective (mailouts up to around 20K people on our largest installation).