This configuration is a community contribution. It is also community supported. The core team does not have any experience or detailed knowledge of this configuration
The method described on this page may be useful for you if you are trying to install CiviMail and any of the following hold true:
Note that this is an addendum to the setup instructions for CiviMail. You still need to follow everything in those instructions that does not relate to Amavis/Postfix. This includes Domain setup, SMTP configuration, and setting up the cron job. Keep in mind that CiviMail requires PHP 5 compiled with the SOAP and DOM extensions; it won't work with PHP 4. If you have a SOAP-less PHP 5, there is a section below on installing SOAP::Lite that you can follow.
Imap2soap.pl is currently being maintained by Fen Labalme; you can find the most recent version at https://svn.civicactions.net/repos/civicrm/scripts/ (the versions attached to this page are older and out-of-date).
This method uses the imap2soap Perl script which is attached to this page. To set this up you need to follow these five steps:
imap2soap.plsomewhere you store executables, like
~/bin/and ensure it's executable (e.g.,
chmod 755 imap2soap.pl. Note the Perl modules required in the script and make sure they are installed on the computer you will be running the script on.*
imap2soap.confsomeplace easy to edit from the user that will be calling it, say
~/civicrm/imap2soap.confand for security purposes, protect it from being world readable (e.g.,
chmod 600 imap2soap.conf). Note that if you invoke
imap2soap.plwithout including the
imap2soap.pllooks for the configuration file in the current directory.
imap2soap.confand enter the usernames, passwords and servers from steps 1. and 2. There is a clearly marked section in the file where you need to insert your own settings for SOAP server and email server.
Set up a Cron job to run the script:
23,53 * * * * /usr/local/bin/imap2soap.pl -q -w 1 -l 4 -L 1 /PATH/TO/imap2soap.conf
When the script runs, it will:
* connect to your mail server using IMAP (or IMAPS),
* create imap folders to store processed messages if necessary,
* send any bounce/unsubscribe/etc. messages to CiviCRM via SOAP, and
* file processed messages in IMAP folders.
You can log into this mail account using
imap2soap.pl -i /PATH/TO/imap2soap.conf (or with a normal imap email client) to see the progress of the operation and perhaps to trim (remove old messages from) the Junk folder. A future version or imap2soap.pl will allow moving messages between folders, say from the Failed folder to the Inbox to try processing failed messages again. (If you want to do that now, you'll have to use an external IMAP mail client such as Mozilla Thunderbird.) If you run a lot of large mailings, you might want periodically to clear out these folders, using your email client, and save any emails locally that you want to archive.
List of hosts known to support the required modules for this installation (please add / edit!)
Hosting service designed specifically to support CiviMail. A working CiviCRM / CiviMail is pre-installed for you to customize. (N.B. In the interests of full disclosure, this section and script is contributed by Open Social Sites!).
If setting up CiviMail is all too much for you, CSOD could be for you. This is a CiviCRM 'ASP' that gives an 'instant', managed CiviCRM installation.
You may need to request that the following PERL modules be installed on your server:
You can use CPAN to install modules SOAP::Lite, Mail::IMAPClient, Mail::Verp, HTTP::Cookies, MIME::Entity, and dependencies into local directories (on model of SOAP::Lite below) and tell the .pl script to look for them there.
The "return path" is the method by which CiviMail receives and processes messages via email: bounces from unsuccessful email deliveries, replies and requests for subscriptions to or from mailing lists. Without it, CiviMail will not know about bad email addresses in your mailing database, nor will it be able to process requests to unsubscribe, or forward replies to the appropriate address. At best you will not be able to use many of CiviMail's features. At worst, you will quickly find yourself (and probably your hosting / server provider) on a spam blacklist. These concepts are covered elsewhere in the wiki, but for convenience a summary of the return path system is provided here:
Your incoming mail server must be set up to accept all emails with a valid CiviMail VERP format. Note this does not correspond to an actual valid mailbox on the mail server, hence the need to either set up a virtual-regexp or equivalent filter to specifically forward emails with a valid CiviMail VERP format to a valid e-mail address on the receiving server that is used to receive and process incoming messages for CiviMail, or use a "catch-all" to forward all incoming emails for which there is no valid recipient email address to an email account your use for CiviMail inbound processing.
The imap2soap script (like Amavis in the standard CiviMail configuration) intercepts these VERP encoded email addresses, extract the data encoded into them, and use the "SOAP interface" to CiviCRM to transfer this data to your server, where CiviCRM act on them accordingly eg adding or removing a user from a mailing group, forwarding a reply, etc.
The imap2soap script has a few significant improvements over new-mail2soap:
Using IMAP connections may be slower than the method below which manipulates the Maildir files directly. However you may find in any case that the limiting factor is the rate at which your web server can handle connections (i.e. thousands of near-sumultaneous SOAP calls to handle bounces could drag your web server down, so the less aggressive rate of message handling through IMAP could be a benefit for some set-ups).
The earlier new-mail2soap script acts on email files directly where they are stored. It is therefore potentially fast, but requires read and write access to your Maildir folders. To use ne-mail2soap:
The new_mail2soap.pl script looks in the new emails folder of your email account, loads any email files it finds there and processes them through the soap interface. This is a first-attempt version and could use some refinement! In particular, the message archiving should probably be moved into the process loop so only successfully processed messages are archived and others stay in the New folder until the next attempt (or forever!). Also, a sanity check on VERP headers to make sure they are legitimate messages might be useful. It does, however, avoid one potential problem of mail2soap.pl, as it only needs to be compiled once per cron run, which could help with large loads. Note in most imap daemons eg Courier, if you access this email account with a mail client (or webmail) your checked mail may be moved from the New to the Cur folder.
N.B. The VERP string in the email to line changed somewhere between early 1.4 and 1.5, with an extra field (domain_id) being added. To account for this, if the $verpinfo matching function in mail2soap-new.pl needs to be updated to
($verpInfo =~ m/(\w+).(\d+).(\d+).(\d+).(0-9A-F+)/i);
This is included in the 1.5 version of new-mail2soap_1.5.pl attached to this page
The following text was excerpted from: http://cookbook.soaplite.com
You want to install SOAP::Lite, but don't have root/administrator privileges.
Install SOAP::Lite into a custom directory using CPAN module:
# perl -MCPAN -e shell > o conf make_arg -I~/lib > o conf make_install_arg -I~/lib > o conf makepl_arg LIB=~/lib PREFIX=~ INSTALLMAN1DIR=~/man/man1 INSTALLMAN3DIR=~/man/man3 > install SOAP::Lite
Setup PERL5LIB environment variable. Depending on your shell it may look like: PERL5LIB=/you/home/directory/lib; export PERL5LIB
lib here is the name of directory where all libraries will be installed under your home directory.
Run CPAN module with perl -MCPAN -e shell
and run three commands from CPAN shell
> o conf make_arg -I~/lib > o conf make_install_arg -I~/lib > o conf makepl_arg LIB=~/lib PREFIX=~ INSTALLMAN1DIR=~/man/man1 INSTALLMAN3DIR=~/man/man3
LIB will specify directory where all libraries will reside.
PREFIX will specify prefix for all directories (like lib, bin, man, though it doesn't work in all cases for some reason).
INSTALLMAN1DIR and INSTALLMAN3DIR specify directories for manuals (if you don't specify them, install will fail because it'll try to setup it in default directory and you don't have permissions for that).
Then run: > install SOAP::Lite
Now in your scripts you need to specify: use lib '/your/home/directory/lib';
somewhere before 'use SOAP::Lite;'