Skip to content

set_mta_sts_enabled

kumo.dns.set_mta_sts_enabled(ENABLED)
Since: Dev Builds Only

The functionality described in this section requires a dev build of KumoMTA. You can obtain a dev build by following the instructions in the Installation section.

Controls whether MX resolution consults MTA-STS policies. ENABLED is a boolean. The default value is true.

kumo.on('pre_init', function()
  kumo.dns.set_mta_sts_enabled(true)
end)

This option controls whether MTA-STS influences the site_name for a domain. When enabled, the MTA-STS policy published by a destination domain is evaluated against that domain's own MX records as part of resolving its site, before several domains that share the same MX records are rolled up (and thus before we know the egress path name). This is distinct from the per-egress-path enable_mta_sts option, which governs whether a resolved policy is allowed to raise the connection's TLS posture. In short:

  • kumo.dns.set_mta_sts_enabled — do we query MTA-STS records and allow them to modify the site_name?
  • enable_mta_sts (egress path) — do we let a resolved policy require TLS?

Why this is a global option

MTA-STS policy is a property of the destination routing domain, but several routing domains that share the same set of MX records are rolled up into a single ready queue keyed by their shared site_name. Evaluating the policy during resolution — before that rollup, and thus before we know the egress path name — keeps each domain's policy scoped to its own resolution, so a misconfigured domain cannot affect other domains sharing the same MX hosts.

How MTA-STS influences the site_name

The effect on the site_name depends on the policy that the destination domain publishes:

  • No MTA-STS policy (the common case): resolution is unaffected and the site_name is derived from the MX records as usual.

  • A policy whose allowed MX patterns cover all of the domain's MX hosts (a correctly specified policy): resolution is unaffected and the site_name is unchanged. The policy's TLS requirement may still apply on egress paths that opt in via enable_mta_sts.

  • A policy that covers only some of the MX hosts: the disallowed hosts are removed during resolution, so the site_name reflects only the permitted hosts. Such a domain rolls up only with other domains that resolve to the same permitted set.

  • A policy that matches none of the domain's MX hosts (a misconfiguration): the domain is treated as undeliverable. It fails to resolve and self-isolates, rather than joining the shared site used by other domains with the same MX records.

For example, if random-domain-example.com shares iCloud's MX records:

$ dig +short mx random-domain-example.com
10 mx01.mail.icloud.com.
10 mx02.mail.icloud.com.

but publishes an MTA-STS policy that can never match those hosts:

$ curl https://mta-sts.random-domain-example.com/.well-known/mta-sts.txt
version: STSv1
mode: enforce
mx: *.mx.cloudflare.net
max_age: 86400

then resolution fails with a transient error and its messages are delayed (and ultimately expire per your retry schedule). The delivery attempt produces a TransientFailure log record whose response is:

451 4.4.4 failed to resolve queue random-domain-example.com: MTA-STS enforce policy for random-domain-example.com permits none of its MX hosts ["mx01.mail.icloud.com.", "mx02.mail.icloud.com."]; allowed mx patterns: ["*.mx.cloudflare.net"]. The destination is undeliverable until its MTA-STS policy is corrected.

This is intentional and correct: the destination's published policy says its mail must not be delivered to those hosts. The right fix is for the destination domain to correct its broken MTA-STS policy. Forcing delivery anyway deliberately ignores a published security policy.

If a particular domain is important enough that you want to deliver to it despite a broken policy, you can route it through an explicit mx_list in get_queue_config. Configuring an mx_list bypasses MailExchanger resolution entirely and places the domain in its own dedicated queue:

kumo.on('get_queue_config', function(domain, tenant, campaign)
  if domain == 'random-domain-example.com' then
    -- Look up a CLEAN domain that shares the same MX records (e.g. the
    -- provider's canonical domain). Do NOT look up the broken domain
    -- itself -- it would fail to resolve for the same reason.
    local mx = kumo.dns.lookup_mx 'icloud.com'
    return kumo.make_queue_config {
      protocol = {
        smtp = {
          mx_list = mx.hosts,
        },
      },
    }
  end
  -- ...normal config...
end)