Knowledge base
default-virtual-mta<source>criticalset by the HubDirectiveApplies when the stream has not been chosen by anything higher up — a header, a rule or a merge variable.domain-key<virtual-mta>criticalset by the HubDirectiveStream keys are stronger than general ones: when both levels match, these win.host-name<virtual-mta>criticalDirectiveThe same directive written inside a sending address; it overrides the node’s general name but yields to the name tied to the address itself.process-x-virtual-mta<source>criticalset by the HubDirectiveA permission for the source — with it the header selects the stream and is stripped before delivery; without it the header does nothing and travels to the recipient.smtp-source-host<virtual-mta>criticalset by the HubDirectiveThe same directive written inside a sending address — it is what makes that address a separate sending identity.virtual-mta<virtual-mta-pool>criticalset by the HubDirectiveThe line lists a sending address in a pool; without a number the members are used round-robin, with a number — in the given proportion, and the shares must add up to 100.auto-mx-rollupGlobalDirectiveOne line instead of a list: the node groups the domains itself and makes up the queue name itself.backoff-reroute-to-virtual-mta<domain>set by the HubDirectiveThe only one in the family that does not slow down but moves: messages leave from another address while the queue is in backoff mode.domain<virtual-mta-pool>DirectiveRules for a receiver written inside a pool are inherited by each of its members; a member’s own block overrides them.domain-key<virtual-mta-pool>DirectiveA pool hands the declaration to each of its members — there is no such thing as a shared key for a pool.include-headers-from<virtual-mta>DirectiveThe same line as at the node level; set here, it does not replace the common one but adds to it.invalid-virtual-mta-fallbackGlobalDirectiveInstead of a refusal, the message leaves through the stream named here; it works only at submission and only if the refusal is turned off in the source.max-smtp-msg-rate<virtual-mta-pool>DirectiveThe same setting written for a group: the pool hands the value out to its members rather than dividing it among them.max-smtp-out<virtual-mta-pool>DirectiveThe pool line goes to each member in full — it is not a reserve shared by the group.proxy-include-tlv<virtual-mta>set by the HubDirectiveAdds a field with the queue domain to the PROXY header; requires the second protocol version.proxy-protocol<virtual-mta>set by the HubDirectiveThe HAProxy header version, 1 or 2; the default is the first.queue-to<domain>DirectiveWritten in the block of each domain in the group: you set the shared queue name, the node does not derive it.reject-invalid-virtual-mta<source>DirectiveThe default is to reject; this same default quietly cancels the fallback stream until it is turned off here.reroute-to-virtual-mta<domain>DirectiveThe queue stays the same; what changes is the second half of its name — the address messages leave from.smtp-hosts<domain>DirectiveA list of hosts with preference levels, ports and addresses — or an instruction to take another domain’s MX.smtp-proxy-source-host<virtual-mta>set by the HubDirectiveThe same directive written inside a sending address; it replaces the node’s common setting and forbids the regular form and use-proxy in the same block.suppression-lists<virtual-mta-pool>DirectiveThe same line as for a sending address, written a level higher — every pool member gets it.use-proxy<virtual-mta>DirectiveA list of proxy blocks in backup order; the second is used only when the first did not respond.aliasGlobalDirectiveDeclares an address whose mail goes to one or more other addresses; the short form applies to all local names of the node.allow-cancel-during-transfer<domain>DirectiveThe default allows it — for a fast service shutdown; turning it off protects against duplicates but makes the node stop more slowly.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.auth-username<domain>DirectiveOne of the two lines that enable outgoing authentication: either of them being non-empty is enough.command<domain>DirectiveMandatory for a pipe queue; substitutions with message properties are expanded in the line.connect-timeout<domain>DirectiveThe first timeout of the conversation: things have not yet reached the greeting.disable-mx-rollup<domain>DirectiveTurns off both kinds of combining for the domain at once — both the manual list and the automatic one.file-destination<domain>DirectiveA path with substitutions: the date, domain and recipient can be inserted right into the name.file-format<domain>DirectiveA file per message, a file per message with envelope addresses, or a shared mbox mailbox.header<pattern-list>DirectiveThe only rule with a parameter — first the header name, then the pattern; the entire header content is matched, including spaces and line breaks.include-headers-from<virtual-mta-pool>DirectiveThe same line written one level up; every pool member gets it.mail-from<pattern-list>set by the HubDirectiveMatches the address from SMTP MAIL FROM — where bounces are returned — not the From address the recipient sees.max-errors-per-connection<domain>set by the HubDirectiveThe default is no limit: the connection lives on, however many recipient refusals pile up on it.max-smtp-data-volume-rate<virtual-mta-pool>DirectiveThe line is written once, but each member applies its own copy — the total volume is a multiple of the number of addresses.rcpt-to<pattern-list>DirectiveMatches the address from SMTP RCPT TO; with several recipients the stream of the first match applies to the whole message.retry-upon-new-mail<domain>DirectiveBypasses the retry schedule: every new message in the queue schedules an attempt immediately.rewrite-list<virtual-mta-pool>DirectiveThe same line as for a sending address, written a level higher — every pool member gets it.smtp-421-means-mx-unavailable<domain>set by the HubDirectiveThe vendor default is to stay on the same connection; enabling it moves the queue to the receiver’s backup server.smtp-data-termination-timeout<domain>DirectiveThe last wait of the conversation — and the most dangerous one: shorten it and you get duplicates.type<domain>DirectiveOne line that switches the queue between five delivery methods.verp-default<domain>DirectiveThe same enabling, but targeted: only for messages to this domain.allow-empty-x-virtual-mta<source>DirectiveWith this line a message with an empty header is accepted and leaves via the default stream; without it this is an invalid stream and a rejection.data-send-timeout<domain>DirectiveThe third wait of the conversation; the manual reminds: less than three minutes violates the mail standard.default-smtp-port<domain>DirectiveUsually 25; a change is needed where sending addresses are told apart by destination port.dummy-smtp-has-chunkingGlobalDirectiveThe default is not to announce it, and then the run uses a different transfer method than production mail will.dummy-smtp-has-pipeliningGlobalDirectiveOf the three lines in the set, this one affects the figure the most: without pipelining the conversation is several times longer.dummy-smtp-has-verpGlobalDirectiveNeeded exactly when mail with unique return addresses is run.ignore-8bitmime<domain>DirectiveA workaround for a known incompatibility: the external gateway accepts 8BITMIME, while the internal one behind it does not.ignore-chunking<domain>DirectiveA debugging switch: returns the transfer to the ordinary DATA command.ignore-dsn<domain>DirectiveCancels the delivery report requests the message carries from submission.ignore-pipelining<domain>DirectiveThe second debugging switch: commands go one at a time, with a reply to each.pix-bug-workaround<domain>DirectiveOn by default: a workaround for a known fault that causes messages to be duplicated.retain-x-virtual-mta<source>DirectiveThe default is to remove it; a header left in place carries internal stream names to the recipient.smtp-greeting-timeout<domain>DirectiveThe second wait of the conversation: there is a connection, the receiver is silent.track-jobs<domain>DirectiveEnables counting jobs per receiver and showing them on its page in the web monitor; off by default.route<domain>deprecatedDirectiveThe same mechanism under an old name: the manual gives it word for word the same description and asks you to use the new one.How the policy for a receiver is assembledcriticalMechanismSettings are assembled from the most general pattern to the most precise; the order of blocks in the file means nothing.The sending address — what it is made ofcriticalMechanismA named set of everything that is a property of the address: which IP the message leaves from, how the node introduces itself, what it signs with and how fast it sends.A name, an address and a greeting name — what a sending address consists ofcriticalMechanismThe definition is small, and two of its properties are easy to miss — omitting the address line silently inherits the node’s settings, and several addresses in one block rotate round-robin.The sender names the stream for each messagecriticalMechanismThe message carries the name of the stream it should be sent through — the choice is made by the submitting program, not by the node configuration.Six ways to choose a stream and the order among themcriticalMechanismA message’s stream is set by a merge variable, an API call, a header, a pattern rule, a listener and a source default — the manual lists them by precedence.The stream is named by a header, if the source is allowed to do socriticalMechanismA message header names the stream; the source the message was submitted from must have permission to process the header, and the header is stripped before delivery.A group of sending addresses with traffic sharesMechanismA named group of sending addresses; without shares messages are distributed in rotation, with shares in the given proportion, in steps of a tenth of a percent.The source default is the bottom rung, tied to whoever connectsMechanismA source block matching the sender’s address can name a default stream; it applies when no choice was made higher up the ladder.Hand a message to a webhook instead of a receiverMechanismThe queue sends the message as a POST request in the form of a JSON object; only a 2xx response counts as success.The stream is chosen by matching the envelope or a headerMechanismA named rule list matches the return address, the recipient or a header against regular expressions and assigns a stream on the first match.The node takes the stream whose address matches the connection addressMechanismThe source default accepts a reserved value instead of a stream name — then the node chooses the stream whose sending address matches the address the connection arrived at.Three pool rules the manual states directlyMechanismRotation-based distribution, inheritance of settings by members with the member’s own values overriding, and a namespace shared with sending addresses.The merge variable is the top rung, and it lives in the contentMechanismA service merge variable names the stream for the message and overrides all other selection methods on its submission path.Selecting a sending address by message contentMechanismRegular expressions are matched against a header, the return address or the recipient and select a sending address or assign a priority; lists can call each other.Five ways for a queue to hand off a messageMechanismA queue does not have to use SMTP: it can write to a file, run a program, call over HTTP or discard.The stream follows the address you connected toMechanismA named source block is attached to a listener and applies to everyone who connected to that address and port — so the sender picks the stream by picking the connection point.Replacing a recipient with one or several othersMechanismA message that arrives at a declared address is forwarded to others; expansion happens after the stream is chosen but before the message is queued into it.Handing a message to a program on the same nodeMechanismThe queue starts a program for each recipient and feeds the message to its input.How a message leaves the nodeMechanismAt the introduction level two paths are described: extended SMTP to the receiver or handing off to a local program; the receiver block adds three more.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.Change a sending address when messages are already queuedProcedureNew connections pick up the new definition right after the configuration reload; already open ones live out their lives on the old one.<domain>criticalConfiguration blockThe largest PowerMTA block and the main one among those the Hub generates itself.<virtual-mta>criticalConfiguration blockOne outgoing address with a greeting name and its own limits — the identity the receiving server sees.<pattern-list>Configuration blockRegular expressions matched against the sender, the recipient or a header to choose a sending address.<virtual-mta-pool>Configuration blockSeveral addresses addressed as one, with rotation among them.show settingscriticalCommandPrints the settings for a “receiving server and sending address” pair after all blocks have been merged.show domainsCommandPrints recipient domains, summing up all sending addresses for each.show vmta-settingsCommandPrints the settings of one sending address: name, limits, outbound addresses and signing keys.show vmtasCommandPrints the sending addresses: how many recipients, kilobytes and connections each has.show topdomainsCommandPrints recipient domains in descending order of load.Receiver policy inside an addressAPI endpointCreates, reads, extends and deletes receiver blocks inside a sending address created through the API.Sending addresses through the configuration APIAPI endpointCreates, reads, extends and deletes sending addresses with requests — as directive lines in JSON.Details of one receiverAPI endpointReturns the state of one recipient domain.Receivers with the largest queueAPI endpointReturns the recipient domains with the largest queue, summing all sending addresses for each.Sending addresses that have a queueAPI endpointReturns sending addresses that currently have mail in the queue, by number of recipients in descending order.The receiver refused the connectionError codeThe connection was not established: the remote host rejected it — either the mail server is down, or a filter is rejecting this particular sender.Refusal at the greetingError codeThe receiver returned an error at the very first step of the conversation — usually 4xx: busy, temporarily not accepting mail or not allowing this connection.The receiver went silent mid-conversationError codeThe connection is established, but the receiver stopped responding; the engine waits ten minutes, and this time is not configurable.The receiver dropped the connectionError codeThe remote host unexpectedly closed the connection — the server was shut down or crashed, or this is how it responded to the message content.Receivers summed across all sending addressesMonitor screenThe busiest recipient domains by number of recipients: volume, open connections and the last error, plus a form for selecting a specific domain.Sending addressesMonitor screenSending addresses that have mail in the queue: recipients, volume, connections; each has a top domains page.