GreenArrow Email Software Documentation

SimpleMH Click and Open Tracking

Overview

GreenArrow Engine offers click and open tracking when the SimpleMH method is used to inject mail. SimpleMH’s click and open tracking facility can be turned on or off on a per-Mail Class basis.

Click tracking rewrites links into a URL that GreenArrow Engine’s HTTP server listens on.

Open tracking inserts tracking images into HTML emails. If images are loaded by the recipient, an open gets registered.

If you’d like to receive notifications about click and open events, the Event Notification System can do this for you.

Click and open data is stored in two tables in GreenArrow Engine’s PostgreSQL database. The data in these tables should be treated as read-only. Here are the table structures:

clickthrough_clicks Table
Column Type Description
id integer Primary key for this table.
urlid integer Primary key of the clickthrough_urls entry this record corresponds to.
clicktime integer Time in seconds past the Unix epoch that the click occured.
emailaddress character varying Email address of the subscriber who clicked.
html_or_text character(1) h for an HTML email, or t for a text email.
email_code integer Value contained in the X-GreenArrow-Click-Tracking-ID header, if present.
email_code_text character varying Value contained in the X-GreenArrow-Click-Tracking-ID header, if present.
clickthrough_urls Table
Column Type Description
id integer Primary key for this table.
sendid character varying(100) SendID of the message that was clicked or opened.
listid character varying(100) ListID of the message that was clicked or opened.
url text The original URL for links, or an empty string for opens.

Position of Open Tracking Image

When SimpleMH open tracking is enabled, a tracking image will be inserted into the HTML part.

To control the position of the open tracking image, add <opentag/> to your HTML part where you’d like it positioned. This must be done before the closing body tag (</body>). The tracking image is inserted into the first of the following within the HTML part:

  1. In place of the first <opentag> or <opentag/> tag. If more than one of these tags exist, the others are kept in the HTML unaltered.
  2. Immediately before the first </body> tag.
  3. Appended to the end of the HTML.

Dynamic Data

When dynamic data is being used, and you have control over how the URL is structured, it’s possible to reduce database bloat by putting dynamic data after a question mark. Database entries for URLs containing query strings are truncated at the question mark. The question mark, and query string following it are encoded in the re-written URL. For example, the following URL:

http://server.example.com?query=string&params=included

Would be stored in SimpleMH’s database as:

http://server.example.com

The re-written URL would look like:

http://greenarrow.example.com/click/e72/HZGVmYXVsdDEwMDAxLHQxLGh0dHA6Ly93d3cuZHJoLm5ldA/qP3F1ZXJ5PXN0cmluZyZwYXJhbXM9aW5jbHVkZWQ/scd6c91ef45

As a result, if a URL that’s inserted into a campaign is distinct for each subscriber, and contains subscriber-identification data following a question mark, SimpleMH is able to process this efficiently, and create only a single row in the clickthrough_urls table.

If a URL that’s inserted into a campaign is distinct for each subscriber, and contains subscriber-identification data that does not follow a question mark, then SimpleMH will insert a new row in the clickthrough_urls table for each user. This can lead to database bloat.

Example Query

Here’s an example query that displays opens for SendID a100525:

SELECT * FROM clickthrough_clicks WHERE id = (SELECT id FROM clickthrough_urls WHERE sendid = 'a100525' AND url = '');

The SendID is constructed by concatenating the InstanceID to the Mail Class. For example, if the following headers are present in a message:

X-GreenArrow-MailClass: a
X-GreenArrow-InstanceID: 100525

Then the resulting SendID would be a100525.

Using HTTPS

GreenArow’s Apache instance listens on TCP ports 80 (HTTP) and 443 (HTTPS) by default.

We recommend using HTTPS on port 443 for click and open tracking. TLS Certificate Configuration shows how to configure HTTPS.

If GreenArrow’s Apache instance is on the same server as another Apache instance that is bound to port 443, one solution is to bind each Apache instance to a specific IP address. Instructions for doing with GreenArrow Engine’s HTTP server are in the HTTP Server Configuration Document.

Statefulness of Event Tracking

By default, SimpleMH uses an internal database for tracking recipient email addresses and link URLs. When a click, open, unsubscribe, bounce or spam complaint is received, the data is retrieved from that internal database. For most usages of GreenArrow, this default behavior is acceptable and fast.

SimpleMH can be configured to use stateless event tracking. This causes it to embed the email address and link URL data in emails instead of recording it in its database.

Stateless event tracking has two advantages:

  1. It allows you to offload event processing to another GreenArrow server.
  2. It reduces disk space requirements.

The downside of stateless event tracking is that it causes the average email size to increase since emails are used to store this extra information. For clicks, opens, and unsubscribes the information is embedded into the link. For bounces, the information is inserted into the email as an X-Mailer-Info-Extra header.

Regardless of whether or not stateless event tracking is configured, repeat bounce counting only takes into account the bounces for the particular server on which they are processed.

To turn on stateless event tracking, run:

echo 1 > /var/hvmail/control/opt.simplemh_stateless_event_handling

To turn it back off, run:

echo 0 > /var/hvmail/control/opt.simplemh_stateless_event_handling

If you have a specific instance of a link that you’d like to track separately from other instances of that same URL, you can add the HTML attribute data-ga-linkid="linkid" immediately after the href= attribute.

The Link ID may have a maximum length of 100 UTF-8 characters. Link IDs longer than this maximum length are ignored. Lead and trailing whitespace is trimmed.

Links that have a User-Defined Link ID are tracked separately in the statstics screen and API.

For example:

<a href="https://example.com" data-ga-linkid="link123">Our Great Link</a>

If the link ID is not quoted, it will end at the first space or > after the =, for example:

<a href="https://example.com" data-ga-linkid=link123 data-something-else="foo">A</a>
<a href="https://example.com" data-ga-linkid=link123>B</a>

This data attribute is not removed from the HTML before delivery.

Skipping Click Tracking

If you have a link for which you’d like to skip click tracking (so the URL will not be rewritten), you can add the HTML attribute data-ga-notrack immediately after the href= attribute (or immediately after the data-ga-linkid= attribute if it is also being used).

For example:

<a href="https://example.com" data-ga-notrack>Our Great Link</a>
<a href="https://example.com" data-ga-linkid="link-123" data-ga-notrack>Our Great Link</a>

This data attribute is not removed from the HTML before delivery.


Copyright © 2012–2024 GreenArrow Email