Demo
Demo

Knowledge base

PMTA knowledge base›Mechanism§ 8.1.5

The HTTP submission format

inline format
A message in parts instead of a finished one

Since version 5.5, a message submitted over HTTP does not have to be assembled: in the content object, instead of a finished email_rfc822, you pass from, subject, reply_to, headers, text, html, amp_html and attachments, and the node assembles the message itself.

Encoding is the node’s job: it encodes non-ASCII characters as needed — in headers per RFC 2047, in the body as quoted-printable. Text in the request is plain UTF-8 and must not be encoded: substitutions are performed before encoding and line wrapping.

Duplicates are silently ignored: of parts with the same name, only the first gets into the message.

The main trap is encoding the text in advance. The manual explicitly forbids it: the node does the encoding, and pre-encoded text ends up in the message as something other than intended.
What the Hub does. Not used: submission goes over SMTP, and the Hub assembles messages itself.
Recommended values

Fields of the content object:

Field What it carries
from, reply_to, subject the sender, the reply address, the subject
headers custom headers
text, html, amp_html body parts
attachments attachments
The content object fields, encoding on the node side, the ban on encoding it yourself and the fate of duplicates come from the manual (§ 8.1.5). The trap analysis is ours.
Example configuration
# content in parts instead of a finished message
"content": {"from": "news@example.com", "subject": "[name], hello", "text": "Hi [name]", "html": "<p>Hi [name]</p>"}
The [name] substitutions are expanded before encoding, so the text in the request stays ordinary UTF-8.
yellow — — directive names, blue — blocks. They are highlighted the same way in the text of the card.
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.
⇄

Related entries

1 relation

Can be replaced by

Encodings at submissionA related mechanism: they work together. § 8.1.5

How to check on the node
Check whether the node accepts submission over HTTP:
grep -n -A4 '<transmissions-api' /etc/pmta/config
Without the <transmissions-api> and <transmissions-api-listener> blocks the format is not available at all.
◇

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
safe: a wrong value breaks nothing
Scenarios
Connect a sending platform