Demo
Demo

Knowledge base

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

bounce-after

<domain>criticalset by the Hub

How long to keep trying to deliver before bouncing a message
in the configuration this is a linebounce-after 4d12hinside the block <domain>
The deadline for a message’s life in the queue

The first of two alarm clocks that govern a deferred message. This one sets the deadline: a message older than the given interval is bounced — a non-delivery report (DSN) goes to the sender. The second, retry-after, sets the frequency: how often to try again until the deadline has passed. Neither makes sense on its own.

The countdown runs from the message’s submission, not from the last attempt. A message that has waited in the queue for three days because of a stubborn receiving server will bounce on schedule, even if that server has just started accepting.

The vendor default is 4d12h, four and a half days. For messages with a one-time code this is pointlessly long: a code delivered on the fourth day is worse than one never delivered. For a campaign it is an extra day of disk and queue for messages that almost certainly will not go out anymore.

The main trap. The deadline and the retry step are set separately, and they are easy to mismatch. With the vendor defaults 4d12h and 10m you get 648 attempts to a single receiver: the node knocks on a receiving server that has already said “later” six hundred-plus times. The opposite mistake is a long retry ladder under a short deadline: the far rungs never run even once, and the message bounces earlier.
What the Hub does. The receiver policy template has 3d — three days in all fifteen blocks: for fourteen large mailbox providers and in the general <domain *>, with a note that the vendor default is different. Next to it the Hub writes retry-after 30m: 144 attempts over the deadline instead of 648.
Recommended values

Count the pair, not one number. The deadline divided by the retry step gives the number of attempts. Three days with a half-hour step is 144 attempts; the same three days with the vendor default 10m is 432. The second number is no better than the first, only noisier for the receiving server.

Messages with an expiry date get hours, not days. A one-time code or a password reset link makes sense for the first few minutes. Such mail is sent through a separate VirtualMTA with its own <domain> inside and a short deadline.

Too short a deadline loses mail. A receiving server that holds greylisting for a day will bounce the whole campaign under a four-hour deadline — and it would have gone out.

The “divide the deadline by the step” rule and a separate VirtualMTA for messages with an expiry date are ours. From the manual here are the 4d12h default and the fact that a message older than the deadline is bounced with a DSN report.
Example configuration
# a large mailbox provider: three days and a half-hour step
<domain gmail.com>
    retry-after 30m
    bounce-after 3d</domain>

# messages with a one-time code live for an hour — a separate stream
<virtual-mta otp>
    <domain *>
        bounce-after 1h        retry-after 2m
    </domain>
</virtual-mta>
The same receiver can have two different deadlines — they are counted per “domain + VirtualMTA” pair, and the campaign does not overlap with the code mail.
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 ends3 mistakes▶

Leaving the vendor default together with the step default

§ 3.3.10.10

What it costs4d12h and 10m give 648 attempts to a single receiver. The receiving server sees a sender that does not hear refusals, and that is exactly the image that gets the rate throttled.
How to spot itThe log has hundreds of 4xx lines for one queue per day.
How to do it rightShorten the deadline to three days and increase the step to half an hour.

Keeping one deadline for all mail

our experience

What it costsThree days is just right for a campaign, but not for a message with a confirmation code. A shared deadline either drags dead mail along or cuts the campaign short.
How to spot itUsers receive confirmation codes a day after requesting them.
How to do it rightMove mail with an expiry date into a separate VirtualMTA and give it its own short deadline.

Shortening the deadline on a live queue

our experience

What it costsThe deadline is counted from the message’s submission, not from the configuration edit. After pmta reload, everything already older than the new deadline bounces at once — a batch of bounces within a minute.
How to spot itA spike of bounces right after the configuration reload.
How to do it rightBefore shortening, look at the queue’s age (pmta list –older-than=… for that queue) and shorten in steps.
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
bounce-after <time-interval>
Values
a time interval: a number and a letter — d days, h hours, m minutes, s seconds; a compound form is allowed, for example 4d12h
Default
4d12h § 3.3.10.10
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. A <domain> block can be nested inside <virtual-mta> or <virtual-mta-pool> — then the deadline applies only to messages of that stream. It is picked up by pmta reload; for messages already sitting in the queue the new deadline applies immediately — shortening it bounces everything already older than it.
⇄

Related directives

3 relations

Works together with

retry-after<domain>The second alarm clock of the same pair: this one sets the deadline, that one the step. The deadline divided by the step is the number of attempts. § 3.3.10.46

Can be replaced by

bounce-upon-no-mx<domain>A condition that bounces the message early, without waiting for the deadline. § 3.3.10.69

Affects

Backoff mode — the queue's second personalityBackoff mode slows down retries but does not extend the deadline: a queue in backoff keeps the same amount of time and gets fewer attempts. § 3.3.10.10

Referenced from

notify-of-delay-every<domain>The message lifetime and this interval together set the number of notifications per message. § 3.3.10.17proxy-retry-after<domain>The overall deadline: the message will bounce once it passes, no matter how many attempts the node makes to get through via the proxy. § 3.3.10.47backoff-retry-after<domain>The upper bound: the message bounces even if the retry schedule has not run out yet. § 3.3.10.48retry-recipients-after<domain>The overall deadline: the personal pause does not extend it; it only reduces the number of attempts a specific address gets. § 3.3.10.49retry-after-dns-error<domain>The overall deadline: the message will bounce by it, however many attempts to resolve the name the node makes. § 3.3.10.50bounce-upon-5xx-greeting<domain>With the line off, the reply is treated as temporary, and the boundary becomes the general deadline: attempts go on until it. § 3.3.10.70

How to check on the node
The queue settings command prints the effective deadline — it works on a “domain/vMTA” pair, not on a domain in general:
pmta show settings gmail.com/vmta1 | grep -i bounce-after
pmta list --queue=gmail.com/vmta1 --older-than=3d --maxitems=10
The second lists queue messages older than three days — with a 4d12h lifetime that is mail about to bounce. The Hub does not show message age on the node screen yet.
◇

What else to read

3 articles

◇Four value types the whole config is written inBoolean, domain pattern, regular expression and time interval — defined once in § 3.2 and then used by all directives.◇Two inbound report processors and what to do with themBounces by message and complaints are parsed by two identically structured blocks; each has its own address list and its own pair of decisions about the message’s fate.◇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.

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
Bounce classification · Tune the pace for a provider
Priority
critical
Neighboring settings of the block <domain>:retry-afterbackoff-to-normal-after-deliverybackoff-retry-afterbackoff-to-normal-afterbackoff-upon-all-sources-disabledAll 135 directives of the block →