Quickstart Guide

Up and running in minutes

Follow these steps to make your first MxToolbox API call. No SDK required — all you need is an API key and an HTTP client.

1

Get Your API Key

Create a free MxToolbox account to receive your API key. Free accounts include 68 DNS API requests to get you started. Paid plans unlock higher request quotas, network lookups, and full monitor access.

Create a Free Account →

2

Make Your First Lookup (No Key Required)

Test the API instantly in your browser or terminal using example.com — no API key needed for this free test endpoint.

curl "https://mxtoolbox.com/api/v1/lookup/dns/example.com"

You should receive a JSON response with DNS check results for example.com. Check the Commands tab on the Lookup API for all available lookup types.

3

Add Your API Key to the Header

Once you have your key, include it as an Authorization header on every request. The format is a plain UUID — no "Bearer" prefix required.

curl -X GET \
  "https://mxtoolbox.com/api/v1/lookup/mx/yourdomain.com" \
  -H "Authorization: 00000000-0000-0000-0000-000000000000"

4

Run a Blacklist Check

One of the most popular use cases — check whether a domain or IP address appears on any email blacklist. This is a Network Lookup and counts against your NetworkRequests quota.

curl -X GET \
  "https://mxtoolbox.com/api/v1/lookup/blacklist/yourdomain.com" \
  -H "Authorization: 00000000-0000-0000-0000-000000000000"

5

Query Your Monitors

Retrieve the current status of all monitors on your account. Optionally filter by command type, domain, or tag. Monitor queries require a paid API key.

curl -X GET \
  "https://api.mxtoolbox.com/api/v1/Monitor" \
  -H "Authorization: 00000000-0000-0000-0000-000000000000"

6

Check Your Usage

Keep track of how many DNS and network requests you've consumed in the current billing period relative to your plan limits.

curl -X GET \
  "https://api.mxtoolbox.com/api/v1/Usage" \
  -H "Authorization: 00000000-0000-0000-0000-000000000000"

The response will show DnsRequests / DnsMax and NetworkRequests / NetworkMax for your account. See DNS Lookups and Network Lookups to understand which commands consume which quota.

Lookup API

DNS · Email · Network · Blacklist

Run any lookup available in the MxToolbox SuperTool programmatically. Supports DNS records, email authentication checks (SPF, DKIM, DMARC), blacklist lookups, network diagnostics, and more.

GET api/v1/Lookup/{Command}/?argument={argument}

Run a Lookup −

Try it →

Path Parameters

Name	Type	Required	Description
Command string	Path	Required	The lookup type to perform. See Commands tab for all valid values (e.g. `mx`, `blacklist`, `dns`).

Query Parameters

Name	Type	Required	Description
argument string	Query	Required	The domain name or IP address to look up. Example: `example.com` or `192.0.2.1`. The dkim command requires the argument formatted as {domain}:{selector} — e.g. ?argument=example.com:default. Both parts are required; the lookup cannot proceed without a selector.
port string	Query	Optional	The port number to use for the lookup. Example: `80` or `443`.

Request Headers

Header	Value	Required	Description
Authorization	`string (UUID)`	Required	Your MxToolbox API key in UUID format.

JavaScript (jQuery Ajax)

var apiUrl = 'https://mxtoolbox.com/api/v1/lookup/dns/example.com';
var apiKey = '00000000-0000-0000-0000-000000000000';

$.ajax({
  url:      apiUrl,
  type:     'GET',
  dataType: 'json',
  success: function(result) {
    // OnSuccess Callback
    console.log(result);
  },
  error: function(xhr, status, error) {
    // OnError Callback
  },
  beforeSend: function(xhr) {
    if (apiKey) {
      xhr.setRequestHeader('Authorization', apiKey);
    }
  }
});

Curl

curl -X GET \
  "https://mxtoolbox.com/api/v1/lookup/dns/example.com" \
  -H "Authorization: 00000000-0000-0000-0000-000000000000"

Python (requests)

import requests

api_url = "https://mxtoolbox.com/api/v1/lookup/dns/example.com"
headers = {"Authorization": "00000000-0000-0000-0000-000000000000"}

response = requests.get(api_url, headers=headers)
data = response.json()

Response Schema (200 OK)

{
  "UID":                 "",
  "Command":             "",
  "CommandArgument":     "",
  "TimeRecorded":        Date,
  "ReportingNameServer": "",
  "TimeToComplete":      "",
  "IsEndpoint":          false,
  "HasSubscriptions":    false,
  "Failed": [
    { "ID": 0, "Name": "", "Info": "", "Url": "" }
  ],
  "Warnings": [
    { "ID": 0, "Name": "", "Info": "", "Url": "" }
  ],
  "Passed": [
    { "ID": 0, "Name": "", "Info": "", "Url": "" }
  ],
  "Timeouts": [
    { "ID": 0, "Name": "", "Info": "", "Url": "" }
  ]
}

Field Descriptions

Field	Type	Description
UID	string	Unique identifier for this lookup result.
Command	string	The command that was executed (e.g. `dns`).
CommandArgument	string	The domain or IP address that was queried.
TimeRecorded	Date	Timestamp when the lookup was recorded.
ReportingNameServer	string	The DNS server that responded to the query.
TimeToComplete	string	Duration of the lookup in milliseconds.
IsEndpoint	boolean	Whether the result is a terminal endpoint.
HasSubscriptions	boolean	Whether the account has active subscriptions.
Failed	array	List of checks that failed. Each item contains ID, Name, Info, and Url.
Warnings	array	List of checks that produced warnings.
Passed	array	List of checks that passed successfully.
Timeouts	array	List of checks that timed out.

Valid Command Values

a

aaaa

arin

asn

bimi

blacklist

dkim

dmarc

dns

http

https

mta-sts

mx

ping

ptr

smtp

soa

spf

tcp

tlsrpt

trace

txt

Argument Type

Argument	Description	Example
Domain Name	For email/DNS record lookups	`example.com`
IP Address	For blacklist/network lookups	`192.0.2.1`

Live Test: Try a free DNS lookup right now — no API key needed:
https://mxtoolbox.com/api/v1/lookup/dns/example.com

▶ Try It — Live Request

Command

Required

Argument

Required QueryString

Port

Optional QueryString

API Key

Response

Monitor API

Uptime · Status · Alerting

Query the status of all monitors configured on your MxToolbox account, including their current state, failure details, and tag metadata.

GET api/v1/Monitor?command={Command}&name={name}&tag={tag}

Query monitor status +

Path Parameters

Name	Type	Required	Description
Command string	Path	Optional	Filter monitors by lookup type. Uses the same values as the Lookup API (e.g. `mx`, `blacklist`, `dns`). Omit to return all monitors regardless of type.

Query Parameters

Name	Type	Required	Description
name string	Query	Optional	Filter monitors by the domain name or IP address being monitored. Example: `example.com` or `192.0.2.1`.
tag string	Query	Optional	Filter monitors by a tag name. Returns only monitors that have been assigned the specified tag. Example: `production`.

Request Headers

Header	Value	Required	Description
Authorization	`string (UUID)`	Required	Your MxToolbox API key.

All three parameters are optional and can be combined. For example, api/v1/Monitor?command=mx&name=example.com&tag=production returns MX monitors for example.com tagged as "production".

JavaScript (jQuery Ajax) — All monitors

var apiUrl = 'https://api.mxtoolbox.com/api/v1/Monitor';
    var apiKey = '00000000-0000-0000-0000-000000000000';

    $.ajax({
    url:      apiUrl,
    type:     'GET',
    dataType: 'json',
    success: function(result) {
        // OnSuccess Callback
        console.log(result);
    },
    error: function(xhr, status, error) {
        // OnError Callback
    },
    beforeSend: function(xhr) {
        if (apiKey) {
        xhr.setRequestHeader('Authorization', apiKey);
        }
    }
    });

JavaScript (jQuery Ajax) — Filtered by command, name & tag

var command  = 'mx';
    var name = 'example.com';
    var tag      = 'production';
    var apiUrl   = 'https://api.mxtoolbox.com/api/v1/Monitor?command=' + command +
                '&name=' + name + '&tag=' + tag;
    var apiKey   = '00000000-0000-0000-0000-000000000000';

    $.ajax({
    url:      apiUrl,
    type:     'GET',
    dataType: 'json',
    success: function(result) {
        // OnSuccess Callback
        console.log(result);
    },
    error: function(xhr, status, error) {
        // OnError Callback
    },
    beforeSend: function(xhr) {
        if (apiKey) {
        xhr.setRequestHeader('Authorization', apiKey);
        }
    }
    });

Curl — All monitors

curl -X GET \
    "https://api.mxtoolbox.com/api/v1/Monitor" \
    -H "Authorization: 00000000-0000-0000-0000-000000000000"

Curl — Filtered by command, name & tag

curl -X GET \
    "https://api.mxtoolbox.com/api/v1/Monitor?command=mx&name=example.com&tag=production" \
    -H "Authorization: 00000000-0000-0000-0000-000000000000"

Response Schema (200 OK) — Array of Monitor Objects

[
        {
        "MonitorUID":      "",
        "ActionString":   "",
        "LastTransition": Date,
        "MxRep":          "",
        "HistoryUrl":     "",
        "Name":           "",
        "TimeElapsed":    "",
        "RecordCount":    "",
        "LarUID":         "",
        "Tags": [
        {
            "Name":         "",
            "UID":          "",
            "IsHidden":     false,
            "IsNegative":   false,
            "MonitorCount": 0
        }
        ],
        "Failing": [
        { "ID": 0, "Name": "", "Info": "", "Url": "" }
        ],
        "Warnings": [
        { "ID": 0, "Name": "", "Info": "", "Url": "" }
        ]
        }
    ]

Field Descriptions

Field	Type	Description
MonitorUID	string	Unique identifier for the monitor.
ActionString	string	Current status/action description (e.g. "OK", "Failing").
LastTransition	Date	Timestamp of the last status change.
MxRep	string	MxToolbox reputation score.
HistoryUrl	string	URL to view the full monitor history.
Name	string	Human-readable name of the monitor.
TimeElapsed	string	Time since last check.
RecordCount	string	Number of records returned in the last check.
LarUID	string	Unique ID of the last action result.
Tags	array	Array of tag objects associated with this monitor.
Failing	array	Current failing checks for this monitor.
Warnings	array	Current warning checks for this monitor.

Valid Command Values

The Monitor API accepts the same command values as the Lookup API. When supplied, only monitors of that type are returned.

a

aaaa

arin

asn

bimi

blacklist

dkim

dmarc

dns

http

https

mta-sts

mx

ping

ptr

smtp

soa

spf

tcp

tlsrpt

trace

txt

Tag Parameter

Parameter	Value	Description
tag	`string`	Any tag name previously assigned to monitors in your account (e.g. `production`, `staging`, `customers`). Tags are defined and managed in the MxToolbox dashboard. Supplying a tag filters results to only monitors carrying that tag.

Example URL Combinations

URL	Returns
`api/v1/Monitor`	All monitors on the account
`api/v1/Monitor?command=mx`	All MX record monitors
`api/v1/Monitor?command=blacklist&name=192.0.2.1`	Blacklist monitor for a specific IP
`api/v1/Monitor?tag=production`	All monitors tagged "production"
`api/v1/Monitor?command=mx&name=example.com&tag=production`	MX monitors for example.com tagged "production"

GET api/v1/Monitor/{MonitorUID}

GET monitor BY UID +

Path Parameters

Name	Type	Required	Description
MonitorUID string	Path	Required	Filter monitors by UID.

JavaScript (jQuery Ajax) — Monitor

var apiUrl = 'https://api.mxtoolbox.com/api/v1/Monitor/123456789';
var apiKey = '00000000-0000-0000-0000-000000000000';

    $.ajax({
    url:      apiUrl,
    type:     'GET',
    dataType: 'json',
    success: function(result) {
        // OnSuccess Callback
        console.log(result);
    },
    error: function(xhr, status, error) {
        // OnError Callback
    },
    beforeSend: function(xhr) {
        if (apiKey) {
        xhr.setRequestHeader('Authorization', apiKey);
        }
    }
    });

Response Schema (200 OK) — Array of Monitor Objects

[
        {
        "MonitorUID":      "",
        "ActionString":   "",
        "LastTransition": Date,
        "MxRep":          "",
        "HistoryUrl":     "",
        "Name":           "",
        "TimeElapsed":    "",
        "RecordCount":    "",
        "LarUID":         "",
        "Tags": [
        {
            "Name":         "",
            "UID":          "",
            "IsHidden":     false,
            "IsNegative":   false,
            "MonitorCount": 0
        }
        ],
        "Failing": [
        { "ID": 0, "Name": "", "Info": "", "Url": "" }
        ],
        "Warnings": [
        { "ID": 0, "Name": "", "Info": "", "Url": "" }
        ]
        }
    ]

GET api/v1/Monitor/{MonitorUID}/Tag

GET tags for a monitor +

Path Parameters

Name	Type	Required	Description
MonitorUID string	Path	Required	Unique identifier of the monitor to retrieve tags for. Obtained from the MonitorUID field in the Monitor API response. Example: 1234567890

Request Headers

Name	Value	Required	Description
Authorization	string (UUID)	Required	Your MxToolbox API key.

Obtain a MonitorUID by calling GET api/v1/Monitor and reading the MonitorUID field from the response.

JavaScript (jQuery Ajax) — Monitor

var monitorUID = '1234567890';
var apiUrl     = 'https://api.mxtoolbox.com/api/v1/Monitor/' + monitorUID + '/Tag';
var apiKey     = '00000000-0000-0000-0000-000000000000';

$.ajax({
  url:      apiUrl,
  type:     'GET',
  dataType: 'json',
  success: function(result) {
    // OnSuccess Callback
  },
  error: function(xhr, status, error) {
    // OnError Callback
  },
  beforeSend: function(xhr) {
    if (apiKey) { xhr.setRequestHeader('Authorization', apiKey); }
  }
});

Curl

curl -X GET \
  "https://api.mxtoolbox.com/api/v1/Monitor/1234567890/Tag" \
  -H "Authorization: 00000000-0000-0000-0000-000000000000"

Python (requests)

import requests

monitor_uid = "1234567890"
api_url     = f"https://api.mxtoolbox.com/api/v1/Monitor/{monitor_uid}/Tag"
headers     = {"Authorization": "00000000-0000-0000-0000-000000000000"}

response = requests.get(api_url, headers=headers)
data = response.json()

Response Schema (200 OK) — Array of Monitor Objects

[
  {
    "Name":         "",
    "UID":          "",
    "IsHidden":     false,
    "IsNegative":   false,
    "MonitorCount": 0
  }
]

Field Descriptions

Field	Type	Description
Name	string	Display name of the tag (e.g. `production`, `staging`).
UID	string	Unique identifier for the tag.
IsHidden	boolean	Whether the tag is hidden from the MxToolbox dashboard UI.
IsNegative	boolean	Whether the tag represents a negative/exclusion filter.
MonitorCount	integer	Number of monitors currently assigned this tag.

Usage API

Quota · Consumption · Limits

Check your current API usage against your plan’s daily limits. Returns counts for DNS and network requests along with your plan maximums.

GET api/v1/Usage

Get current usage counters +

Name	Type	Required	Description
No parameters. Returns usage for the authenticated account.

Request Headers

Name	Type	Required	Description
Authorization	`string (UUID)`	Required	Your MxToolbox API key.

JavaScript (jQuery Ajax)

var apiUrl = 'https://api.mxtoolbox.com/api/v1/Usage';
var apiKey = '00000000-0000-0000-0000-000000000000';

$.ajax({
  url:      apiUrl,
  type:     'GET',
  dataType: 'json',
  success: function(result) {
    // OnSuccess Callback
    console.log(result);
  },
  error: function(xhr, status, error) {
    // OnError Callback
  },
  beforeSend: function(xhr) {
    if (apiKey) {
      xhr.setRequestHeader('Authorization', apiKey);
    }
  }
});

Curl

curl -X GET \
  "https://api.mxtoolbox.com/api/v1/Usage" \
  -H "Authorization: 00000000-0000-0000-0000-000000000000"

Response Schema (200 OK)

{
  "DnsRequests":    0,
  "DnsMax":         0,
  "NetworkRequests": 0,
  "NetworkMax":     0
}

Field Descriptions

Field	Type	Description
DnsRequests	integer	Number of DNS lookup requests used in the current billing period.
DnsMax	integer	Maximum DNS requests allowed under your current plan.
NetworkRequests	integer	Number of network requests (ping, HTTP, etc.) used.
NetworkMax	integer	Maximum network requests allowed under your current plan.

DNS vs. Network Requests

Quota · Commands · Argument Format

Every Lookup API call counts against one of two quotas depending on the command used. Check your current consumption at any time with the Usage API.

🌐 DNS Lookups — DnsRequests quota

Command	Argument	Description
a	`domain.com`	DNS A record — resolves a hostname to its IPv4 address.
aaaa	`domain.com`	DNS AAAA record — resolves a hostname to its IPv6 address.
asn	`domain.com` or IP	Autonomous System Number lookup for a domain or IP.
bimi	`domain.com`	Checks the BIMI DNS record for the domain.
dkim special	`domain.com:selector`	DKIM key lookup. Argument must be domain:selector — e.g. `example.com:default`.
dmarc	`domain.com`	Checks the DMARC policy record for the domain.
dns	`domain.com`	General DNS health check — verifies server config and propagation.
mta-sts	`domain.com`	Checks for an MTA Strict Transport Security record.
mx	`domain.com`	Returns the mail exchange servers for the domain.
ptr	`192.0.2.1`	Reverse DNS — resolves an IP address to its hostname.
soa	`domain.com`	Start of Authority — returns primary DNS server and zone metadata.
spf	`domain.com`	SPF record check — validates the Sender Policy Framework config.
tlsrpt	`domain.com`	Checks for an RFC 8460 TLSRPT DNS record.
txt	`domain.com`	Returns all TXT records published for the domain.

📡 Network Lookups — NetworkRequests quota

Command	Argument	Description
blacklist	`domain.com` or IP	Checks whether a domain or IP appears on any major email blacklist.
http	`domain.com` or URL	Verifies that the host responds to HTTP connections on port 80.
https	`domain.com` or URL	Verifies HTTPS connectivity and checks the SSL/TLS certificate.
ping	`domain.com` or IP	Performs a standard ICMP ping to test reachability of the host.
smtp	`domain.com` or IP	Tests SMTP connection on port 25 and validates the banner response.
tcp	`domain.com` or IP	Verifies that a host accepts TCP connections.
trace	`domain.com` or IP	Performs an ICMP traceroute to map the network path to the host.

DKIM Note: The dkim command requires the argument formatted as {domain}:{selector} — e.g. ?argument=example.com:default. Both parts are required; the lookup cannot proceed without a selector.

Response Codes

Code	Status	Description
200	OK	Request was successful. Response body contains the JSON result.
401	Unauthorized	Missing or invalid API key in the Authorization header.
429	Too Many Requests	Rate limit or usage quota exceeded. Check your Usage API for current limits.
500	Server Error	An unexpected error occurred on the MxToolbox server.

Rate Limits

MxToolbox API usage is tracked against daily usage limits. These limits reset each day at 12:00 am UTC. You can check your current consumption at any time using the Usage API.

Plan	DNS Requests	Network Requests	Monitor Queries
Free	64 (daily)	0	—
Paid	Per plan quota	Per plan quota	Included

To increase your quota, upgrade your plan →

MxToolbox RESTful API Reference

Quickstart Guide

Get Your API Key

Make Your First Lookup (No Key Required)

Add Your API Key to the Header

Run a Blacklist Check

Query Your Monitors

Check Your Usage

Lookup API

Monitor API

Usage API

DNS vs. Network Requests

Response Codes

Rate Limits

MxToolBox has been Updated