NAME

Apache::Mailtrack - keep track of views of HTML newsletters

SYNOPSIS

In your local httpd.conf:

RewriteEngine On
RewriteRule /Mailtrack/([^/]*)/(.*) /Mailtrack/?userdata=$1&target=$2 [P]

<Location "/Mailtrack">
  PerlSetVar db_dsn      dbi:Pg:dbname=mydatabase
  PerlSetVar db_user     myuser
  PerlSetVar db_pass     mypass
  PerlSetVar db_table    mytable
  PerlSetVar db_target   mytarget

  PerlSetVar serializer  YAML
  PerlSetVar secret      "A top secret secret that is."

  PerlSetVar path        /images
  PerlSetVar defaultfile mod_newsletter_default.jpg

  SetHandler perl-script
  PerlHandler Apache::Mailtrack
</Location>

In the body of the HTML newsletter:

<img src="http://www.site.at/Mailtrack/[% userdata %]/some.gif">
<a href="http://www.site.at/Mailtrack/[% userdata %]/url|use.perl.org">X</a>

DESCRIPTION

Apache::Mailtrack assists you in keeping track of the response generated by an HTML newsletter (supposedly - or shall I say, hopefully - NOT SPAM), by logging all views of the newsletter (via an embedded image, which is served by this module) and logging all clicks on an URL (which gets also "served" by this module via redirect) into a database capable of SQL (PostgreSQL, MySQL, Oracle, and such).

The data to be logged must be provided in a serialized string, generated by Data::Serializer, representing a hashref. Every entry of this hash is written into the database, using the key as fieldname and writing the value into that field.

The implementation of a script to generate such userdata and embed it into an HTML mail is left as exercise to the reader.

The handler can be triggered either using an images embedded in the newsletter, or by recipients clicking on a link that points to a location handled by Apache::Mailtrack.

Using the file approach, you should get a log entry every time a recipient views the mail in an HTML capable mail client. Example:

<img src="http://www.site.at/Mailtrack/[% userdata %]/some.gif">

Using the link approach, you should get a log entry every time a recipient clicks on a link pointing to an URL handled by Apache::Mailtrack. Example:

<a href="http://www.site.at/Mailtrack/[% userdata %]/url|use.perl.org">X</a>

NOTE: the URL must not contain the protocol (http://). In this release it is only possible to link to HTTP resources.

INSTALLATION

Follow these steps to set up Apache::Mailtrack:

• Install Apache::Mailtrack and all needed modules.

• Create the a table in the database you want to use for logging which fits your needs.

  For example:

  CREATE TABLE log
    (
    subscriberid       INTEGER        NOT NULL,
    newsletterid       INTEGER        NOT NULL,
    target             TEXT,
    view               TIMESTAMP      NOT NULL DEFAULT NOW()
    );

• Set up a location in your Apache config as shown in SYNOPSIS.

• Set up a rewrite rule to catch the request which should be handled by Apache::Mailtrack.

  For example:

  RewriteEngine On
  RewriteRule /Mailtrack/(.*)/(.*) /Mailtrack/?userdata=$1&target=$2 [P]

  Replace Mailtrack with the location you use.

• Restart Apache.

CONFIGURATION

You have to set up at least the following variables in your httpd.conf in the location you want to use Apache::Mailtrack using PerlSetVar:

db_dsn

complete DBI connect string

db_user

database user

db_pass

password to be used

db_table

name of table we should log to

Additionally you can define the following options:

db_target

name of the field in the defined table (see db_table) we should write the redirection target to [default: undef]

serializer

name of the serializer Data::Serializer should use [default: Storable]

secret

specify secret for use with encryption [default: undef]

path

default path to the served file [default: /images]

defaultfile

file we should serve in case of emergency [default: mailtrack_default.jpg]

AUTHOR

Florian Helmberger <fh@laudatio.com>

SEE ALSO

mod_perl, Apache::Request, Apache::Constants, Data::Serializer, YAML, DBI