Demo
Demo

Knowledge base

PMTA knowledge base›Block <signals>›Directive§ 11.1.6.2.3

engagement-tracking

<signals>

Who collects opens and clicks
in the configuration this is a lineengagement-trackinginside the block <signals>
The fork that all other tracking depends on

The line decides where the service gets opens and clicks from — and half of its metrics depend on that, including the health score. The default is no.

Value What it means
no (default) events are not collected at all
external you send the events yourself, with your own tools
sparkpost the engine itself inserts links and pixels into messages

🔴 The sparkpost value changes your messages. The engine rewrites links to its own and inserts transparent pixel images — that is, recipients’ clicks go through someone else’s domain, and opens are registered on someone else’s side.

Five neighboring lines work only with sparkpost: enable-click-tracking, enable-top-open-pixel, enable-bottom-open-pixel, tracking-domain, use-https. With other values they do nothing.

Tagging can be limited from the message itself: the data-msys-clicktrack=”0″ attribute excludes a link from tracking, and data-msys-linkname gives it a name in reports (up to 63 characters). The engine removes both attributes from the message.

The values yes and true mean external — they are kept for compatibility.

The main trap is enabling sparkpost without thinking about the domains in the message. Links will start pointing to the vendor’s domain rather than yours. For the recipient, that is someone else’s domain in a message from you — something both mailbox providers and attentive readers look at.
What the Hub does. It does not write it — and does not intend to: substituting someone else’s links into our messages would mean recipients’ clicks going through the vendor’s domain.
Recommended values

The choice here is short:

Value When
no (default) tracking is not needed
external you count opens yourself and send them to the service
sparkpost you are ready to hand links and pixels over to the vendor
All three values, the no default, the yes and true compatibility, both tagging attributes and their removal from the message come from the manual (§ 11.1.6.2.3).
Example configuration
# the engine itself will insert links and pixels — the domain in the message becomes someone else's
<signals>
    api-key 0123456789abcdef012345678901234567890123
    engagement-tracking sparkpost    tracking-domain track.mydomain.com
</signals>
Your own tracking domain at least returns the domain in the message to your control.
yellow — — directive names, blue — blocks. They are highlighted the same way in the text of the card.
▲

Common mistakes and problems

what people get wrong and how it ends2 mistakes▶

Enabling insertion without setting up your own tracking domain

our experience

What it costsLinks in messages will point to the vendor’s domain. The recipient sees someone else’s domain in a message from you, and so do mailbox providers.
How to spot itIn the delivered message, links point to an unknown domain.
How to do it rightSet up your own tracking domain and specify it in tracking-domain.

Expecting the line to work with substitution turned off

§ 11.1.6.2.3

What it costsThe insertion lines work only with engagement-tracking set to sparkpost. With other values they do nothing.
How to spot itThe line is set, and nothing in the messages has changed.
How to do it rightCheck the engagement-tracking value.
Compatibility
PowerMTA 6.0
described in the manual of this version · platform: any
The vendor does not state the first version for every directive — there is no note here. The name also appears in the 5.0 edition of the manual.
Reference data
Syntax
engagement-tracking { external | sparkpost }
Values
no | external | sparkpost (as well as yes and true, meaning external)
Applying
reload, no restart needed
Queue
will not touch what is already queued
Where to write it
<signals>
How many times
once in the block
Everything here comes from the manual, with the section.
Inheritance
There is no inheritance: the line lives inside <signals>, and there is one such block per node. The scope of export by stream is set by the enable-signals line with three levels.
⇄

Related directives

2 relations

Affects

enable-click-tracking<signals>One of the three insertions enabled only when the engine does the tracking. § 11.1.6.2.4

Where you can see it

The node can insert pixels and rewrite links by itselfOpen and click tracking: this line is what decides who collects it. § 11.1.6.2.3

Referenced from

customer-id<signals>Before version 5.5 the line was required precisely for engine-side tracking. § 11.1.6.2.7Markup parsing and editingThe directive that enables this mechanism. § 11.1.6.2.10

How to check on the node
The result is visible in the message itself — check it in a delivered one:
grep -i "signals\|html" /var/log/pmta/log | tail -20
It is more reliable to look at a message that reached the seed mailbox: the links and pixels are either in it or not.
◇

What else to read

3 articles

◇Hand a message to a webhook instead of a receiverThe queue sends the message as a POST request in the form of a JSON object; only a 2xx response counts as success.◇The node can insert pixels and rewrite links by itselfIn the vendor’s tracking mode the engine parses outgoing HTML, rewrites links to the tracking domain and inserts open pixels — with a choice of what to do if the markup cannot be parsed.◇Markup parsing and editingOpen and click tracking in sparkpost mode edits the message markup with the built-in gumbo-parser; by default a message whose markup could not be parsed is bounced.

In the Hub
Cost of a mistake
dangerous: effects outlast a rollback
Scenarios
Tracking infrastructure
Neighboring settings of the block <signals>:html-edit-error-modetracking-domainenable-top-open-pixelenable-click-trackingenable-bottom-open-pixelAll 16 directives of the block →