Demo
Demo

Knowledge base

PMTA knowledge base›Mechanism§ 14

Markup parsing and editing

html rewriting engine
What tracking rests on

When engagement-tracking in the <signals> block is set to sparkpost, the node itself inserts links into messages that produce open and click events. For that, the markup is parsed by the built-in gumbo-parser library — the HTML5 parser from the manual’s acknowledgments.

The manual does not describe how exactly the markup is edited: only the links or the whole document. So before enabling it, compare a message before and after the node.

What to do with an unparsed message is decided by html-edit-error-mode: by default a permanent failure, otherwise the message leaves unchanged, that is, without tracking. In both cases the node writes the error to the log.

The main trap is the silent error mode. With deliver-unmodified an unparsed message leaves without tracking, and the only sign is an open rate lower than deserved — if nobody reads the log.
What the Hub does. There is no <signals> block in the Hub templates, and the node does not touch message markup. Engine tracking is worth enabling only after comparing messages from every template family before and after the node and choosing the error mode.
Recommended values

Parse error mode:

Value What happens to the message The cost
perm-fail, the default a permanent failure a lost message
deliver-unmodified leaves unchanged understated open statistics
The gumbo-parser library comes from the manual (§ 14); the sparkpost mode and the error modes are § 11.1.6.2.3, § 11.1.6.2.10. The analysis of consequences is ours.
Example configuration
<signals>
    api-key 0123456789012345678901234567890123456789
    engagement-tracking sparkpost    html-edit-error-mode deliver-unmodified
</signals>
Following the manual’s example: without api-key the node will not start, and deliver-unmodified sends an unparsed message unchanged.
yellow — — directive names, blue — blocks. They are highlighted the same way in the text of the card.
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.
⇄

Related entries

3 relations

Does not work without

engagement-tracking<signals>The directive that enables this mechanism. § 11.1.6.2.10

Applies to

The node can insert pixels and rewrite links by itselfA related mechanism: they work together. § 11.1.6.2.10

Where you can see it

html-edit-error-mode<signals>The directive that enables this mechanism. § 11.1.6.2.10

How to check on the node
Find markup parse errors:
grep -i 'html' /var/log/pmta/log | tail -20
The node writes a parse error to the log in both modes — the only trace of a message that left without tracking. The log path comes from log-file.
◇

What else to read

3 articles

◇How a message gets into the engineSix described submission methods: extended SMTP, four language bindings and a directory the node watches on disk.◇What the node tells about itself and through which channelsSeven observation surfaces: the web monitor, the console in four formats, the log, accounting, accounting search, metrics and export to external analytics.◇The watchdog that restarts the engineKeeps an eye on the engine and brings it back up after a crash by itself, sending a crash report to the postmaster address.

In the Hub
Cost of a mistake
disruptive: applying it interrupts the node
Scenarios
Troubleshoot deliverability · Connect a sending platform · Tracking infrastructure