Logging Email Opens and Clicks

Most emailing services provide open and click statistics for their customers.

If you run your own emailing software on your own server, that information might not have been available for you. Until now.

The statistics do not depend on the emailing software you use, so long as you can insert an img tag (to count email opens) and link URLs (to count clicks) into the outgoing email.

Logging the statistics requires the Mail Opens & Clicks script, which comes with today's article. Mail Opens & Clicks is not emailing software and is separate from whatever emailing software you are using. In other words, Mail Opens & Clicks is independent.

Mail Opens & Clicks can log when the email is opened or a link is clicked. Or both actions can be logged.

• To log email opens, HTML email needs to be used. That's so an image tag can be put into the email — an image that loads when the email is opened.

  When the email is opened, the image loads via Mail Opens & Clicks — which logs the image load and then sends the image to the email reading software.

• Logging link clicks can be done with either HTML or plain text emails.

  When a link is clicked, the click goes to Mail Opens & Clicks — which logs the click and then redirects the browser to its destination.

The log includes a time stamp, the reader's IP address, an ID (probably the reader's email address), and the reader's browser identification.

When logging a link click, the destination URL is also recorded in the log.

The Log File

Before the source code for the Mail Opens & Clicks script, let me show you what the log file looks like.

You'll see one "load" entry (meaning the image was loaded because the email was opened) and one "click" entry (meaning a link was clicked). The "click" entry includes the destination URL.

"Mon, 07 Sep 2020 14:54:03 +0000","24.12.57.168","load","name@domain.com","","Mozilla/5.0 (Macintosh; Intel Mac OS X 10.13; rv:68.0) Gecko/20100101 Thunderbird/68.12.0 Lightning/68.12.0"
"Mon, 07 Sep 2020 14:54:08 +0000","24.12.57.168","click","name@domain.com","https://lightfocus.com","Mozilla/5.0 (Macintosh; Intel Mac OS X 10_13_6) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/84.0.4147.135 Safari/537.36"

The time zone for the time stamp depends on how your PHP is configured. The time stamp format used in this statistics CSV file looks like this.

Mon, 07 Sep 2020 14:54:03 +0000

The "+" or "-" followed by digts, at the end of the stamp, is a time zone indication (the number of minutes plus or minus UT). "+0000" means UT (same as GMT).

The Source Code for the Mail Opens & Clicks PHP Script

Here is the entire source code for the Mail Opens & Clicks PHP script. Customization notes follow the source code.

<?php
/* 
Mail Opens & Clicks
Version 1.0
September 7, 2020
Will Bontrager Software LLC
https://www.willmaster.com/
*/

/* Customizations */
// 3 places to customize.

// Place 1:
// Specify log file location (contents are formatted CSV). Default is logfile.csv.

$LogFile = 'logfile.csv';

// Place 2:
// Specify the redirect code (301, 302, or blank). Default is 301.
// - 301 logs only first click to unique destination (browser remembers click URL).
// - 302 logs every click (browser doesn't remember click URL).

$RedirectCode = 302;

// Place 3:
// Specify default image location (server location or URL). Default is a 1-pixel transparent GIF image.

$DefaultImage = 'https://www.willmaster.com/images/wmlogo_icon.gif';

/* End of customization section */

if( empty($LogFile) ) { $LogFile = 'logfile.csv'; }
if( strpos($LogFile,'/')===0 ) { $LogFile = "{$_SERVER['DOCUMENT_ROOT']}$LogFile"; }
if( empty($RedirectCode) ) { $RedirectCode = 301; }
if( empty($DefaultImage) ) { $DefaultImage = 'data:image/gif;base64,R0lGODlhAQABAJH/AP///wAAAMDAwAAAACH5BAEAAAIALAAAAAABAAEAAAICVAEAOw=='; }
$RedirectCode = strval($RedirectCode);
if( empty($_GET['act']) and isset($_GET['action']) ) { $_GET['act'] = $_GET['action']; }
foreach( array( 'src', 'code', 'dest' ) as $key )
{
   if( empty($_GET[$key]) ) { $_GET[$key] = false; }
}
if( empty($_GET['id']) ) { $_GET['id'] = 'NoID'; }
if( $_GET['act'] == 'load' )
{
   if( empty($_GET['src']) ) { $_GET['src'] = $DefaultImage; }
   $type = 'gif';
   if( strpos($_GET['src'],'data:image')===false )
   {
      $s = strpos($_GET['src'],'?')!==false ? preg_replace('/\??*$/','',$_GET['src']) : $_GET['src'];
      $ta = explode('.',$s);
      $type = array_pop($ta);
      if( $type = 'jpg' ) { $type = 'jpeg'; }
   }
   UpdateCSVfile();
   header("Content-type: image:$type");
   echo file_get_contents($_GET['src']);
   exit;
}
if( $_GET['act'] == 'click' )
{
   if( empty($_GET['code']) ) { $_GET['code'] = $RedirectCode; }
   if( empty($_GET['dest']) ) { $_GET['dest'] = '/'; }
   UpdateCSVfile();
   header("Location: {$_GET['dest']}", true, $_GET['code']);
   exit;
}
function UpdateCSVfile()
{
   global $LogFile;
   $loglines = array();
   $loglines[] = date('r');
   $loglines[] = $_SERVER['REMOTE_ADDR'];
   $loglines[] = str_replace('"',"\\"."'",$_GET['act']);
   $loglines[] = str_replace('"',"\\"."'",$_GET['id']);
   $loglines[] = str_replace('"',"\\"."'",$_GET['dest']);
   $loglines[] = str_replace('"',"\\"."'",$_SERVER['HTTP_USER_AGENT']);
   file_put_contents($LogFile,'"'.implode('","',$loglines)."\"\r\n",FILE_APPEND);
}
echo 'Inappropriate access.';
?>

Customizations —

There are three places to customize Mail Opens & Clicks. (There are defaults for any values left blank.)

1. The first customization is to specify the log file. Replace logfile.csv with your preferred log file location.

   $LogFile = 'logfile.csv';
   

   If the log file location begins with a "/" character, it is assumed to be relative to document root. Otherwise, it is assumed to be relative to the directory where Mail Opens & Clicks is installed.

   If no file name is specified, logfile.csv will be used.

2. The next customization is to specify a redirect code. Either replace 302 with 301 or leave it as it is.

   $RedirectCode = 302;
   

   When a link in an email is clicked, the click goes to the reader's browser.

   • If the redirect code is 301, the browser remembers the link URL of the click.

     The first time a particular link URL goes to the browser, the browser goes through Mail Opens & Clicks, which logs the click and redirects the browser. For subsequent clicks of that link URL, the browser bypasses Mail Opens & Clicks and goes directly to the destination.

     Thus, with 301, only the first click is logged.

   • If the code is 302, the browser does not remember the click URL.

     Thus, with 302, every click is logged.

   If no redirect code is specified, 301 will be used.

3. The last customization is to specify a default image to use when no image src URL is specified in the image tag that uses Mail Opens & Clicks.

   $DefaultImage = 'https://www.willmaster.com/images/wmlogo_icon.gif';
   

   Replace the URL to the image in the source code. If the $DefaultImage value is blank, a 1-pixel transparent GIF image will be assumed.

Installing Mail Opens & Clicks

When the customizations are complete, save the Mail Opens & Clicks file as oc.php or other *.php that you may prefer.

Upload oc.php to your server and make a note of its URL. (URL https://example.com/oc.php is assumed for instructions in this article.)

Using Mail Opens & Clicks

This has two sections, one for loading an image to be used for counting opens and the other for counting clicks.

Something that both sections have in common is to specify an ID. The ID value is so you know who opened the email and clicked on the link.

For many installations of this system, the ID value is likely to be the person's email address — the person who received the email. For others, a unique id might be utilized that can indicate which email address the open or click relates to.

These instructions assume the email address of the email recipient is name@example.com.

Counting Email Opens —

To count email opens, an HTML email is required.

One image in the email has a special src attribute URL for an img tag. Other images in the email can be regular images.

Here is the template for the special img tag URL:

https://example.com/oc.php?act=load&id=[ID]&src=[ImageURL]

There are three things to customize.

1. Replace https://example.com/oc.php with the URL to your installation of the Mail Opens & Clicks script.

2. Replace [ID] with the recipient's email address — or other id that tells you what their address is.

   Most list mailers — email sending software that sends email to a list of addresses — have a way to insert custom content into the outgoing email. Follow your list mailing software's procedure for inserting the recipient's email address into the spot where [ID] is at.

3. &src=[ImageURL] is optional. If included, replace [ImageURL] with the URL of the image to publish. If not included, the default image will be published.

Publish the above src attribute URL with an img tag.

This examples does not contain &src=https://example.com/image.jpg — which means the default image will be published.

<img src="https://example.com/oc.php?act=load&id=name@example.com">

This examples contains &src=https://example.com/image.jpg — to specify a particular image to publish.

<img src="https://example.com/oc.php?act=load&id=name@example.com&src=https://example.com/image.jpg">

The optional &src=[ImageURL] lets you specify a particular image, if you wish, or let the default image kick in.

Counting Clicks —

Both plain text and HTML emails can count clicks.

Here is the template for constructing the link URL:

https://example.com/oc.php?act=click&id=[ID]&dest=[DestinationURL]

There are three things to customize.

1. Replace https://example.com/oc.php with the URL to your installation of the Mail Opens & Clicks script.

2. Replace [ID] with the recipient's email address — or other id that tells you what their address is.

   As indicated in the previous section, most list mailers have a way to insert custom content into the outgoing email. Follow the list mailing software's procedure for inserting the recipient's email address into the spot where [ID] is at.

3. Replace [DestinationURL] with the URL that is the browser's final destination — the URL that Mail Opens & Clicks shall redirect the browser to.

Here is an example of what the link URL might look like:

https://example.com/oc.php?act=click&id=name@example.com&dest=https://example.com/page.php

Use the link URL as you would use any link URL in plain text or HTML emails.

You now know how to measure email opens and clicks.

Because some people have images turned off, there may be more opens than your statistics indicate. But click counts are not up to the person's email reader; they are actual counts of every time a click was redirected through Mail Opens & Clicks.

(This article first appeared with an issue of the Possibilities newsletter.)

Will Bontrager