Campaign Setup Guide
This tutorial will walk you through the setup of a spamzilla campaign.
Setting up spamzilla
First, you must configure the controller, if you already have a controller installed, you can skip this step.
Install perl 5.8.0 or newer on your controller machine, and postgresql. You will also need the following list of Perl Modules available from CPAN:
POE POE::Component::Server::SimpleHTTP POE::Component::Server::SimpleContent POE::Component::Server::SOAP POE::Component::LaDBI POE::Component::Client::HTTP POE::Component::Client::DNS DBI DBD::Pg LWP Net::DNS XML::LibXML XML::LibXSLT Regex::Common MIME::Lite MIME::Types Error
A custom version of POE::Component::Client::SMTP is included in the distribution.
Once this is done you must configure spamzilla. I will not go over the configuration details here, they are quite simple, and documented in the configuration reference. An example configuration file is attached.
See also SpamZilla/Configuration
Starting the controller
If the controller is already running (you can reach the mozilla web interface) then you can skip this step.
The controller has several command line options
| Short Option | Long Option | Description |
| c | configfile | This option takes an argument of the path to the configuration file, and is required |
| d | daemonize | This overrides the "daemonize" configuration option |
| v | verbose | This option specifies verbose mode. Unfortunately, this is mostly deprecated |
| l | logfile | This option accepts an argument of a logfile path |
To start spamzilla, start up perl with the path to spamzilla.pl, and atleast the -c option, and a path to the spamzilla configuration file. Because spamzilla binds port 80, you must be suid 0 (or "root") to start this application, unless spamzilla is configured to use user port space.
root@12# cd spamzilla root@12# perl spamzilla.pl -c controller.xml
The controller should now be running!
Installing JavaMail
If the mailer is already installed on all systems you wish to use, you can skip this step. The Spamzilla Java Mail component requires the following libraries, they should be included, but if any of them seem to be missing:
Tidy.jar libreadline-java.jar activation.jar log4j-1.2.8.jar axis-schema.jar mail.jar axis.jar mailapi.jar bsf-2.3.0.jar pop3.jar bsf.jar postgresql-8.0-314.jdbc3.jar commons-discovery-0.2.jar resolver.jar commons-logging-1.0.4.jar saaj.jar dom.jar serializer.jar dom1.jar servlet-2.3.jar imap.jar servlet.jar javax-crypto.jar smtp.jar javax-security.jar wsdl4j-1.5.1.jar jaxp-1.2.jar xalan.jar jaxrpc.jar xalan2.jar js-1.6.jar xercesImpl.jar jsch-0.1.19.jar xercesSamples.jar jsch.jar xml-apis.jar jsse.jar xmlParserAPIs.jar libreadline-java-0.8.0.jar xt.jar
Most of these are associated with either javamail 1.3.3, Axis 1.3, or Rhino 1.6 which are the core dependencies of the java mailing node. JavaMail also depends on Sun Microsystem's Java 1.5.
Once you have these, put them in a directory easily accessable (preferrably a directory called "lib" in the directory you wish to run JavaMail from), and set them to your classpath.
tcsh> setenv CLASSPATH .:`echo lib/*.jar | sed 's/ /:/g'`:spamzilla.jar bash$ export CLASSPATH=.:`echo lib/*.jar | sed 's/ /:/g'`:spamzilla.jar
Then, set your JAVA_HOME to the directory where you installed your Java 1.5 distribution.
tcsh> setenv JAVA_HOME /opt/jdk1.5 bash$ export JAVA_HOME=/opt/jdk1.5
Once you have done this, you may now start configuring JavaMail. You must atleast set Local Resource Options and Subscription Options. Use the JavaMail/Properties reference to guide you through tweaking the configuration values. It is suggested you store these in a file called properties.xml.
An example properties.xml is attached to this page.
Once you have done this, you can start axis, effectively loading up JavaMail. Before starting axis, make 100% sure you have the server-config.wsdd file in your local directory. There is also one of these attached.
Starting Java Mail
Unfortunately, starting a JavaMail node is a process of several steps. Once you have your subscription options set up in your local configuration file, and you have a controller started. (You must also be subscribing to the controller, that is running.)
java -Dspamzilla.properties=properties.xml subscribe
This will subscribe the local mailing node, even though the mailer is not running. Keep in mind that the controller only keeps subscribers in memory, for the time being, so at the time of writing if the controller goes offline for some reason you will need to re-subscribe all of your nodes (However, you do not need to restart the mailer if it is already running, you can simply run the subscription tool).
Now, you're ready to start the actual mailer. In this example, we will just use the simple axis server, but you could package spamzilla into a war file and deploy it into any servlet container, or whatever else you would like to do. For simplicities sake, and because we don't use much other than just SOAP for access currently, this is the lightest, fastest, and easiest way.
java -Dspamzilla.properties=properties.xml org.apache.axis.transport.http.SimpleAxisServer
The JavaMail node should now be running. Now you can build and send a campaigns.
Building a Campaign
- Go to the SpamZilla? Controller Interface.
- First, import your list.
- Click "Import" in the top menu, and then "Target List".
- Now select your list
- Press Ok.
Wait patiently for the import to complete. You should get a popup notification giving you statistics of the import. The larger the list is, the longer it takes to import. The import process is rather complicated, the server will open a port for the client to connect to and dump the file you selected, once that is done, the server will parse the header of the CSV file, then load the list into the database. once this is done, the server will proceed to resolve the MX records, and MX domains, of each email domain in the list.
Example CSV
"Email","Firstname","Lastname" "tag@cpan.org","Scott","McCoy" "tag@blisted.org","Scott","McCoy"
Once you have finished that you may import a template. The template import expects a zip file, filled with atleast 1 html template and possibly one or more text templates of other types. All text templates will be parsed at the time of send, and all non-text files will be attached, MIME Encoded as is. If you wish to link to the attached files from the HTML template, you may refer to the files as cid:<name of file in archive, including possible path>.
You may use the following style of template tokens {{{Token}}}, with the corresponding name of the database field or one or more special fields, such as Key, TargetID, CampaignID. Key's are case insensitive.
If you're planning on logging clicks or opens you will want to use the {{{Key}}} token as the first directory of your link.
Setting up a tracking server
At this point you may want to set up a tracking server. To set up a tracking server, follow the instruction for setting up a controller. But you will likely want to configure the controller to be only a webserver.
Figure: Example webserver-only controller configuration
<spamzilla xmlns="http://www.blisted.org/spamzilla/config">
<daemon type="perl"
daemonize="true"
user="www-data
group="www-data"
pid="/tmp/spamzilla.pid" />
<database type="DBI"
dsn="DBI:Pg:dbname=spamzilla;host=204.15.164.12"
username="root"/>
<webserver type="POE"
address="<IP HOSTING DOMAIN>"
port="80"
authenticate="false"
track="true"
indexfile="spamzilla.xul"
docroot="/path/to/document/root">
<servlet uri="/optout.html" type="POE" name="Optout">
</webserver>
</spamzilla>
Then, place any images or links you wish to use for tracking in the document root of the web service. To track email opens, you will need to place the tracking image in the subdirectory "open". You may link to it as http://yourdomain.com/!{{{Key}}}/open/pixel.png, for example. Placing this in an img tag in your template will create a tracking secenario.
Any redirections you wish to do will need to be manually set up. You can use a meta-redirect or a frame forward, whichever is your preference. Stick a redirection page for your sponsor in the document root of your webserver.
Figure: refresh.html, Example Redirect Page
<html>
<head>
<meta http-equiv="refresh" content="1;http://your/sponsor/url"/>
</head>
<body>
</body>
</html>
Link to the page using the a url signature such as http://yourdomain.com/!{{{Key}}}/refresh.html. This will track users as they open and click on your emails links.
Building a campaign
To build a campaign, go back to the controllers web interface. Click on New > Campaign. The campaign wizard will start up. Follow the steps of the campaign wizard, they are relatively simple. First select a list, then targets to email from. I suggest that you set up your mailing servers IPs as MX handlers for the domains you are sending email as, for SPF compliance. Then insert your subjects, select your templates, and select a time to schedule the campaign for sending.
If all is well, your mail will start sending on time, your message views and clicks will get tracked.
