Demo
Demo

Knowledge base

PMTA knowledge base›Block <domain>›Directive§ 3.3.10.108.2

require-starttls

<domain>set by the Hub

Whether to give up on delivery if encryption could not be established
in the configuration this is a linerequire-starttls falseinside the block <domain>
The same name 1:<domain><source>— some of them are other settings, some are the same one
Encryption is mandatory — or the message will not go out

The line makes sense only with use-starttls enabled. It answers the question of what to do when encryption could not be established: the receiver did not offer it or the negotiation failed.

The default is false, that is, send in plain text. This is a reasonable default for the world at large and a wrong one for large receivers: they always have STARTTLS, and its absence means not “an old server” but something wrong with the connection.

true is a decision not to deliver. The node drops the connection, the message stays in the queue and goes out on the regular retry schedule. If the receiver has no encryption at all, the message will eventually bounce on expiry.

The main trap is setting true in <domain *>. This makes any receiver without STARTTLS undeliverable. Small corporate mail servers without encryption still exist, and messages to them will pile up in the queue until they bounce on expiry.
What the Hub does. It writes yes in the blocks of fourteen large receivers — Mail.ru, Yandex, Gmail and the rest: large ones always have STARTTLS, and unencrypted delivery there means a malfunction, not compatibility. In the general <domain *> it is no: encryption when possible (use-starttls), and whoever requires it declares that themselves through MTA-STS. Until Sep 15, 2026 the requirement was in the general block too, and a receiver without encryption did not get messages from the node.
Recommended values

The difference between the values is the difference between two kinds of losses:

Value What you lose For whom
no (default) confidentiality of some messages everyone except large receivers
yes delivery to those without encryption large receivers, where STARTTLS is always present

The rule is simple: mandatory encryption is enabled where the absence of encryption is a sign of a malfunction, not a trait of the receiver.

The false default and dropping the connection instead of sending come from the manual (§ 3.3.10.108.2). The “only for large receivers” rule is ours, from the policy template.
Example configuration
# mandatory encryption — only where it is certain to exist
<domain $mailru>
    use-starttls yes
    require-starttls yes</domain>
The line sits in a specific receiver’s block, not in <domain *>. A message that could not be encrypted will stay in the queue and be retried on the regular schedule.
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▶

Putting the requirement in the common recipient block

our experience

What it costsAny receiver without STARTTLS becomes unreachable. Messages pile up in the queue and bounce on expiry — that is, they are lost, but not right away, only after several days.
How to spot itQueues to small corporate domains grow; bounces arrive in a batch after several days.
How to do it rightKeep the line only in large receivers’ blocks. Leave the common block at the default.

Setting the requirement with encryption turned off

§ 3.3.10.108.2

What it costsThe line makes sense only together with use-starttls. With encryption turned off it does nothing — and creates the impression that protection is configured.
How to spot itThe requirement is in the configuration, while in accounting all messages have an empty protocol version field.
How to do it rightCheck whether use-starttls is turned off in a more specific recipient block or at the sending address level.
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
require-starttls <boolean>
Values
yes | no | true | false
Default
false § 3.3.10.108.2
Applying
reload, no restart needed
Queue
will not touch what is already queued
Where to write it
<domain>
How many times
once in the block
Everything here comes from the manual, with the section.
Inheritance
The directive lives in <domain> and merges by the usual rule for recipient blocks: the most precise match by receiver name wins. Hence the technique: the common block is left without it, and the requirement is enabled pointwise. The same three levels apply by sending address — node, <virtual-mta-pool>, <virtual-mta>.
⇄

Related directives

2 relations

Does not work without

use-starttls<domain>Works only with encryption enabled: without it there is nothing to require. § 3.3.10.108.2

Same name in other blocks

require-starttls<source>A namesake on the other side: that one is about the node receiving mail, this one is about sending. § 3.3.7.14

Referenced from

smtp-tls-ca-file<domain>Mandatory encryption decides what a failed verification turns into: a temporary refusal or sending in plain text. § 3.3.10.108.14

How to check on the node
The consequences are visible in the queue: messages that could not be encrypted stay in it:
pmta show queues | head -20
A growing queue to one receiver together with an empty protocol version field in accounting is exactly the requirement at work. The reason the negotiation failed is logged when log-tls is enabled.
◇

What else to read

3 articles

◇Submission over HTTPS on its own listener, modeled on SparkPostA separate entry point: its own listener with a certificate, its own keys and a reserved source name through which the usual submission settings apply to such mail.◇The receiver declares an encryption requirement on its websiteThe node fetches the recipient domain’s policy over HTTPS and, if it is in enforce mode, delivers only when the MX matches, the connection is encrypted and the certificate is verified.◇The receiver declares an encryption requirement in its DNS zoneThe node looks at the recipient domain’s DANE records and, if STARTTLS is required, sends only over an encrypted channel with a certificate verified by fingerprint.

In the Hub
Value
The Hub picks it itself — pace, warm-up stage, metrics
Cost of a mistake
reversible: harms only while it is set
Scenarios
Connection encryption
Neighboring settings of the block <domain>:smtp-tls-min-versionuse-daneuse-mta-stsuse-starttlssmtp-tls-ca-fileAll 135 directives of the block →