TESTMXLOOKUP(1)

💖 TESTMXLOOKUP 💖

okay bestie, gather round, because testmxlookup is the little Courier utility that goes and snoops on a domain's mail servers for you 👑 it's the diagnosis queen, fr fr.

---

✨ NAME ✨

testmxlookup — look up mail servers for a domain 🦋

---

🌸 SYNOPSIS 🌸

testmxlookup [@ip-address | --dnssec | --udpsize n | --sts |
             --sts-override=mode | --sts-purge] {domain}

testmxlookup {--sts-expire | --sts-cache-disable | --sts-cache-enable |
             --sts-cache-enable=size}

---

💅 DESCRIPTION 💅

so what does she actually do? testmxlookup reports the names and IP addresses of the mail servers that receive mail for the domain, and also the domain's published STS policy. literally built for diagnosing mail delivery problems, and she ate 💖

here's the vibe: testmxlookup sends a DNS MX query for the specified domain, followed by A/AAAA queries, if needed. then testmxlookup lists the hostname and the IP address of every mail server, and its MX priority. if the domain publishes a strict transport security (STS) policy, that policy status comes first, before the mail server list. main character energy ✨

😭 DIAGNOSTICS 😭

• “Hard error” — this means the domain does not exist, or it does not have any mail servers. not a vibe.
• “Soft error” — this means a temporary error condition (usually a network failure of some sorts, or the local DNS server is down). give it a sec bestie.
• “STS: testing” or “STS: enforcing” sitting right before the list of mail servers — that means the domain publishes an STS policy 👀
• “ERROR: STS Policy verification failed” showing up after an individual mail server — that means that mail server's name does not meet the domain's STS policy. problematic.
• “STS: testing” or “STS: enforcing” all by itself, with no further messages, means all the listed mail servers comply with the listed STS policy 🎀 and ngl, if you're trying to install your own STS policy, this is literally the simplest way to check whether it's valid. periodt.

🌈 OPTIONS 🌈

• @ip-address — specify the DNS server's IP address, i.e. where to send the DNS query to, overriding the default DNS server addresses read from /etc/resolv.conf. and note: ip-address must be a literal, numeric, IP address. no names, no games 💅
• --dnssec — turn on the DNSSEC extension. if the DNS server has DNSSEC enabled, and the specified domain's DNS records are signed, then the list of IP addresses gets a “(DNSSEC)” suffix slapped on the end, indicating a signed response ✨ this one is a diagnostic option. also heads up: older DNS servers may respond with an error to a DNSSEC query. rude of them.
• --udpsize n — say that n is the largest UDP packet size that the DNS server may send. this option is only valid together with --dnssec. if --dnssec keeps returning an error, try --udpsize 512 👑 the default setting is 1280 bytes, which is adequate for Ethernet, but other kinds of networks may impose lower limits. iykyk.
• --sts — do not issue an MX query, and just display the domain's raw STS policy file. straight to the source, no filter 💖
• --sts-cache-disable — turn off STS lookups, checking, and verification. STS is enabled by default, but it requires that a global systemwide list of SSL certificate authorities is available, and that TLS_TRUSTCERTS is specified in /etc/courier/courierd. so yeah, STS can be disabled, if needed 🦋
• --sts-cache-enable — reenable STS lookups, checking, and verification, and set the size of the internal cache back to its default value. specify =size to enable and set a non-default cache size — a positive value indicating the approximate number of most recent domains whose STS policies get cached internally 🌸
• --sts-override=policy — override the domain's STS enforcement mode. policy is one of: “none”, “testing”, or “enforce”, and it overrides the cached domain STS policy setting.

Note 💀 this is a diagnostic or a testing tool. Courier may eventually purge the cached policy setting, or the domain can update its policy, replacing the overridden setting. so don't fall in love with your override, bestie.

• --sts-purge — remove the domain's cached STS policy, and retrieve and cache the domain's policy, again. out with the old, in with the new ✨
• --sts-expire — execute Courier's STS policy expiration process. nothing happens unless /var/lib/courier/sts's size exceeds the configured cache size setting. the oldest cached policy files get removed to bring the cache size down to its maximum size 🧹

---

🫶 STRICT TRANSPORT SECURITY 🫶

Courier automatically downloads and caches domains' STS policy files by default, in an internal cache with a default size of 1000 domains 💖

Note the cache size setting is approximate. Courier purges stale cache entries periodically, and the size of the cache can temporarily exceed its set size, by as much as a factor of two. /var/lib/courier/sts must be owned by courier:courier, and uses one file per mail domain. the maximum cache size depends on the capabilities of the underlying filesystem 🦋 testmxlookup must be executed with sufficient privileges to access the cache directory (by root, or by courier). without sufficient privileges testmxlookup still attempts to use the cache directory even without write permissions on it, as long as it's accessible, and attempts to download the STS policy for a domain that's not already cached; but, of course, won't be able to save the downloaded policy in the cache directory 😭

---

👀 SEE ALSO 👀

courier(8)[1], RFC 1035[2], RFC 8461[3].

---

💜 AUTHOR 💜

Sam Varshavchik — Author

---

📝 NOTES 📝

1. courier(8) — https://www.courier-mta.org/courier.html
2. RFC 1035 — https://datatracker.ietf.org/doc/html/rfc1035
3. RFC 8461 — https://datatracker.ietf.org/doc/html/rfc8461

---

and that's the whole page, bestie 🎀 this one shipped as part of the Courier Mail Server, dated 01/10/2026 — go forth and diagnose those mail servers, you absolute icon 💅✨