Knowledge base

PMTA knowledge base›Configuration block§ 3.3.10

<domain>

critical

Settings applied to the queue for a specific receiver

The receiver’s queue and block merging

In PowerMTA a queue is a “receiver + sending address” pair. The <domain> block describes how to behave with a specific receiver: how many connections to open, how fast to send, how long to retry after a refusal, whether to sign messages and what to write to accounting.

There can be many blocks, and they add up. Values from matching blocks merge from general to specific: <domain *> sets the base, <domain yahoo.com> refines it for one receiver. The most precise match wins, and the order of lines in the file plays no part — a common mistake when reading someone else’s config.

Example configuration

# the base for all receivers
<domain *>
    max-smtp-out 15
    max-msg-rate 10/m
    retry-after 10m
</domain>

# a strict receiver gets its own
<domain yahoo.com>
    max-smtp-out 5
</domain>

yellow — — directive names, blue — blocks. They are highlighted the same way in the text of the card.

Block directives: 135

Signing 22

dkim-signcriticalset by the HubWhether to sign messages to this receiver check-spf-outboundWhether to check SPF of your own mail before sending to this receiver dkim-identityIn whose name the signature is made arc-identityOn whose behalf forwarding is sealed arc-signWhether to seal messages to this recipient with a forwarding signature dkim-add-body-limitWhether to sign only the beginning of the body, allowing appending at the bottom dkim-disallow-adding-headersWhich headers should break the signature if they are added after it dkim-headersWhich message headers are covered by the signature dkim-identity-fallbackA fallback signing name if no key was found for the main one arc-algorithmWhich algorithm the forwarding attestation is computed with arc-body-canonHow the message body is canonicalized before the forwarding attestation arc-expire-afterAfter how long the forwarding attestation stops being valid arc-headersWhich headers fall under the forwarding attestation arc-headers-canonHow headers are canonicalized before the forwarding attestation arc-identity-fallbackA fallback attestation identity if no key was found for the main one arc-oversigned-headersWhich headers should break the attestation if they are added after it dkim-add-timestampWhether to put the moment of its creation into the signature dkim-algorithmWhich algorithm the signature is computed with dkim-body-canonHow tolerant the signature is of edits to the message body in transit dkim-expire-afterAfter how long the signature stops being valid dkim-headers-canonHow tolerant the signature is of edits to headers in transit dkim-query-methodHow the recipient should look up the public key

Delivery 22

allow-cancel-during-transferWhether a connection may be cut while the message body is being transferred assume-delivery-upon-data-termination-timeoutset by the HubWhether to consider delivery successful when confirmation never arrived auth-usernameThe user name the node uses to identify itself to the receiver commandWhich program to run for messages of this queue connect-timeoutHow long to wait for an outgoing connection to be established file-destinationWhere the queue writes files — a directory or a file name file-formatIn what form the queue writes messages to files max-errors-per-connectionset by the HubHow many recipient errors break the connection retry-upon-new-mailWhether to try delivery right away when a new message arrives in a stalled queue smtp-421-means-mx-unavailableset by the HubWhether to move on to the next MX server after receiving a 421 response smtp-data-termination-timeoutHow long to wait for the final 250 after sending the message body typeHow this queue hands off messages — SMTP, a file, a program, a webhook or not at all verp-defaultWhether to write the recipient into the return address of messages to this recipient domain data-send-timeoutHow long to wait for the next piece of the message body to be sent default-smtp-portWhich port to connect to if no explicit server list is set ignore-8bitmimeDo not tell the receiver that the message body is eight-bit ignore-chunkingDo not use the CHUNKING extension even if the receiver announced it ignore-dsnDo not use the DSN extension even if the receiver announced it ignore-pipeliningDo not use the PIPELINING extension even if the receiver announced it pix-bug-workaroundWhether to send the final dot as a separate packet for the sake of old Cisco PIX firewalls smtp-greeting-timeoutHow long to wait for the 220 greeting after the connection is established track-jobsWhether to show the receiver’s jobs on the monitor page

Limits 20

max-msg-ratecriticalset by the HubHow fast to hand messages to this receiver max-smtp-outcriticalset by the HubHow many simultaneous connections the node keeps to one receiver backoff-max-msg-rateset by the HubWhich rate applies while the queue is in backoff backoff-max-smtp-outset by the HubHow many simultaneous connections to keep while the queue is in backoff max-connect-rateset by the HubHow fast to open new connections to this recipient domain source-ip-max-connect-rateHow fast to open connections from one outgoing address source-ip-max-msg-rateHow many recipients per interval to attempt from one outgoing address source-ip-max-smtp-outHow many simultaneous connections to this recipient domain from one outgoing address backoff-max-connect-rateWhat connection-opening rate applies while the queue is in backoff backoff-max-data-volume-rateWhat volume rate applies while the queue is in backoff connection-idle-timeoutset by the HubHow long to keep an idle connection open waiting for messages max-data-volume-rateset by the HubHow many bytes per interval, counting only successful deliveries max-msg-per-connectionset by the HubHow many messages go out over one connection before reconnecting max-rcpt-per-transactionHow many recipients are passed to the receiver in one transfer smtp-out-rampup-intervalset by the HubThe minimum pause before opening the next connection of this queue source-ip-max-data-volume-rateHow many bytes per interval are allowed from one outgoing address max-rcpt-per-messageA second name of the max-rcpt-per-transaction directive backoff-max-msg-per-hourdeprecatedBackoff mode rate — an obsolete form with a hard-wired hour max-msg-per-hourdeprecatedMessage rate to the receiver — a deprecated form with a hard-coded hour max-smtp-out-per-source-ipdeprecatedDeprecated in favor of source-ip-max-smtp-out

TLS 17

require-starttlsset by the HubWhether to give up on delivery if encryption could not be established smtp-tls-min-versionThe minimum TLS version toward the receiver use-daneWhether to check the receiver’s requirements from DANE records use-mta-stsset by the HubWhether to verify the connection against the receiver’s MTA-STS policy use-starttlsset by the HubWhether to encrypt the connection to this receiver smtp-client-certificateYour own certificate presented to the receiver smtp-tls-ca-fileThe list of trusted root certificates for verifying the receiver reuse-ssl-sessionset by the HubWhether to reuse the parameters of a previous TLS session log-tlsWhether to log the course of TLS negotiation smtp-tls-allow-sslv3deprecatedWhether to allow SSLv3 — the directive no longer has any effect smtp-tls-allow-tlsv1deprecatedWhether to allow TLS 1.0 — a deprecated switch smtp-tls-allow-tlsv1.1deprecatedWhether to allow TLS 1.1 — a deprecated switch smtp-tls-allow-tlsv1.2deprecatedWhether to allow TLS 1.2 — a deprecated switch smtp-tls-allow-tlsv1.3deprecatedWhether to allow TLS 1.3 — a deprecated switch smtp-tls-ciphersCipher set for versions up to and including TLS 1.2 smtp-tls-max-versionThe upper bound of the TLS version to the receiver smtp-tls-v1.3-ciphersuitesCipher set for TLS 1.3

Bounces 11

bounce-category-patternsWhich pattern list classifies this receiver’s bounces first bounce-upon-5xx-greetingset by the HubWhether to bounce all of a receiver’s mail at once on a 5xx reply to the greeting bounce-upon-no-mxset by the HubWhether to bounce right away when the receiver has no MX record smtp-553-means-invalid-mailboxset by the HubWhether to treat a bare 553 response as a sign of a nonexistent mailbox smtp-pattern-listset by the HubWhich pattern list is applied to this recipient domain’s responses bounce-upon-transfer-failureWhether to bounce a message if the connection broke while the body was being transferred bounce-upon-pix-transfer-failureThe same decision, but only when Cisco PIX is detected on the receiver’s side dsn-formatThe standard report format or only its text part notify-of-delay-everyHow often the node checks whether it is time to report a delay replace-smtp-421-service-responseWhether to replace the text of a 421 reply with a neutral one deliver-local-dsndeprecatedWhether to generate reports for mail accepted from this domain

Retries 10

bounce-aftercriticalset by the HubHow long to keep trying to deliver before bouncing a message retry-aftercriticalset by the HubAt what interval to retry delivery backoff-retry-afterset by the HubAt what intervals to retry after a refusal backoff-to-normal-afterset by the HubAfter what interval the queue returns to normal mode by itself backoff-to-normal-after-deliveryset by the HubWhether one successful delivery returns the queue to normal mode backoff-upon-all-sources-disabledWhether a queue goes into backoff when all its outgoing addresses are disabled proxy-retry-afterThe retry interval when a queue stalls because of a proxy failure reenable-source-ip-afterThe interval after which a disabled outgoing address returns to service retry-recipients-afterset by the HubHow long to wait before retrying a specific recipient retry-after-dns-errorset by the HubThe interval to retry at when the queue stalled because of a DNS error

Routing 6

backoff-reroute-to-virtual-mtaset by the HubWhich address or pool to move messages to while the queue is in backoff queue-toAn alternative queue name that combines domains with shared MX reroute-to-virtual-mtaMove this recipient domain’s messages to a different sending address smtp-hostsExplicit delivery servers instead of the usual DNS lookup disable-mx-rollupWhether to exclude this recipient from queue combining routedeprecatedDeprecated in favor of smtp-hosts

API 6

http-delivery-urlThe address to which the queue hands messages with a POST request http-delivery-extra-headersA file with additional request headers add-x-msys-api-headerWhether to add the header with parameters for SparkPost add-x-msys-api-header-metadataWhich message headers are copied into metadata for SparkPost sparkpost-ip-poolWhich SparkPost IP pool redirected messages are sent from sparkpost-sandboxSending from the SparkPost sandbox domain

Monitoring 4

backoff-notifyset by the HubWhom to notify when a queue enters or leaves backoff disabled-source-ip-notifyWhom to notify when an outgoing address is disabled or re-enabled for this receiver max-events-recordedHow many recent events are kept in memory for this domain track-recipient-eventsWhether to keep the last fifty recipient events in memory

Queue 4

queue-priorityThe priority of this queue when competing for connections allow-priority-interruptionWhether this queue’s connections may be interrupted for a higher-priority one allow-priority-interruption-during-transferInterrupt a connection at once or wait until it frees up delivery-prioritydeprecatedDelivery priority — a deprecated name

Accounting 3

disable-acct-recordscriticalWhich types of accounting records not to write for this queue discard-as-bounceWhether to count discarded messages as bounces or deliveries enable-tq-record-for-proxy-failureWhether to write proxy failures to accounting

Diagnostics 3

log-disabled-ipsWhether to log when and which outgoing addresses were disabled log-resolutionWhether to log name resolution for this receiver log-transfer-failuresset by the HubWhether to log breaks during transfer of the message body

Access 2

auth-passwordThe password the node uses to identify itself to the receiver use-unencrypted-plain-authWhether to allow PLAIN and LOGIN on an unencrypted connection

Message content 2

bcc-upon-deliveryThe address every delivered message is copied to macro-variables-preserve-caseWhether to preserve address case in substitutions

Proxies 1

enable-source-ip-limits-on-sending-ipcriticalWhether to count four limits per outgoing address rather than per local one

Warm-up 1

max-cold-virtual-mta-msgHow many of the day’s first messages to this recipient domain go out from a cold address

Core 1

includeInclude a settings file inside a recipient block

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.

⇄

Related entries

0 relations

Referenced from

remove-header<source>The prose of § 3.3.7.9 allows the same line for the recipient too, but the chapter 15 index does not know this position, and it has no entry of its own. § 3.3.7.9

◇

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.◇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.

In the Hub

Cost of a mistake: reversible: harms only while it is set
Scenarios: Tune the pace for a provider
Priority: critical