Demo
Demo

Knowledge base

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

http-delivery-extra-headers

<domain>

A file with additional request headers
in the configuration this is a linehttp-delivery-extra-headersinside the block <domain>
Where to put the authorization header

An optional line for a queue of the http-delivery type (type). It names a file from which the node takes additional headers and adds them to the request carrying the message. Each header is on its own line in the file.

Why it exists. Credentials in the http-delivery-url address are forbidden by the manual, while the handler almost always requires authorization. The headers file is the only provided way to pass it.

It is good not only for authorization: any constant header that must accompany every request goes here too — a source tag, a contract version, a node identifier.

The main trap is file permissions. It holds a working access key to your handler, and the service reads it at every configuration reload. A file with default permissions is visible to everyone on the node; the key is carried off with a single command.
What the Hub does. It does not write it: it does not create queues of this type. If it does, the access key to its own handler will go here — and the file has to be closed the same way the telemetry webhook headers file /etc/pmta/mtahub-headers.txt already is: owner — the service user, permissions 600.
Recommended values

Permissions 600, owner — the service user. The file holds a working key, and that is no exaggeration.

One file per handler, not per queue. If there are several queues of the http-delivery type and they share one handler, there is no point multiplying the key across files — it would have to be changed in all of them.

The line is optional. Without it the request goes out without additional headers; for an open handler that is enough.

The requirements for permissions and for one file per handler are ours. From the manual come the optional nature of the line, the “one header per line” file format and the example with an authorization header.
Example configuration
# the access key lives in the file — it must not be kept in the address
<domain feedback.example.com>
    type http-delivery
    http-delivery-url https://hub.example.com/api/v1/feedback
    http-delivery-extra-headers /etc/pmta/http-delivery-headers.txt</domain>
Inside the file — one header per line, for example a line with Authorization. File permissions must be closed: the node reads it itself, and nobody else needs it.
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▶

Leaving the file with open permissions

our experience

What it costsAny user of the node can read the access key to the handler. On a node with outside accounts this is a leak, plain and simple.
How to spot itls -l shows permissions broader than 600.
How to do it rightClose the file: owner — the service user, permissions 600.

Changing the key and expecting it to be picked up

§ 3.3.10.112.2

What it costsThe file is read together with the configuration. The new key is on disk, while the node keeps sending the old one until the settings are reloaded.
How to spot itAfter the key change the handler replies with an authorization error, and the queue grows.
How to do it rightAfter editing the file, run pmta reload.
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
http-delivery-extra-headers <path>
Values
a file path; one header per line in the file
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 value is merged across <domain> blocks from general to specific: the best-matching block wins, not the last one in the file. In a queue of another type the line is ignored. It is picked up by pmta reload — and the file is re-read at the same time: after changing the key, the configuration still has to be reloaded.
⇄

Related directives

1 relation

Does not work without

Five ways for a queue to hand off a messageA line from the set of the type that hands messages to a webhook; ignored in a queue of another type. § 3.3.10.112.2

How to check on the node
The path is printed by the queue settings command; permissions on the file itself are checked in the system:
pmta show settings feedback.example.com/vmta1 | grep -i extra-headers
ls -l /etc/pmta/http-delivery-headers.txt
Permissions wider than 600 mean the access key to the handler is visible to everyone on the node. The Hub does not create queues of this type.
◇

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
dangerous: effects outlast a rollback
Scenarios
Connect a sending platform
Neighboring settings of the block <domain>:http-delivery-urlsparkpost-sandboxsparkpost-ip-pooladd-x-msys-api-headeradd-x-msys-api-header-metadataAll 135 directives of the block →