Demo
Demo

Knowledge base

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

process-x-envid

<source>

Whether to read the x-envid header and set the envelope identifier from it
in the configuration this is a lineprocess-x-envid falseinside the block <source>
A workaround for those who cannot say it via the protocol

The default is false. With the permission the engine takes the value of the x-envid header, makes it the message’s envelope identifier — the very one that goes into delivery notifications — and removes the header.

The standard way to set the envelope identifier is different: the ENVID parameter of the MAIL command in the protocol itself. The manual names directly the case the header was made for — the submitting application does not allow control of this parameter. Then the same value is passed as a message header.

Without the permission the header is ignored and, as the section says plainly, stays in the message.

The envelope identifier is the second of the two submission labels. Unlike the job label, it identifies one message rather than a group, and serves as the –envId filter in listing, deletion and priority change.

The main trap is that the header silently loses to the protocol. If the submitting library can pass the parameter in the MAIL command after all and does, the message will get the identifier from there. Figuring out which of the two routes worked will have to be done from accounting, not from the configuration.

The second half is the usual one for this family: without the permission there will be no error — the header will simply go to the recipient along with your internal message identifier.

What the Hub does. It does not write it: the Hub sets no envelope identifier, neither with a header nor with a protocol parameter.

The envid field is part of the record-fields asterisk, which the Hub sets for all record types — so it arrives in telemetry with every record and is always empty. The Hub links events to sends by the recipient address and the sending address, not by a message identifier.

Recommended values

What to set. There is exactly one question — whether the submitting side can say it via the protocol:

Value When
no (default) the envelope identifier is not needed or is set with the MAIL command parameter
yes the submitting application does not allow control of the parameter, and there is no other way

The second is precisely a workaround, not an equivalent replacement: a protocol parameter does not travel in the message body and cannot end up with the recipient.

The false default, removal of the header when read and the purpose “when the application does not allow control of the parameter” come from the manual, § 3.3.7.44. The assessment “a workaround, not a replacement” is ours.
Example configuration
# the header is needed where the submitting application cannot set the ENVID parameter
<source 10.0.0.0/24>
    process-x-envid true</source>
A message with the line “x-envid: order-40213” will get this envelope identifier, and the header itself will be removed before delivery. Without the permission line the same header will go to the recipient.
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 header without granting permission

§ 3.3.7.44

What it costsThe identifier will not appear, filtering by it will find nothing, and the header itself will stay in the message and go to the recipient — together with your internal order or message number.
How to spot itx-envid is visible in the delivered message.
How to do it rightGrant the permission to the source block that the submission falls under, or remove the header on the submitting side.

Using the header while having the protocol parameter

§ 3.3.7.44

What it costsThe value travels in the message body instead of the service channel. If the permission is off at the same time, it reaches the recipient — which never happens with the MAIL command parameter.
How to spot itThe submitting library supports ENVID, but the configuration still relies on the header.
How to do it rightPass it as a MAIL command parameter, and leave the header for applications that cannot do that.
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
process-x-envid <boolean>
Values
yes | no | true | false
Default
false § 3.3.7.44
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

1 relation

Applies to

Headers the sender uses to control deliveryOne of the six submission control headers, with its own permission on the source. § 3.3.7.44

How to check on the node
The permission is visible in the configuration, the result — in the queue:
grep -n 'process-x-envid' /etc/pmta/config /etc/pmta/virtualhost.txt
pmta list --envId=order-40213 --maxitems=20
If the message is not found by the identifier, the engine did not set it: either there is no permission, or the header arrived in the wrong form. The Hub does not set the envelope identifier — neither in warm-up nor in the configuration templates — so warm-up messages have an empty envId field in telemetry.
◇

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 →