Demo
Demo

Knowledge base

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

bounce-upon-transfer-failure

<domain>

Whether to bounce a message if the connection broke while the body was being transferred
in the configuration this is a linebounce-upon-transfer-failure falseinside the block <domain>
A choice between a duplicate and a loss

The connection broke not before sending and not after, but in the middle of the message transfer — the headers and part of the body have gone out, and there is no acceptance confirmation yet. The node does not know whether the message got through: the mail protocol does not report it.

The vendor default false chooses delivery. The message stays in the queue and is retried until the bounce-after deadline. If the receiver actually accepted it, the recipient will see two copies — and sometimes a truncated first one.

true chooses no duplicates. The message is bounced after the very first broken transfer. There will be no duplicate — but there will be no message either if the break happened on our side and the receiver got nothing. The protocol has no third option.

The main trap. There is no safe value here — there is a choice of which risk costs you more. For a mailing a duplicate is unpleasant but tolerable: the recipient will see the message twice. For a message with a one-time code or an invoice, a duplicate is worse: two codes, two invoices, two payment attempts. The decision is made by the content of the mail, not by the node’s settings.
What the Hub does. It does not write it — the vendor false stays. For a mailing this is the right choice: delivering matters more than avoiding a repeat. For transactional streams the value is worth setting by hand.
Recommended values

For a mailing — false. Losing a message costs more than a second copy in the mailbox.

For mail with money or codes — true. A second invoice or a second one-time code is more dangerous than an undelivered message, and such mail is sent through a separate stream anyway.

Look at how often breaks happen, not only at the value. If transfers break regularly, the problem is not this line: check the network, transfer timeouts and intermediate equipment.

The split by mail type is ours. From the manual here come the vendor default, the duplicate risk mechanics with a reference to RFC 1047 and the direct caveat that when it is enabled the recipient may not get the message at all.
Example configuration
# a mailing: delivering matters more than avoiding a repeat
<domain *>
    bounce-upon-transfer-failure false</domain>

# invoices and codes: a second copy is more dangerous than an undelivered message
<virtual-mta billing>
    <domain *>
        bounce-upon-transfer-failure true    </domain>
</virtual-mta>
The split by streams is the decision here: one value for all mail is always wrong for one of its parts.
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▶

Enabling it for all mail to fight duplicates

§ 3.3.10.72

What it costsEvery network break turns into a bounce. On an unstable channel a noticeable part of the mailing is lost, and the cause looks like a receiver problem.
How to spot itBounces with a diagnostic about a broken transfer while the receiver is alive.
How to do it rightKeep false for mailings, and enable it only where a duplicate really is more dangerous than a loss.

Treating an unstable network with this line

our experience

What it costsThe line does not reduce the number of breaks, it only changes their outcome. Regular transfer breaks are a sign of a network fault or timeouts that are too short, and a bounce setting does not cure that.
How to spot itBreaks continue at the same rate; only the look of the accounting records has changed.
How to do it rightDeal with the channel and transfer timeouts, and choose the value by mail type.
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-upon-transfer-failure <boolean>
Values
yes or no; true and false are accepted on a par with them
Default
false § 3.3.10.72
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 in <virtual-mta> — this is how a mailing is separated from mail where a duplicate is unacceptable. It is picked up by pmta reload.
⇄

Related directives

1 relation

Works together with

allow-cancel-during-transfer<domain>The second lever for the same risk: that one decides whether a transfer may be interrupted at our own will, this one — what to do with the message after someone else’s break. § 3.3.10.72

Referenced from

bounce-upon-pix-transfer-failure<domain>The general form of the same decision: this line narrows it down to one kind of equipment. § 3.3.10.71

How to check on the node
The value is printed by the queue settings command; transfer breaks themselves are logged as a separate line if their logging is enabled:
pmta show settings gmail.com/vmta1 | grep -i bounce-upon-transfer-failure
pmta show settings gmail.com/vmta1 | grep -i log-transfer-failures
The second line shows whether breaks are written to the log at all: with logging off they are not visible anywhere. The Hub does not collect transfer breaks.
◇

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
Cost of a mistake
reversible: harms only while it is set
Scenarios
Bounce classification · Tune the pace for a provider
Neighboring settings of the block <domain>:smtp-pattern-listsmtp-553-means-invalid-mailboxbounce-category-patternsbounce-upon-no-mxbounce-upon-5xx-greetingAll 135 directives of the block →