Demo
Demo

Knowledge base

PMTA knowledge base›Block <source>›Directive§ 3.3.7.59

retain-x-schedule

<source>

Whether to keep the x-schedule header in the message on delivery
in the configuration this is a lineretain-x-schedule falseinside the block <source>
Whether to show the recipient when you planned to send

The default is false: the header is removed before delivery. With true it stays in the message.

The manual stresses that the directive is independent of the permission to read the header: they are usually set together, but there is no link between them, and any combination is valid.

The main trap is that the manual speaks with two voices about the “both off” case. This section states: with both directives false the engine ignores the header but still removes it before delivery. The neighboring sections on reading — three times, for three different headers — state the opposite: an unread header stays in the message.

The wording “still removes” appears here and in the signing key pair, and both are written as carbon copies. The weight of evidence is on the side of “stays”. The question can be settled only with a message to your own mailbox.

What the Hub does. It does not write it: scheduling plays no part in the Hub’s submission, reading the header is not allowed in the sources, and there is nothing to remove.
Recommended values

What to set. The default is right almost always:

Value When
no (default) the usual case: the recipient has no need to know when you planned to send
yes the message goes to your own seed mailbox, and the schedule needs to be seen by eye

The second case is temporary, for the duration of an investigation. Left on, it shows recipients how your scheduling works.

The false default and independence from the permission to read the header come from the manual, § 3.3.7.59. The contradiction with the reading sections is our finding. The breakdown of cases is ours.
Example configuration
# the header stays in the message — only for your own mailboxes
<source 10.0.0.5>
    process-x-schedule true
    retain-x-schedule true</source>
The pair makes sense on a separate source for seeding: the message arrives in your own mailbox together with the windows in which delivery was attempted.
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▶

Considering the question settled by the manual

§ 3.3.7.59

What it costsAbout the “both directives off” case the manual has two mutually exclusive statements. Choosing between them by the authority of the text is impossible, and any decision made by reading may turn out wrong for your engine version.
How to spot itThe header behaves differently than expected from what was read.
How to do it rightSend a message with the service headers to your own mailbox and see what arrived. One check closes the question for the whole family of headers at once.

Leaving it on after the investigation

our experience

What it costsRecipients see the time windows in which you planned to send. From this the structure of your scheduling can be read: batch size, time of day, window length.
How to spot itThe header with the schedule shows up in messages received in other people’s mailboxes.
How to do it rightReturn the default right after the investigation and keep retention only on a source for your own mailboxes.
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-schedule <boolean>
Values
yes | no | true | false
Default
false § 3.3.7.59
Applying
reload, no restart needed
Queue
will not touch what is already queued
Where to write it
<source>
How many times
once in the block
Everything here comes from the manual, with the section.
Inheritance
The directive lives in <source> and follows source merging: a connection falls under all address blocks that cover it, and a narrow one overrides a broad one. For submission under a login the named block applies, and the line has to be repeated in it — we did not see inheritance from address blocks into a named one on our installation.
⇄

Related directives

2 relations

Does not work without

process-x-schedule<source>The first half of the pair; the manual calls them independent, and this is the case where independence creates a question rather than convenience. § 3.3.7.59

Applies to

Headers the sender uses to control deliveryThe “keep or remove” half for one of the six service headers. § 3.3.7.59

How to check on the node
The setting is visible in the configuration, the consequence — in the delivered message:
grep -n 'retain-x-schedule' /etc/pmta/config /etc/pmta/virtualhost.txt
Empty output means the vendor default. What actually reached the recipient is shown only by a message in a seed mailbox — and that is also the only way to resolve the manual’s contradiction about the “both off” case.
◇

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.◇Who is allowed to submit mail and for whom to accept itOut of the box, the node accepts submission only from the machine itself; two different questions — “who can send through us” and “for whose addresses we accept mail” — are answered by different directives.◇Headers the sender uses to control deliverySix control headers let the submitting side choose a stream, tag a message with a job, set signing options and the key, the envelope identifier and the schedule; each is allowed separately and per source.

In the Hub
Cost of a mistake
reversible: harms only while it is set
Scenarios
Connect a sending platform
Neighboring settings of the block <source>:process-x-scheduleretain-x-dkim-keyprocess-x-dkim-keydefault-virtual-mtasmtp-serviceAll 74 directives of the block →