Demo
Demo

Knowledge base

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

retry-after-dns-error

<domain>set by the Hub

The interval to retry at when the queue stalled because of a DNS error
in the configuration this is a lineretry-after-dns-error 1minside the block <domain>
A separate step for when the receiver is not to blame

A queue goes into retry mode not only because the receiver refused. It also goes there when the receiver could not be reached at the name level: the DNS server did not answer, a record came back with a temporary error, the resolver hit a timeout. For this case not retry-after but this line applies.

The separation makes sense for exactly one reason: the receiver did not see this attempt. There was no connection, it did not get the message, and the sender’s reputation is not at risk. So here you can hurry — the vendor default 1m is noticeably shorter than the usual step, and the manual directly advises keeping it smaller.

It has no paired value of its own for backoff mode — and none is needed: it applies in backoff too. It is the only line in the retry family that has no twin with the backoff- prefix.

The main trap. A DNS error is not always temporary. If a domain has no records at all — a typo in the address, a domain that lost its delegation — the resolver will answer the same way even every half minute, and the queue will stay silent for the whole bounce-after period. At 30s and a three-day period that is 8640 useless resolver queries for a single message.
What the Hub does. The receiver policy template has 30s for fourteen large mailbox providers: their DNS does not go away for good, and if there is no answer, it is almost certainly a one-minute failure on our side. In the general <domain *> it is 5m: for an arbitrary domain a DNS error can be permanent, and five minutes is still six times shorter than the regular 30m step. Until Sep 15, 2026 the general block had 30s.
Recommended values

Shorter than the usual step is a rule, not a matter of taste. The point of a separate line is that the receiver has nothing to do with it. Making it equal to retry-after means giving up the separation altogether.

Half a minute is enough. A temporary resolver failure lasts seconds or minutes; if it lasts longer, the pause is not the issue.

For <domain> with an asterisk keep it longer. Unknown domains do have typos and dead zones, and half a minute for such a domain means thousands of wasted queries.

Different values for well-known mailbox providers and for the asterisk are our rule. From the manual here come the 1m default, the advice to keep it smaller than the usual step and the fact that it also applies in backoff mode.
Example configuration
# a well-known mailbox provider: a DNS failure is almost certainly a matter of minutes
<domain gmail.com>
    retry-after 30m
    retry-after-dns-error 30s</domain>

# everything else: the domain may not exist at all
<domain *>
    retry-after-dns-error 5m</domain>
The order-of-magnitude difference here is intentional: a well-known mailbox provider’s domain definitely exists, an arbitrary recipient’s does not necessarily.
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 it equal to the usual step

§ 3.3.10.50

What it costsThe separation loses its meaning. A resolver failure lasting half a minute costs the queue half an hour of downtime — even though the receiver had no part in that delay.
How to spot itThe queue is stalled, the log has name resolution errors, and the next attempt follows the general schedule.
How to do it rightMake it noticeably shorter than the usual step: seconds or minutes.

Setting half a minute in the asterisk block

our experience

What it costsIn arbitrary domains a DNS error is often permanent: a typo in the address, a domain that lost its delegation. Half a minute turns into thousands of resolver queries per message, and you can hit its limits.
How to spot itThe resolver answers with temporary errors even to the node’s own queries.
How to do it rightKeep minutes in the asterisk block, and a short value only for domains whose existence is beyond doubt.
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
retry-after-dns-error <time-interval>
Values
a single time interval — a number and the letter d, h, m or s; a list is not accepted here, unlike the queue schedule
Default
1m § 3.3.10.50
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. The line has no twin with the backoff- prefix: the same interval applies when the queue is in backoff mode. It is picked up by pmta reload.
⇄

Related directives

3 relations

Depends on

bounce-after<domain>The overall deadline: the message will bounce by it, however many attempts to resolve the name the node makes. § 3.3.10.50

Can be replaced by

retry-after<domain>The usual retry step, which this line replaces when the queue stalls on name resolution. Its default is its own — a minute, not the neighbor’s value. § 3.3.10.50

Applies to

Backoff mode — the queue's second personalityThe only line of the retry family that works in backoff mode unchanged: it has no twin with the backoff- prefix. § 3.3.10.50

How to check on the node
The value is printed by the queue settings command; the name resolution errors themselves are visible in the log if their logging is enabled:
pmta show settings gmail.com/vmta1 | grep -i retry-after-dns-error
grep -i 'dns\|resolv' /var/log/pmta/pmta.log | tail -20
The Hub does not yet collect DNS errors by node: a queue stalled on name resolution looks the same in telemetry as one stalled on a receiver refusal.
◇

What else to read

3 articles

◇How the policy for a receiver is assembledSettings are assembled from the most general pattern to the most precise; the order of blocks in the file means nothing.◇Backoff mode — the queue's second personalityA queue that a receiver has started refusing switches to a parallel set of limits, retries and routes — ten directives that act only in this mode.◇Reputation monitoring inside the nodeThe engine itself watches the receiving servers’ replies and changes the queue mode on a pattern match — a reaction within the connection, not through telemetry.

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
Troubleshoot deliverability · Tune the pace for a provider
Neighboring settings of the block <domain>:bounce-afterretry-afterbackoff-retry-afterbackoff-to-normal-afterbackoff-upon-all-sources-disabledAll 135 directives of the block →