Demo
Demo

Knowledge base

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

custom-message-id-header

<signals>

The header by which the service links a message's events
in the configuration this is a linecustom-message-id-header noneinside the block <signals>
Your own message identifier in external analytics

The service receives delivery events from the node, and opens and clicks from somewhere else. To link them into one message, a common identifier is needed, and this line names the header to take it from. There is no default.

🔴 It works only with engagement-tracking set to external. The manual says so directly: linking is required exactly where you send the open events yourself.

Length — up to 512 Latin characters. Mail merge has its own way: there the *custommessageid variable is used instead of a header.

What it is really for. Without linking, the service sees two unrelated streams: “message delivered” and “someone opened something.” Half of its conclusions are built on connecting the two, and the vendor calls linking a condition for getting full value from the analytics.

The main trap is setting the header when the engine does the tracking. With the sparkpost value the engine links events itself, and the line adds nothing. It is needed in exactly the opposite case.
What the Hub does. It does not write it: we do not use uploading to external analytics.

🔎 The technique itself is common and familiar: your own message identifier set in a header — the same thing we do with the header_NAME accounting field, only for the other side.

Recommended values

The line is needed in exactly one combination:

Tracking The line
external needed: otherwise the events will not be linked
sparkpost not needed: the engine links them itself
no not needed
The requirement of the external value, the 512-character limit and the caveat about the mail merge variable come from the manual (§ 11.1.6.2.11).
Example configuration
# you send the open events — a common identifier is needed
<signals>
    engagement-tracking external
    custom-message-id-header x-my-msgid</signals>
In the message the header looks like this: x-my-msgid: 01234.abc@mysite.
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 ends1 mistake▶

Setting the header when the engine does the tracking

§ 11.1.6.2.11

What it costsWith the sparkpost value the engine links events itself. The line adds nothing and misleads the reader.
How to spot itThe line sits next to engagement-tracking sparkpost.
How to do it rightRemove it, or switch tracking to external if you send the events yourself.
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
custom-message-id-header <header-name>
Values
a header name; the value in the message is up to 512 Latin characters
Default
none § 11.1.6.2.11
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.
⇄

Related directives

1 relation

Works together with

Two tags the sender puts on a messageOne more message identifier, only for the other side. inference

How to check on the node
Check it on a sent message — the header must be in it:
grep -i "signals" /var/log/pmta/log | tail -20
It is more reliable to look at the message headers in the seed mailbox: if the header is not there, the service has nothing to link by.
◇

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
safe: a wrong value breaks nothing
Scenarios
Tracking infrastructure
Neighboring settings of the block <signals>:privacy-policyretain-x-sp-subaccount-idhtml-edit-error-modeengagement-trackingtracking-domainAll 16 directives of the block →