Skip to content

lookup_mx

kumo.dns.lookup_mx(DOMAIN, OPT_RESOLVER_NAME)

Resolve the MX information for the requested DOMAIN.

Raises an error if the domain doesn't exist.

Returns a lua table with the structure shown in the example below.

DNS results are cached according to the TTL specified by the DNS record itself.

This example shows the gmail.com MX information. At the time of writing, the DNS information looks like this:

$ dig +nocomments mx gmail.com.

; <<>> DiG 9.18.12 <<>> +nocomments mx gmail.com.
;; global options: +cmd
;gmail.com.                     IN      MX
gmail.com.              1620    IN      MX      30 alt3.gmail-smtp-in.l.google.com.
gmail.com.              1620    IN      MX      40 alt4.gmail-smtp-in.l.google.com.
gmail.com.              1620    IN      MX      5 gmail-smtp-in.l.google.com.
gmail.com.              1620    IN      MX      10 alt1.gmail-smtp-in.l.google.com.
gmail.com.              1620    IN      MX      20 alt2.gmail-smtp-in.l.google.com.
;; Query time: 0 msec
;; SERVER: 127.0.0.53#53(127.0.0.53) (UDP)
;; WHEN: Wed Mar 15 09:24:03 MST 2023
;; MSG SIZE  rcvd: 161

-- Query the gmail mx
local gmail_mx = kumo.dns.lookup_mx 'gmail.com'

-- This is what we expect it to look like
local example = {
  by_pref = {
    -- Each preference level has a sorted list of hosts
    -- at that level
    [5] = {
      'gmail-smtp-in.l.google.com.',
    },
    [10] = {
      'alt1.gmail-smtp-in.l.google.com.',
    },
    [20] = {
      'alt2.gmail-smtp-in.l.google.com.',
    },
    [30] = {
      'alt3.gmail-smtp-in.l.google.com.',
    },
    [40] = {
      'alt4.gmail-smtp-in.l.google.com.',
    },
  },

  -- The site name represents the hostname/port set, independent of preferences
  site_name = '(alt1|alt2|alt3|alt4)?.gmail-smtp-in.l.google.com',

  -- The FQDN that was resolved
  domain_name = 'gmail.com.',

  -- The flattened set of hosts in preference order
  hosts = {
    'gmail-smtp-in.l.google.com.',
    'alt1.gmail-smtp-in.l.google.com.',
    'alt2.gmail-smtp-in.l.google.com.',
    'alt3.gmail-smtp-in.l.google.com.',
    'alt4.gmail-smtp-in.l.google.com.',
  },

  -- true if the domain is a literal IPv4 or IPv6 address such as
  -- `[10.0.0.1]` or `[IPv6:::1]`
  is_domain_literal = false,
  -- true if the hosts are mx records
  is_mx = true,

  -- The applicable MTA-STS policy mode: 'None', 'Testing' or 'Enforce'
  -- (*Since: Version 2026.09.22-a276d4a8*)
  mta_sts = 'None',
}

assert(gmail_mx == example)

The site_name field identifies the destination group used for ready queues and traffic shaping. See Site Names for its meaning and sharing behavior.

Named resolvers

Since: Version 2026.09.22-a276d4a8

The functionality described in this section requires version 2026.09.22-a276d4a8 of KumoMTA, or a more recent version.

The optional OPT_RESOLVER_NAME parameter names an alternate resolver defined via define_resolver. When omitted, the default resolver is used.

local kumo = require 'kumo'

kumo.dns.define_resolver('my_resolver', {
  Test = {
    zones = {
      [[
$ORIGIN example.com.
@       600  IN MX 2 two.example.com.
                MX 1 one.example.com.
]],
    },
  },
})

local list = kumo.dns.lookup_mx('example.com', 'my_resolver')