Demo
Demo

Knowledge base

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

retain-x-sp-subaccount-id

<signals>

Whether to keep the subaccount header in the sent message
in the configuration this is a lineretain-x-sp-subaccount-idinside the block <signals>
The same name 1:<inline-seeding><signals>— some of them are other settings, some are the same one
The header stays not only for the recipient

The default is false. With true the engine keeps the x-sp-subaccount-id header in the message when sending.

The manual adds an important caveat: the header stays in the message even when reading is turned off — that is, with process-x-sp-subaccount-id false it also reaches the recipient.

And the other half, which is why the line is enabled. With true it becomes possible to write the header’s contents to accounting files, into delivery, bounce and transient failure records. This comes in handy for those who pass events to the service manually, with their own call.

The line is shared by two blocks: set here or in the <inline-seeding> block, it applies to both.

The main trap is that the header reaches the recipient in two cases out of three. It stays both with true and with reading turned off. The only combination in which it is removed is reading enabled and retention disabled. The client’s service number then lives in someone else’s mailbox for as long as the message lives there.

The other half: the ability to write the number to accounting is a separate record field setting, not a consequence of this line. It only opens that possibility.

What the Hub does. It does not write it: it does not use the Signals service, and our submission has no subaccount header.

If such a header appeared, it would not get into telemetry by itself: the asterisk in record-fields takes the standard set of fields, while a message header has to be named as a separate header_… field — that is how the Hub adds header_feedback-id to complaints.

Recommended values

What to set. The case for true is narrow and quite specific:

Value When
false (default) the header is not needed in accounting — the usual case
true events are passed to the service manually, and the subaccount number is needed in accounting records

The second is enabled for accounting, not for the recipient. The price is that the number travels with the message; it cannot be reduced, except by cleaning out the header with a separate remove-header line.

The false default, keeping the header with reading turned off, the ability to write it to accounting records and the line being shared with the seeding block come from the manual, § 11.1.6.2.13. The breakdown of cases is ours.
Example configuration
# the header is kept for the sake of accounting records, not for the recipient
<signals>
    api-key 0123456789012345678901234567890123456789
    process-x-sp-subaccount-id true
    retain-x-sp-subaccount-id true</signals>
The pair is enabled so that the subaccount number gets into accounting records. The header itself then reaches the recipient too.
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 ends3 mistakes▶

Treating the disabled line as a guarantee that the header is removed

§ 11.1.6.2.13

What it costsWith reading turned off the header stays in the message — the section says so directly. The service number travels to the recipient and stays in their mail.
How to spot itThe subaccount header is visible in the message received in the seed mailbox, even though both lines are off.
How to do it rightCheck with a message and, if necessary, clean out the header with the header removal line on the source.

Expecting the number in accounting from this line alone

§ 11.1.6.2.13

What it costsThe line only opens the possibility: which fields get into accounting records is decided by the field setting. Without it the number will not reach the files.
How to spot itThe line is enabled, but there is no subaccount number in the accounting records.
How to do it rightAdd the field to the accounting record field setting.

Treating the line as a setting of this block only

§ 11.1.6.2.13

What it costsIt is shared by two: enabled for event export, it is enabled for seeding too.
How to spot itSeeding behavior changed after the event export block was edited.
How to do it rightRead both lines as one and check both blocks at once.
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
retain-x-sp-subaccount-id { yes | no }
Values
yes | no | true | false
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
The directive lives in <signals>, but it has no inheritance in the usual sense: it is shared with the seeding block, and set in either of the two it applies to both. A value “only for event export” does not exist.
⇄

Related directives

1 relation

Affects

The telemetry contractWith the line enabled, the subaccount number can be written into delivery, bounce and transient failure records. § 11.1.6.2.13

How to check on the node
The line is visible in the configuration; check both blocks and the message itself:
grep -n -A4 '^<signals>\|^<inline-seeding>' /etc/pmta/config
The absence of the lines does not mean the header is removed: with reading turned off it stays in the message. The only way to be sure is a message to a seed mailbox.
◇

What else to read

3 articles

◇A license for a fleet, not for a serverThe license is not bound to a server: it is installed on as many machines as the instance limit allows, and the nodes send volume statistics to the vendor every hour.◇How the node selects a source and combines its settingsA connection falls under all source blocks whose addresses cover it, and they act merged — the narrow one overrides the wide one; named blocks are attached only by direct reference.◇Address lists — named and unnamedA list of addresses, domains, patterns or hashes; a named one is attached by directives such as suppression, an unnamed one lives inside an inbound mail processor.

In the Hub
Cost of a mistake
reversible: harms only while it is set
Scenarios
Sender isolation
Neighboring settings of the block <signals>:privacy-policycustom-message-id-headerhtml-edit-error-modeengagement-trackingtracking-domainAll 16 directives of the block →