Demo
Demo

Knowledge base

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

add-x-msys-api-header

<domain>

Whether to add the header with parameters for SparkPost
in the configuration this is a lineadd-x-msys-api-header true for the {sparkpost} domain, false elsewhereinside the block <domain>
A bridge between the node’s settings and the service’s settings

The default depends on the recipient: true for the reserved domain {sparkpost} and false for all others.

The line adds to the message the service header X-MSYS-API — the one that sets options on the SparkPost side. Along the way it carries the message’s job label into the service’s campaign field, if there is a label.

A header already in place is left untouched. If the submitting side set it itself, the directive is ignored entirely — the value remains its own.

All of this works inside the traffic redirection mechanism: the manual describes it as a way to add capacity, for example for a season. The {sparkpost} domain is created separately, and in it auth-username and auth-password are set — a name with an optional subaccount number and the service’s access key.

The main trap is that the campaign is taken from the job label. If nobody sets the label, the campaign field in the service’s reports will be empty — and there will be nothing to break down its statistics by.

The job label is exactly what is not set here: reading the header with it is not enabled in any submission source. That is, enabling redirection would first require introducing labels.

The second half: the subaccount number is not set here, but in the authentication user name — as a prefix to it. And if the access key itself belongs to a subaccount, the number in the name is ignored.

What the Hub does. It does not write it: traffic redirection through SparkPost is not used, and there is no {sparkpost} domain in the configuration.

If it were used, one would have to start not with this line but with job labels: process-x-job is false here, and there would be nothing to carry into the campaign.

Recommended values

What to set. The default is almost always right:

Value When
do not write it the default differs for {sparkpost} and the others — and both are right
false for {sparkpost} the submitting side sets the header itself and more fully
true for other recipients pointless: only SparkPost understands the header

The third row is not a recommendation but a warning: enabled for an ordinary recipient, the line will add a header to the message that goes to the recipient with no benefit at all.

Defaults by recipient, carrying the job label into the campaign and the rule “a header already in place is left untouched” come from the manual, § 3.3.10.113.1. The syntax of the name with a subaccount — § 3.3.10.113. The breakdown of cases is ours.
Example configuration
# the domain is reserved; the access key and name set the service account
<domain {sparkpost}>
    auth-username SMTP_Injection:X-MSYS-SUBACCOUNT=123
    auth-password d41d8cd98f00b204e9800998ecf8427e
    add-x-msys-api-header true</domain>
The line here repeats the default for this domain. The subaccount number is set in the user name, not by this line — and it is ignored if the access key itself belongs to a subaccount.
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▶

Expecting a campaign name where there is no job label

§ 3.3.10.113.1

What it costsThe message’s job label is carried into the campaign field. No label — the field is empty, and there is nothing to break down the service’s statistics by.
How to spot itThe service’s reports show traffic without a breakdown by campaign.
How to do it rightIntroduce job labels at submission — otherwise there is nothing to carry over.

Looking for the subaccount setting among these lines

§ 3.3.10.113

What it costsThe subaccount is set as a prefix to the authentication user name, and it is ignored there too if the access key itself belongs to a subaccount. None of the lines with the sparkpost- prefix sets it.
How to spot itTraffic goes to the wrong service account, and the subaccount settings cannot be found in the configuration.
How to do it rightLook at the authentication user name and at where the access key comes from.
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 <boolean>
Values
yes | no | true | false
Default
true for the {sparkpost} domain, false elsewhere § 3.3.10.113.1
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. The peculiarity is in the default: it is different for the reserved {sparkpost} domain and for all others — a rare case where “not written” means different things for different recipients.
⇄

Related directives

1 relation

Does not work without

auth-username<domain>The service account and subaccount are set in the user name, not by this line. § 3.3.10.113.1

How to check on the node
The setting is visible in the configuration, the consequence — in the message and in the service’s reports:
grep -n -A5 'domain {sparkpost}' /etc/pmta/config
grep -n 'process-x-job' /etc/pmta/config /etc/pmta/virtualhost.txt
The second command matters more than the first: without a job label the campaign field in the service’s reports will stay empty. The presence of the header itself is checked with a message to a seed mailbox over the same route.
◇

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-header-metadataAll 135 directives of the block →