Demo
Demo

Knowledge base

PMTA knowledge base›Block <pattern-list>›Directive§ 3.3.14.3

rcpt-to

<pattern-list>

A rule on the recipient address that selects a stream or priority
in the configuration this is a linercpt-toinside the block <pattern-list>
Selecting a stream by recipient — with a caveat you need to know

Matches the recipient address from the SMTP RCPT TO command. The form is the same as for the list’s other rules: a pattern in slashes and a result — virtual-mta=name, recipient-priority=N or call-to:.

The main peculiarity is stated by the manual directly. If a message has several recipients and several of them match rules, the stream of the first match applies to the whole message — including the recipients that did not match that rule. The vendor adds that this behavior may change in the future and advises using the rule only for messages with a single recipient.

Where it fits. Recipient priority is the most honest case: recipient-priority=90 on password recovery messages lifts them above the mailing, and the question of stream selection does not come up.

The main trap. A recipient rule in a mailing does not behave the way it reads. “A separate stream for Yahoo recipients” on a message with a hundred addresses means that all hundred will go out through that stream if the Yahoo address happened to be the first match. Splitting by recipient works only with one recipient per message.
What the Hub does. It does not write it. Stream selection is built on the sender’s domain — with a rule on the return address — and splitting by recipient is handled in the Hub by <domain> blocks inside the stream: there it applies to the queue, not to the message, and has no caveat about several recipients.
Recommended values

When a recipient rule really fits:

Case Suitable Why
priority of transactional messages yes the priority is set for the recipient, not the message
messages with a single recipient yes the caveat does not apply
a mailing to many addresses no the stream of the first match will apply to everyone
splitting by mailbox provider no, use <domain> recipient rules are a property of the queue

Patterns are written by the same rules as the others: dots are escaped, and the end of the domain is anchored.

The caveat about several recipients and the vendor’s advice to apply the rule only to messages with a single recipient come from the manual. The breakdown by cases is ours.
Example configuration
# a safe use: priority, not stream selection
<pattern-list mta-hub-senders>
    mail-from /@shop\.example\.com$/ virtual-mta=shop-example-com
    rcpt-to /^password-reset@/ recipient-priority=90</pattern-list>
The priority is set for the recipient, so the caveat about several recipients does not get in the way here. The scale is 0–100 with a default of 50, so 90 means “ahead of the regular mailing,” not “as urgent as possible.”
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▶

Splitting a mailing by recipients

§ 3.3.14.3

What it costsThe stream of the first matching recipient applies to the whole message. Part of the mailing goes out from an address meant for a completely different mailbox provider, and in accounting it looks like a routing error.
How to spot itRecipients of one domain carry the name of a stream meant for another.
How to do it rightSplit by sender — with a rule on the return address. Set recipient rules with <domain> blocks inside the stream.

Writing a pattern without anchors

§ 3.3.14

What it costs/customer/ will match both customer@ourshop.com and noreply@customer-support.example.net. Messages the rule was not written for fall under it.
How to spot itThe stream gets recipients that were not assigned to it.
How to do it rightAnchor the pattern and escape the dots — like /^stud.*@somesite\.com$/ in the manual’s example.
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
rcpt-to <regex-rule>
Values
a pattern in slashes and a result — virtual-mta=name, recipient-priority=N or call-to:name
Applying
reload, no restart needed
Queue
will not touch what is already queued
Where to write it
<pattern-list>
How many times
may be repeated
Everything here comes from the manual, with the section.
Inheritance
The rule has no inheritance: it acts inside its <pattern-list> block. What is inherited is the reference to the list — pattern-list is written in <source> and merges by the source rule, with a narrow block replacing the list entirely.
⇄

Related directives

2 relations

Does not work without

pattern-list<source>The rule works only if the list is plugged into a source, and the list is declared in the file above it. § 3.3.7.42

Applies to

Selecting a sending address by message contentOne of the three kinds of rules: the return address, the recipient or a header is matched. § 3.3.14.3

Referenced from

The regular expression dialectThe directive that enables this mechanism. § 3.3.14

How to check on the node
Check it on a message with several recipients — that is exactly where the rule behaves non-obviously:
pmtaacctfind --output csv[rcpt,vmta,jobId] /var/log/pmta/acct-*.csv | head -30
If messages of one job have the same name in the vmta field while the recipients differ and not all of them match the rule, that is the very caveat. Not a configuration error but documented behavior.
◇

What else to read

3 articles

◇Headers the sender uses to control deliverySix control headers let the submitting side choose a stream, tag a message with a job, set signing options and the key, the envelope identifier and the schedule; each is allowed separately and per source.◇Selecting a sending address by message contentRegular 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.◇How a message gets into the engineSix described submission methods: extended SMTP, four language bindings and a directory the node watches on disk.

In the Hub
Cost of a mistake
reversible: harms only while it is set
Scenarios
Sending address rotation · Connect a sending platform
Neighboring settings of the block <pattern-list>:headermail-fromAll 3 directives of the block →