Demo
Demo

Knowledge base

PMTA knowledge base›Block <domain>›Directive§ 3.3.10.113.2

add-x-msys-api-header-metadata

<domain>

Which message headers are copied into metadata for SparkPost
in the configuration this is a lineadd-x-msys-api-header-metadata noneinside the block <domain>
Three conditions under which the line does not work

There is no default. The value is name=header_HEADER pairs separated by commas: on the left the metadata field name on the service side, on the right the message header to take the value from.

The manual names three conditions under which the line does not work, all in one paragraph:

The parent add-x-msys-api-header is not set — the directive is ignored. The service header is already in place in the message — ignored. The node is configured to remove the named header — the line “may not be effective”.

And a fourth limitation separately: it does not work for headers the node adds itself. That is, the reception trace or a message identifier added by the engine cannot be carried into metadata.

The main trap is the third condition. The list of removed headers (remove-header) is usually written once and forgotten, and it lives in the source block — far from this line in the recipient block. A header that ends up on both lists will quietly not reach the metadata, and the manual describes this cautiously: “may not be effective”.

The second half: the conditions are silent. None of the four produces an apply error. The line is in the configuration, looks working, but the metadata is empty — and which of the conditions triggered can only be found by elimination.

What the Hub does. It does not write it: redirection through SparkPost is not used.

If it were used, the third condition would trigger at once: the Hub writes remove-header with a list of platforms’ service headers in all submission sources, and an attempt to carry any of them into metadata would be useless.

Recommended values

What to set. The value is pairs; you have to choose what to carry:

Value When
do not write it the service’s metadata is not used
your own pair messages have a header with a label useful for analysis — client, segment, campaign

The header to carry must be your own and come from outside: those added by the node do not work by design, and removed ones will not arrive.

The syntax, the absence of a default and all four failure conditions come from the manual, § 3.3.10.113.2. The assessment “the conditions are silent” is ours.
Example configuration
# the header must come from outside and not be on the removal list
<domain {sparkpost}>
    add-x-msys-api-header true
    add-x-msys-api-header-metadata job=header_X-MyJobId</domain>
On the left the service’s metadata field name, on the right the message header. If the same header is on the source’s removal list, the transfer will not work.
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▶

Carrying a header the node itself removes

§ 3.3.10.113.2

What it costsThe removal list lives in the source block, this line in the recipient block. A header that ends up on both will not reach the metadata, and there will be no error.
How to spot itMetadata in the service’s reports is empty, the line is in the configuration.
How to do it rightCheck the header name against the source’s removal list.

Carrying a header added by the node itself

§ 3.3.10.113.2

What it costsFor such headers the line does not work by design. The reception trace, an added message identifier and the like will not get into metadata.
How to spot itMetadata is empty exactly for the fields taken from headers added by the node.
How to do it rightCarry only headers coming from the submitting side.
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
add-x-msys-api-header-metadata <mapping>
Values
name=header_HEADER pairs separated by commas
Default
none § 3.3.10.113.2
Applying
reload, no restart needed
Queue
will not touch what is already queued
Where to write it
<domain>
How many times
once in the block
Everything here comes from the manual, with the section.
Inheritance
The directive lives in <domain> and obeys the merging of receiver blocks. But it depends on what is written in the source block: the list of removed headers lives there, and it can make this line useless.
⇄

Related directives

1 relation

Does not work without

auth-username<domain>The line works only inside traffic redirection, and that starts with authentication at the service. § 3.3.10.113.2

How to check on the node
Three places have to be checked at once — otherwise you cannot tell which condition triggered:
grep -n 'add-x-msys-api-header' /etc/pmta/config
grep -n 'remove-header' /etc/pmta/config /etc/pmta/virtualhost.txt
A header named in the first command and appearing in the second will not reach the metadata. There will be no error — only empty metadata in the service’s reports.
◇

What else to read

3 articles

◇The activation key is a prerequisite for installation, not a step after itWithout an activation key from SparkPost support the engine neither installs nor runs, and the license tier sets the outbound connection ceiling: on Standard everything above 200 is ignored.◇Cloud restrictionsClouds restrict outbound mail on port 25 until you ask them to lift the limit, and mailbox providers treat their address ranges with suspicion.◇How to turn a sending plan into hardwareTwo constants for sizing any node: about 2 KB of memory per queued recipient and spool space proportional to the total size of the messages.

In the Hub
Cost of a mistake
safe: a wrong value breaks nothing
Scenarios
Capacity planning
Neighboring settings of the block <domain>:http-delivery-urlhttp-delivery-extra-headerssparkpost-sandboxsparkpost-ip-pooladd-x-msys-api-headerAll 135 directives of the block →