Knowledge base
bounce-after<domain>criticalset by the HubDirectiveUntil this point the message lives in the queue and takes up disk space.records<acct-file>criticalset by the HubDirectiveA list of eight possible accounting record types; the default is deliveries and local bounces.bounce-upon-5xx-greeting<domain>set by the HubDirectiveThe vendor default is yes, and one misconfigured server in the MX list is enough to burn the queue.bounce-upon-no-mx<domain>set by the HubDirectiveIt accepts more than yes and no: an interval gives the domain time during which the node can try the address directly.enable-tq-record-for-proxy-failure<domain>DirectiveRecords proxy connection failures in tq accounting records; off by default and ignored without this record type.html-edit-error-mode<signals>DirectiveRefuse delivery or send as is when HTML parsing failed; the default is to refuse.mail-from<rewrite-list>set by the HubDirectiveChanges the address from the SMTP MAIL FROM command — the one a bounce returns to and the one SPF checks; this rule does not touch the From header.reject-spf-check-fail<source>DirectiveThe most unambiguous of the three outcomes: the domain owner said that mail must not be sent from this address.reject-spf-check-permerror<source>DirectiveThe sender forbade nothing — it made a syntax mistake; the default rejects anyway.reject-spf-check-temperror<source>DirectiveThe only one of the three outcomes where the refusal is temporary: the sender is invited to retry.suppression-lists<source>DirectiveAttaches one or more named address lists; a recipient on a list is rejected at submission or bounced later, depending on how invalid recipients are accepted.verp-default<source>DirectiveEnabling on the submission side: it applies to everything submitted through this source.assume-delivery-upon-data-termination-timeout<domain>set by the HubDirectiveA bet that the message got through: there will be no duplicates, but no truth in accounting either.body-pattern-file<email-patterns>DirectiveA regular expression with named groups that pulls accounting fields out of the body of a non-standard report; the line is repeatable.bounce-upon-transfer-failure<domain>DirectiveA choice between the risk of a duplicate at the recipient and the risk of not delivering the message at all.disable-mx-rollup<domain>DirectiveTurns off both kinds of combining for the domain at once — both the manual list and the automatic one.pattern-list<source>set by the HubDirectiveAttaches a named rule list to the source; the list must be declared earlier in the file, and only one can be attached.retry-upon-new-mail<domain>DirectiveBypasses the retry schedule: every new message in the queue schedules an attempt immediately.verp-default<domain>DirectiveThe same enabling, but targeted: only for messages to this domain.bounce-upon-pix-transfer-failure<domain>DirectiveA narrow case of the general line: it fires if the receiver’s greeting contains at least ten asterisks.log-match-info<email-patterns>DirectiveWrites to the log the name of the pattern file that matched the parsed report; off by default.pix-bug-workaround<domain>DirectiveOn by default: a workaround for a known fault that causes messages to be duplicated.track-jobs<domain>DirectiveEnables counting jobs per receiver and showing them on its page in the web monitor; off by default.The bounce category in accounting — configurable, not vendor-fixedcriticalMechanismThe bounceCat string in every accounting record comes from a pattern list that can be extended with your own rules and your own category names.Parsing bounces that arrive as messagescriticalMechanismBounce reports that arrive as messages are parsed by a separate processor — and it runs before the complaint processor.Two inbound report processors and what to do with themMechanismBounces 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.What to do with an accepted messageMechanismWhat the node does with an accepted inbound message: forwards it, writes it to a file, discards it, passes it to a program or parses it as a bounce or complaint.The complaint format of one large receiverMechanismHotmail complaints do not come in standard ARF: for the engine to recognize them and record the recipient, you need the variant with an RFC attachment and the X-HmXmrOriginalRecipient header.The regular expression dialectMechanismConfiguration regular expressions are Perl-compatible, based on the PCRE library: that is how sending address selection, reply rules, bounce categories, address lists and signing headers are written.The second complaint report formatMechanismXARF complaints are JSON instead of ARF: the engine fills the main fields itself, and the rest are extracted with the xarf.<path> form.Reports the engine does not understand by itselfMechanismReceivers that send bounces and complaints in a non-standard form are parsed with custom patterns; the extracted fields go into accounting on a par with the usual ones.Which outcomes produce a report — each recipient decidesMechanismFor each recipient separately a report on success, failure, delay, any combination of them or nothing is requested; the default is failure only.What to return in a bounce reportMechanismWhat to enclose in a bounce report: the whole message or only its headers.A return address with the recipient written into itMechanismThe bounce arrives at a unique address, and there is no need to parse its content.National alphabetsMechanismConfiguration files are UTF-8, so internationalized domains and addresses are written as is; a message with an internationalized address in the envelope goes out only if the receiver supports SMTPUTF8.Removing a sending address — and what happens to its queuecriticalProcedureThe definition is removed with an edit and a reload; messages still tied to the removed address bounce with their own code.<smtp-pattern-list>Configuration blockPatterns matched against receiver responses — the very trigger that backoff mode reacts to.Permanently bouncedcriticalAccounting recordThe recipient permanently did not receive the message — either the receiving server refused for good, or the node itself bounced the message when the deadline expired.Parsed bounce from outsideAccounting recordA bounce report email arrived at the configured processor and was parsed.The name lookup did not complete — and no conclusion is drawnError codeThe name service query failed, usually on timeout; the engine deliberately does not bounce the message on such a failure.The receiver is misconfiguredError codeThe bounce is caused by the remote side’s configuration, not ours.Connection problemError codeThe connection to the receiver failed or was broken.The domain does not existError codeThe recipient’s domain was not found or does not exist. The bounce is about the right-hand part of the address, not the left.The address does not existError codeThe receiver said it has no such recipient. The most unambiguous of bounces: it is about the address, not about the message, not about us and not about the network.Held back over contentError codeRejected because of what is inside the message: a link, an attachment, markup.The mailbox is disabled or expiredError codeThe mailbox once existed, but it was closed, frozen or expired. Formally the address exists, practically it is dead.A problem with the sender domainError codeThe bounce is caused by our domain’s records: they are missing or wrong.The bounce deadline has expiredError codeThe message was not delivered within the allotted time and was bounced on deadline.The host connected and stays silentError codeThe connection was established, no reply followed.OtherError codeA bounce that did not fit any category.Rejected by the receiver's rulesError codeThe receiver refused by its own rules — not over content and not over the address.A breach of the conversation orderError codeA syntax error or a wrong command sequence.The mailbox is fullError codeThe recipient has run out of space. The mailbox is alive, there is just nowhere to put the message.The receiver refused to relayError codeThe remote server refused to accept the message for further relaying.A route could not be builtError codeMail to the recipient’s domain cannot be routed.Held back as spamError codeThe message was rejected on spam signals. The bounce is not about the address — it is about us and about the content.A virus was foundError codeThe receiver considered an attachment or a link malicious.Bounces according to the serviceMonitor screenThe SparkPost Signals report on bounces for a selected period — in SparkPost’s classification, not in the engine’s categories.