Knowledge base
bounce-category-patterns<domain>DirectivePuts your own reply parsing ahead of the general one — without changing whether the message bounced.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.deliver-unmatched-email<feedback-loop-processor>set by the HubDirectiveWhat to do with a message the processor did not recognize; delivers by default, and it is also the condition for forwarding.deliver-unmatched-email<bounce-processor>set by the HubDirectiveWhat to do with a message the processor did not recognize; delivers by default, and it is also the condition for forwarding.forward-unmatched-to<feedback-loop-processor>DirectiveThe address an unrecognized message goes to; the line is repeatable and requires delivery of unrecognized mail to be allowed.forward-unmatched-to<bounce-processor>DirectiveThe address an unrecognized message goes to; the line is repeatable and requires delivery of unrecognized mail to be allowed.hashed-address<address-list>DirectiveThe address is lowercased, hashed with SHA256 and encoded as BASE64URL; the engine hashes the address being checked and compares the hashes.smtp-553-means-invalid-mailbox<domain>set by the HubDirectiveA guess in place of what the receiver left unsaid — and whether the address ends up on the blocklist depends on it.smtp-pattern-list<domain>set by the HubDirectiveAttaches a named pattern list to connections with the recipient domain; it is used to parse its SMTP responses and assign actions.suppression-lists<virtual-mta>DirectiveThe same line as in a source, but here there is no choice — the message is always accepted, queued and bounced.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.address<address-list>set by the HubDirectiveAccepts three forms — a full address, a bare local part or a regular expression in slashes.address-file<address-list>DirectiveIncludes a file where each line holds a full address or a bare local part.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.deliver-matched-email<feedback-loop-processor>set by the HubDirectiveWhat to do with a recognized message after parsing: deliver it to the recipient or discard it; discard by default.deliver-matched-email<bounce-processor>set by the HubDirectiveWhat to do with a recognized message after parsing: deliver it to the recipient or discard it; discard by default.domain<address-list>DirectiveOne line instead of listing addresses — all recipients of this domain get on the list.forward-errors-to<feedback-loop-processor>DirectiveAn address for messages the processor could not parse; the line is repeatable.forward-errors-to<bounce-processor>DirectiveAn address for messages the processor could not parse; the line is repeatable.hashed-address-file<address-list>DirectiveIncludes a file where each line is the hash of a whole address; there is not a single readable address in the file.suppress-local-dsn<source>set by the HubDirectiveTurns off bounce, delay and delivery report messages for submission from this source; accounting records are written as usual.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.custom-dsn-from-headerGlobalDirectiveSets the report sender as a string without substitutions; a newer line with the same purpose can substitute values from the original message.dsn-failed-body-template-fromGlobalDirectiveThe path to the report body template file; nine values from the original message are substituted in it — from the node name to the receiver’s reply.dsn-failed-from-templateGlobalDirectiveSets the sender of the generated report with substitutions from the original message; an older line with the same purpose does not support substitutions.dsn-failed-subject-templateGlobalDirectiveSets the subject of the generated report with substitutions from the original message; the set of substitutions is shared with the body template.dsn-format<domain>DirectiveThe second value returns one part instead of the full report — the delivery status, as plain text — so that the report gets through mail filters that cut attachments.dsn-return-default<source>DirectiveThe default for the RET parameter, with which the sender asks to return the whole message or only the headers in the report; the plain-text format cancels this line.notify-of-delay-every<domain>DirectiveThe check interval for delay notifications the submitting side requested at submission; the value never turns them off for this receiver.replace-smtp-421-service-response<domain>DirectiveReplaces the text after the 421 code with “service unavailable”, so that addresses from someone else’s reply do not get into the bounce report; pattern-based parsing keeps working.deliver-email<feedback-loop-processor>deprecatedDirectiveOne line decided the fate of both recognized and unrecognized messages; replaced by two separate ones.deliver-email<bounce-processor>deprecatedDirectiveOne line decided the fate of both recognized and unrecognized messages; replaced by two separate ones.deliver-local-dsn<domain>deprecatedDirectiveDeprecated directive: it turned off report messages by sender domain; replaced by a setting in the source block.How the node responds to the receiving server's wordscriticalMechanismMatches SMTP replies against regular expressions and changes the queue mode on a match — the very trigger that all of the backoff mode machinery waits for.Two attachment points — and two different behaviorscriticalMechanismA list attached to a source rejects the recipient at submission or bounces the message later; attached to a sending address or pool, it always accepts and then bounces.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.Address lists — named and unnamedMechanismA list of addresses, domains, patterns or hashes; a named one is attached by directives such as suppression, an unnamed one lives inside an inbound mail 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.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.<bounce-processor>Configuration blockThe block enables parsing inbound messages for bounces; it catches them by a nested address list and writes accounting records of type rb.<feedback-loop-processor>Configuration blockThe block enables parsing inbound messages for complaints; it catches them by a nested address list and writes accounting records of type f.<smtp-pattern-list>Configuration blockPatterns matched against receiver responses — the very trigger that backoff mode reacts to.<address-list>Configuration blockA named list is attached by its name; an unnamed one lives inside a bounce or complaint processor and selects mail for parsing.<email-patterns>Configuration blockA block with pattern files, nested inside a bounce or complaint processor; it has two lines.Address lists through the configuration APIcriticalAPI endpointCreates, reads, extends and deletes address and domain lists — for suppression, for example — without editing files.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.