Demo
Demo

Knowledge base

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

date-header-time

<source>

Which time goes into the added Date header
in the configuration this is a linedate-header-time receptioninside the block <source>
Reception time or delivery time

The default is reception: the header gets the time the message was received and queued. With the value delivery — the time it was actually sent to the recipient.

The directive works only in a pair: the manual requires add-date-header to be set to yes or override. Without it there is nothing to add, and no time to choose.

The main trap is delivery and the queue. The difference between the two values is small while the queue runs light. It becomes huge when the receiver is in retry mode: the message sits for hours or days and then leaves with the date of the moment it was finally accepted.

For the recipient this looks like a fresh message they were expecting the day before yesterday — and figuring out why the mailing “arrived at the wrong time” will then be up to them.

What the Hub does. It does not write it — and does not write the paired line either: the date is set by the sending library, and the engine does not interfere with it.

For warm-up the choice would be unambiguous: reception time. The scheduler decides when to submit a message and considers that same time the mailing time; delivery time would move the date to where the queue left retry mode.

Recommended values

What to set. The question is what the message date means for you:

Value When
reception (default) date = when it was sent; that is how both the recipient and your report understand it
delivery date = when the recipient saw it; suitable for messages where the moment of reading matters

The second makes sense for rare kinds of messages — notifications whose date must match the moment they appear in the mailbox. For a mailing the first is almost always right.

The reception default, both values and the add-date-header requirement come from the manual, § 3.3.7.2. The analysis of the queue and the breakdown of cases are ours.
Example configuration
# choosing the time only makes sense together with adding the date
<source 0/0>
    add-date-header yes
    date-header-time delivery</source>
With this pair a message that sat in the queue because of retry mode will leave with the date of the moment the queue finally moved — not when it was submitted.
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▶

Setting the time choice without adding the date

§ 3.3.7.2

What it costsThe manual names the condition plainly: the paired line must be set to yes or override. A lone line does nothing and looks like a working setting.
How to spot itThe time in messages does not change, however this line is edited.
How to do it rightPut both lines in the same source block.

Choosing delivery time for a mailing

our experience

What it costsMessages delayed by retry mode arrive with the date they left it. The recipient sees a message dated today although the mailing was the day before yesterday — and in reports your mailing spreads across days.
How to spot itThe dates of messages in seed mailboxes diverge from the mailing launch date.
How to do it rightKeep reception time: it matches what you consider the mailing time.
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
date-header-time <enumeration>
Values
reception | delivery
Default
reception § 3.3.7.2
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 obeys source merging: a connection falls under all address blocks that cover it, and the narrow one overrides the wide one. The line becomes meaningful only where adding the date is also set in the same merged set.
⇄

Related directives

1 relation

Does not work without

add-date-header<source>The condition of applicability: without adding the date there is no time to choose. § 3.3.7.2

How to check on the node
Both lines are checked together — neither works on its own:
grep -n 'add-date-header\|date-header-time' /etc/pmta/config /etc/pmta/virtualhost.txt
If adding the date is off, this line does nothing. The difference between the two values is visible only on a message that sat in the queue: for a fresh delivery both times nearly coincide.
◇

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-jobjobid-prefixallow-mailmergeadd-message-id-headeradd-received-headerAll 74 directives of the block →