Demo
Demo

Knowledge base

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

http-delivery-url

<domain>

The address to which the queue hands messages with a POST request
in the configuration this is a linehttp-delivery-urlinside the block <domain>
Where the request with the message goes

It works for an http-delivery queue (type) and is mandatory for it. It sets the address to which the node sends a POST request with the message as a JSON object — one message per request.

The address is restricted. It must be absolute and begin with the http or https scheme. It must not contain credentials, a query string or a fragment — the manual lists these three parts separately. The host is a name or an address; an IPv6 address goes in square brackets. The port is optional: without it, 443 is implied for https and 80 for http.

Credentials do not go here. Since they cannot be written into the address, the authorization header is put into a file and plugged in with the http-delivery-extra-headers line.

The main trap is the http scheme instead of https. The whole message goes to this address, along with the envelope addresses and headers. An unencrypted request exposes message contents on the network in plain form — and usually together with the authorization header you attached.
What the Hub does. It does not write it: it creates no queues of this type. When it does, the address will be its own — the Hub’s bounce and complaint handler already works over HTTP.
Recommended values

https only. Message contents go to this address; an unencrypted channel is out of place here under any circumstances.

A name instead of an address. The handler moves, the address changes — the name survives the move, and the configuration line stays the same.

The path is worth versioning. /api/v1/… makes it possible to change the processing format without touching node configurations.

The requirements about an encrypted scheme, a name and a path version are ours. From the manual here come the line being mandatory for this type, the three prohibited address parts, the IPv6 address notation and the default ports.
Example configuration
# a complaint handler: https only, a name, a versioned path
<domain feedback.example.com>
    type http-delivery
    http-delivery-url https://hub.example.com/api/v1/feedback</domain>
No port is specified — 443 is implied, because the scheme is https. For http, 80 would be implied.
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▶

Keeping the http scheme

our experience

What it costsThe whole message goes to the address along with the envelope addresses and headers, and next to it — the authorization header from the extra headers file. All of this travels over the network in plain text.
How to spot itIn the configuration the address starts with http://.
How to do it rightSwitch the handler to https and fix the line.

Writing a login and password into the address

§ 3.3.10.112.1

What it costsThe manual directly prohibits a credentials part in this address. The line will not be accepted, and the queue will be left without an address.
How to spot itThe http-delivery queue sends nothing.
How to do it rightMove authorization into a headers file and plug in http-delivery-extra-headers.
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-url <url>
Values
an absolute address with the http or https scheme; without credentials, a query string or a fragment; an IPv6 address in square brackets; the port is optional
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 merges 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; messages already in the queue will go to the new address.
⇄

Related directives

1 relation

Does not work without

Five ways for a queue to hand off a messageThe line is mandatory for a queue that hands messages to a webhook; in a queue of another type it is ignored. § 3.3.10.112.1

Referenced from

Hand a message to a webhook instead of a receiverThe handler address: without it a queue of this type does not work. § 8.5.1

How to check on the node
The effective address is printed by the queue settings command; whether it is reachable is checked with a regular request:
pmta show settings feedback.example.com/vmta1 | grep -i http-delivery-url
curl -s -D - -o /dev/null -X POST https://hub.example.com/api/v1/feedback | head -1
A response outside the 2xx family means messages will pile up in the queue: the node treats such a response as a temporary failure. 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-extra-headerssparkpost-sandboxsparkpost-ip-pooladd-x-msys-api-headeradd-x-msys-api-header-metadataAll 135 directives of the block →