Demo
Demo

Knowledge base

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

auto-qualify-domain

<source>set by the Hub

Whether to complete an incomplete address domain with the domain suffix
in the configuration this is a lineauto-qualify-domain trueinside the block <source>
Completing addresses that arrived without a domain

The default is true. If an address arrives in the SMTP conversation whose domain consists of a single part (user@host), the engine completes it by appending the domain suffix: on the machine mail.foo.com the address becomes user@host.foo.com.

The completion applies to both addresses of the conversation — both MAIL FROM and RCPT TO.

The suffix is set separately, with the domain-suffix line at the root of the file. If it is not set, it is taken from the machine’s own name.

The main trap is silent address substitution. Completion looks like a convenience for local senders, but in fact it edits what the client sent. A typo in the domain (user@gmail instead of user@gmail.com) is not rejected but turns into an existing address in your domain — and the message goes somewhere it was not meant to go.

The second edge: the default suffix is taken from the machine name. So on a node whose name you did not choose, addresses are completed with a domain you did not think about.

What the Hub does. It writes auto-qualify-domain no in the general <source 0/0> source — since Aug 29, 2026.

Why it was turned off. Completion was invented for internal mail systems, where user@host is a legitimate notation. Here submission comes from sending platforms with address lists, and an incomplete domain there means an error in the list. The right reaction to an error is a rejection at submission, so that the list gets cleaned; completion instead makes the address “correct”, the message goes nowhere and brings a bounce into the receiver’s statistics.

As a side effect, a second case is closed too: a completed address could end up in the message’s return path where rewriting is not enabled.

Recommended values

What to set. The question is whether you trust the addresses that arrive at submission:

Value When
true (default) local old-style scripts submit, and addresses without a domain are legitimate
false submission comes from a platform that always gives a full address — then an incomplete one is a typo, and rejecting it is more honest

The second is stricter and almost always more correct for mailings: a message sent to a completed address complains to no one — it simply goes to the wrong recipient.

The true default, the analysis of the user@host example and the note that the suffix is configurable come from the manual, § 3.3.7.73 and § 3.3.1.34. The breakdown of cases is ours.
Example configuration
# an incomplete address is a sign of a typo, not an abbreviation
<source 0/0>
    auto-qualify-domain false</source>
With this value an address like user@gmail will not be completed with your domain but rejected as incomplete — and the sender will learn about 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▶

Keeping completion where full addresses are submitted

§ 3.3.7.73

What it costsA typo in the domain stops being an error: an incomplete address is completed with your suffix and turns into an existing one. The message goes to the wrong recipient, and neither the sender nor the node reports it.
How to spot itAccounting contains recipients in your domain who were not in the mailing.
How to do it rightTurn completion off where the submitting side is obliged to give a full address.

Relying on a suffix nobody set

§ 3.3.1.34

What it costsWithout an explicit line the suffix is taken from the machine name. On a node whose name was given by the hosting provider, addresses are completed with a domain that has nothing to do with your mailing.
How to spot itCompleted addresses end with the hosting provider’s domain.
How to do it rightEither set the suffix explicitly or turn completion off.
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
auto-qualify-domain <boolean>
Values
yes | no | true | false
Default
true § 3.3.7.73
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 suffix itself is set at the root of the file and is not divided by source — it is one for the whole installation.
⇄

Related directives

1 relation

Does not work without

domain-suffixGlobalWhat exactly the address is completed with; if not set, it is taken from the machine name. § 3.3.7.73

How to check on the node
Both lines are checked together: without a suffix there is nothing to complete with except the machine name:
grep -n 'auto-qualify-domain\|^domain-suffix\|^host-name' /etc/pmta/config
If the suffix is not set, completion uses the machine name — it is worth looking at what it actually is. Whether completion fired is visible from the addresses in accounting: they are already full there.
◇

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
Value
The Hub picks it itself — pace, warm-up stage, metrics
Cost of a mistake
reversible: harms only while it is set
Scenarios
Connect a sending platform
Neighboring settings of the block <source>:allow-smtputf8disconnect-on-transient-errorallow-authaccept-invalid-recipientsalways-allow-api-submissionAll 74 directives of the block →