MX Lookup
Look up MX (Mail Exchange) records for any domain. Returns all mail server hostnames and their priorities, sorted from highest to lowest priority (ascending numeric value). Use this to verify email deliverability, discover mail server infrastructure, and diagnose email routing issues.
Overview
Use Cases
- Verifying a domain is configured to receive email before sending
- Email deliverability checks in validation pipelines
- Discovering mail server infrastructure for a domain
- Diagnosing email routing and delivery issues
- Building email validation tools that go beyond syntax checking
Features
Returns all MX records for any domain
Records sorted by priority (lowest numeric value = highest priority)
Includes both hostname and priority for each mail server
Returns 404 when no MX records exist for the domain
API Endpoints
MX Lookup
Retrieve all MX records for a domain. Results are sorted by priority ascending (lowest numeric value has highest mail delivery priority per RFC 5321).
GET
https://requiems.xyz/v1/networking/mx/{domain}
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
| domain | string |
Required | The domain name to look up MX records for (e.g. gmail.com) |
Try it out
Live DemoRequest
The domain name to look up MX records for (e.g. gmail.com)
Sending request...
Response Fields
| Field | Type | Description |
|---|---|---|
| domain | string |
The domain that was queried |
| records | array<object> |
List of MX records, sorted by priority ascending (lowest number = highest priority) |
| records[].host | string |
Fully-qualified hostname of the mail server (typically ends with a trailing dot) |
| records[].priority | integer |
MX priority value. Lower values have higher delivery priority per RFC 5321. |
Code Examples
curl "https://requiems.xyz/v1/networking/mx/gmail.com" \
-H "requiems-api-key: YOUR_API_KEY"import requests
url = "https://requiems.xyz/v1/networking/mx/gmail.com"
headers = {"requiems-api-key": "YOUR_API_KEY"}
response = requests.get(url, headers=headers)
data = response.json()["data"]
for record in data["records"]:
print(record["priority"], record["host"])const response = await fetch('https://requiems.xyz/v1/networking/mx/gmail.com', {
headers: { 'requiems-api-key': 'YOUR_API_KEY' }
});
const { data } = await response.json();
data.records.forEach(r => console.log(r.priority, r.host));require 'net/http'
require 'json'
uri = URI('https://requiems.xyz/v1/networking/mx/gmail.com')
request = Net::HTTP::Get.new(uri)
request['requiems-api-key'] = 'YOUR_API_KEY'
response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
http.request(request)
end
data = JSON.parse(response.body)['data']
data['records'].each { |r| puts "#{r['priority']} #{r['host']}" }Error Responses
bad_request
The domain parameter is not a valid domain name.
not_found
No MX records were found for the domain (domain may not accept email).
internal_error
DNS lookup failed due to an unexpected server error.
Batch MX Lookup
Retrieve MX records for up to 50 domains in a single request. Results for each domain are sorted by priority ascending (lowest numeric value has the highest mail delivery priority per RFC 5321).
POST
https://requiems.xyz/v1/networking/mx/batch
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
| domains | array<string> |
Required | Array of domains to lookup (min: 1, max: 50). |
Try it out
Live DemoRequest
Array of domains to lookup (min: 1, max: 50).
Sending request...
Response Fields
| Field | Type | Description |
|---|---|---|
| results | array<object> |
MX lookup results for each input domain, in the same order as the input. |
| results[].domain | string |
The domain name that was queried. |
| results[].found | boolean |
Whether MX records were found for the domain. |
| results[].error | string |
Error message if the lookup failed. Empty if found is true. |
| results[].data | object |
MX lookup data. Present only when found is true. |
| results[].data.domain | string |
The domain name associated with the MX records. |
| results[].data.records | array<object> |
List of MX records sorted by priority ascending (lower value means higher priority). |
| results[].data.records[].host | string |
Hostname of the mail server. |
| results[].data.records[].priority | number |
Priority of the mail server. Lower value means higher priority. |
| total | number |
Total number of results returned. |
Code Examples
curl -X POST "https://requiems.xyz/v1/networking/mx/batch" \
-H "requiems-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"domains":["outlook.com", "yahoo.com"]}'import requests
url = "https://requiems.xyz/v1/networking/mx/batch"
headers = {
"requiems-api-key": "YOUR_API_KEY",
"Content-Type": "application/json"
}
payload = {"domains": ["outlook.com", "yahoo.com"]}
response = requests.post(url, headers=headers, json=payload)
for result in response.json()["data"]["results"]:
print(result["domain"], result["found"])
if result["found"]:
for record in result["data"]["records"]:
print(f" {record['host']} (priority: {record['priority']})")const response = await fetch('https://requiems.xyz/v1/networking/mx/batch',
{
method: 'POST',
headers: {
'requiems-api-key': 'YOUR_API_KEY',
'Content-Type': 'application/json'
},
body: JSON.stringify({ domains: ['outlook.com', 'yahoo.com'] })
}
);
const { data } = await response.json();
data.results.forEach(r => {
console.log(r.domain, r.found);
if (r.found) {
r.data.records.forEach(record => {
console.log(record.host, record.priority);
});
}
});require 'net/http'
require 'json'
uri = URI('https://requiems.xyz/v1/networking/mx/batch')
request = Net::HTTP::Post.new(uri)
request['requiems-api-key'] = 'YOUR_API_KEY'
request['Content-Type'] = 'application/json'
request.body = { domains: ['outlook.com', 'yahoo.com'] }.to_json
response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
http.request(request)
end
JSON.parse(response.body)['data']['results'].each do |r|
puts "#{r['domain']}: #{r['found']}"
if r['found']
r['data']['records'].each do |record|
puts " #{record['host']} (priority: #{record['priority']})"
end
end
endError Responses
validation_failed
The domains array is missing, empty, or contains more than 50 items.
internal_error
DNS lookup failed due to an unexpected server error.
Frequently Asked Questions
MX priority is a numeric value where a lower number means higher delivery preference. Mail servers try the lowest-priority-number host first. For example, a server with priority 5 is tried before one with priority 10. This allows mail server failover to be configured at the DNS level.
The trailing dot is standard DNS notation indicating an absolute (fully-qualified) domain name rather than a relative one. Most mail clients strip it automatically; it is safe to remove when displaying to end users.
The API returns HTTP 404 with error code "not_found". A domain with no MX records cannot receive email via standard SMTP delivery.
Yes. Any valid domain or subdomain can be queried. However, subdomains typically do not have their own MX records unless explicitly configured; in that case you will receive a 404 response.
Yes. Records are always returned sorted by priority ascending (lowest number first), regardless of the order returned by the DNS resolver.