Skip to the documentation
API

Tools

Every operation in this group: what it accepts, what it returns and the errors it can answer with.

Operations

The free tools on the Nextmail website, which need no scope. Three check the public mail records of any domain: its DMARC policy, its BIMI logo, and a deliverability report across MX, SPF, DKIM, DMARC and BIMI. They read public DNS and nothing in the workspace, and every answer is what DNS said at that moment. One reads the sign-in code in a message you pass in, and one prices every plan for a usage.

GET/tools/dmarc

Check a domain's DMARC policy

No scopeReads

Reads the domain's DMARC record from public DNS, or the record of the organisational domain it inherits from, and says how strict it is and what is wrong with it. stage is missing, invalid, monitor for p=none, quarantine or reject.

Needs no scope: any key or access token for the workspace may run it.

Query parameters

domainstringRequired

The domain to check, such as acme.com. An email address, a URL or a domain with a trailing dot is read as its domain. Any public domain works, not only the ones in this workspace.

Up to 320 characters

Returns

What the DMARC record says.

Errors

422

invalid_parameter on domain: it does not read as a domain.

503

unreachable: public DNS did not answer for the domain just now. Nothing about the domain was decided, so try again in a moment.

The errors every operation can return400401403404429500Error catalog

Also available in

TypeScript
nextmail.tools.checkDmarc()
Python
tools.check_dmarc()
Ruby
tools.check_dmarc
PHP
tools->checkDmarc
Go
Tools.CheckDmarc
Java
tools().checkDmarc
C#
Tools.CheckDmarcAsync
CLI
openemail tools check-dmarc
MCP
checkDmarc

GET/tools/bimi

Check a domain's BIMI logo

No scopeReads

Reads the domain's BIMI record, fetches the logo it names and checks the DMARC policy beside it, since inboxes draw a logo only at p=quarantine or p=reject. status is present, partial when the record is there but something stops inboxes showing it, absent or invalid, and issues says why.

Needs no scope: any key or access token for the workspace may run it.

Query parameters

domainstringRequired

The domain to check, such as acme.com. An email address, a URL or a domain with a trailing dot is read as its domain. Any public domain works, not only the ones in this workspace.

Up to 320 characters

Returns

What the BIMI record says and whether inboxes can draw the logo.

Errors

422

invalid_parameter on domain: it does not read as a domain.

503

unreachable: public DNS did not answer for the domain just now. Nothing about the domain was decided, so try again in a moment.

The errors every operation can return400401403404429500Error catalog

Also available in

TypeScript
nextmail.tools.checkBimi()
Python
tools.check_bimi()
Ruby
tools.check_bimi
PHP
tools->checkBimi
Go
Tools.CheckBimi
Java
tools().checkBimi
C#
Tools.CheckBimiAsync
CLI
openemail tools check-bimi
MCP
checkBimi

GET/tools/deliverability

Check a domain's deliverability

No scopeReads

Checks the records a receiving mailbox reads before it trusts mail from the domain: MX, SPF, DKIM at the selectors its mail provider uses, DMARC and BIMI. Each check says pass, warn, fail or absent with a verdict and notes written to be shown to a person, and score weighs them into 0 to 100, graded A to F.

Needs no scope: any key or access token for the workspace may run it.

Query parameters

domainstringRequired

The domain to check, such as acme.com. An email address, a URL or a domain with a trailing dot is read as its domain. Any public domain works, not only the ones in this workspace.

Up to 320 characters

Returns

Each check, the score and the grade.

Errors

422

invalid_parameter on domain: it does not read as a domain.

503

unreachable: public DNS did not answer for the domain just now. Nothing about the domain was decided, so try again in a moment.

The errors every operation can return400401403404429500Error catalog

Also available in

TypeScript
nextmail.tools.checkDeliverability()
Python
tools.check_deliverability()
Ruby
tools.check_deliverability
PHP
tools->checkDeliverability
Go
Tools.CheckDeliverability
Java
tools().checkDeliverability
C#
Tools.CheckDeliverabilityAsync
CLI
openemail tools check-deliverability
MCP
checkDeliverability

POST/tools/verification-code

Read the sign-in code in a message

No scopeReads

Finds the sign-in or verification code in a message you pass in, with the reader that puts a code at the top of a message in Nextmail. Send the message as raw (the whole MIME source) or as subject with html or text.

It answers only when it is sure. The message has to hold exactly one code worded as one, such as a verification code, a one-time code or a security code, in any of the common languages. Two different codes, or a number that could be an order, a booking, a meeting, a phone number or a promotion, give code: null. The code comes back as you would type it: digits only, or capital letters and digits, without spaces or dashes.

It reads only what you send, so it cannot tell whether the sender is who it claims to be. The verificationCode on a message in your mailbox also requires the sender to pass authentication. Nothing is stored, and no model is called.

Needs no scope: any key or access token for the workspace may run it.

Request body

subjectstring

Subject line, at most 998 characters.

Up to 998 characters
htmlstring

HTML body. Links are left out before the code is looked for.

Up to 1000000 characters
textstring

Plain text body, used when there is no html.

Up to 1000000 characters
rawstring

The whole message as MIME source, as it was received. Wins over the other fields when it is set.

Up to 5000000 characters

Returns

The code, or null when the reader is not sure.

Errors

The errors every operation can return400401403404422429500Error catalog

Also available in

TypeScript
nextmail.tools.readVerificationCode()
Python
tools.read_verification_code()
Ruby
tools.read_verification_code
PHP
tools->readVerificationCode
Go
Tools.ReadVerificationCode
Java
tools().readVerificationCode
C#
Tools.ReadVerificationCodeAsync
CLI
openemail tools read-verification-code

GET/tools/address

Check an email address

No scopeReads

Says whether an address is worth sending to: valid, risky, invalid or unknown, with the reasons. It checks the syntax, whether the domain takes mail at all, whether it is a throwaway domain or a role address such as info@, and offers a correction for a likely typo such as gmial.com. With the emails:read scope it also says what this workspace knows: whether it suppressed the address and when it last delivered to it or saw it bounce. It never shows another workspace's history.

deep also asks whether the mailbox exists. A deep check is billed per address through pay as you go, $1.50 per 100 addresses on every plan, needs the emails:send scope, and is refused when pay as you go is off. Without it the check is free and checks.mailbox is null.

Needs no scope: any key or access token for the workspace may run it.

Query parameters

emailstring

The address to check.

1 to 320 characters
deepboolean

Also ask whether the mailbox exists. Billed per address. Defaults to false.

Defaultfalse

Returns

What the check found.

Errors

409

deep_check_unavailable or deep_check_limit_reached: a deep check needs pay as you go, and has to fit under its monthly limit.

503

deep_check_unavailable: the mailbox check did not answer. Nothing was billed.

The errors every operation can return400401403404422429500Error catalog

Also available in

TypeScript
nextmail.tools.checkAddress()
Python
tools.check_address()
Ruby
tools.check_address
PHP
tools->checkAddress
Go
Tools.CheckAddress
Java
tools().checkAddress
C#
Tools.CheckAddressAsync
CLI
openemail tools check-address
MCP
checkAddress

POST/tools/addresses

Check several email addresses

No scopeReads

Checks up to 100 addresses in one call, each as GET /tools/address does, and returns them in the order they were sent. deep applies to every address and is billed for each one that reaches the mailbox check.

Needs no scope: any key or access token for the workspace may run it.

Request body

emailsstring[]Required

The addresses to check, from 1 to 100.

1 to 100 items
deepboolean

Also ask whether each mailbox exists. Billed per address through pay as you go. Defaults to false.

Defaultfalse

Returns

One check per address, in order.

Errors

409

deep_check_unavailable or deep_check_limit_reached: a deep check needs pay as you go, and has to fit under its monthly limit.

503

deep_check_unavailable: the mailbox check did not answer. Nothing was billed.

The errors every operation can return400401403404422429500Error catalog

Also available in

TypeScript
nextmail.tools.checkAddresses()
Python
tools.check_addresses()
Ruby
tools.check_addresses
PHP
tools->checkAddresses
Go
Tools.CheckAddresses
Java
tools().checkAddresses
C#
Tools.CheckAddressesAsync
CLI
openemail tools check-addresses

GET/tools/cost

Estimate what Nextmail costs for a usage

No scopeReads

Prices every plan for the usage you describe, as the cost calculator on the Nextmail website does: the plan itself, the extra sends and AI actions it would bill, the monthly total, and whether the plan fits at all. A plan does not fit when the usage needs more domains than it includes, more than one person without team access, or more sends than it allows without billing extra. cheapest names the cheapest plan that fits.

Amounts are in US cents per month. With interval set to year, the plan price is the monthly equivalent of paying yearly.

Needs no scope: any key or access token for the workspace may run it.

Query parameters

sendsinteger

Emails sent in a month. Defaults to 0.

At least 0At most 1000000000
domainsinteger

Domains you send from. Defaults to 1.

At least 0At most 1000000
peopleinteger

People who use the workspace. Defaults to 1.

At least 1At most 1000000
aiActionsinteger

AI actions in a day, such as drafts, rewrites and summaries. Defaults to 0.

At least 0At most 10000000
intervalstring

How you pay: month or year. Defaults to month.

One of"month""year"

Returns

Every plan priced for the usage, and the cheapest one that fits.

Errors

The errors every operation can return400401403404422429500Error catalog

Also available in

TypeScript
nextmail.tools.estimateCost()
Python
tools.estimate_cost()
Ruby
tools.estimate_cost
PHP
tools->estimateCost
Go
Tools.EstimateCost
Java
tools().estimateCost
C#
Tools.EstimateCostAsync
CLI
openemail tools estimate-cost

Objects

AddressCheckobject

objectstringRequired
One of"address_check"
emailstringRequired

The address as it was sent.

normalizedstringRequired

The address lower-cased, with an international domain in its ASCII form. Null when the syntax is wrong.

Can be null
resultstringRequired

valid is safe to send to, risky may bounce or annoy, invalid will not be delivered, and unknown means DNS did not answer.

One of"valid""risky""invalid""unknown"
reasonsstring[]Required

Why the result is not valid. Empty for a valid address.

One of"invalid_syntax""domain_not_found""no_mail_server""null_mx""no_mx_record""dns_unreachable""disposable""role_address""typo_suspected""suppressed""bounced_before""mailbox_not_found""mailbox_uncertain""random_input"
suggestionstringRequired

The address with a likely typo in its domain corrected, or null.

Can be null
checksobjectRequired
syntaxbooleanRequired
mxobjectRequired
statusstringRequired

found has mail servers, implicit has none but the domain itself answers, missing, null_mx and domain_not_found take no mail, and unknown means DNS did not answer.

One of"found""implicit""missing""null_mx""domain_not_found""unknown"
hostsstring[]Required
nullMxbooleanRequired

The domain says it takes no mail.

disposablebooleanRequired

A throwaway mailbox domain.

rolebooleanRequired

A shared address such as info@ or support@.

freeProviderbooleanRequired

A public mailbox provider such as Gmail.

mailboxobjectRequired

Only with deep: how sure the mailbox check is. Null otherwise.

Can be null
existsstringRequired
One of"high""medium""low"
validstringRequired
One of"high""medium""low"
randomInputstringRequired
One of"high""medium""low"
workspaceobjectRequired

What this workspace knows about the address. Null without the emails:read scope.

Can be null
suppressedbooleanRequired
lastBouncedAtstringRequired
Can be nullFormatdate-time
lastDeliveredAtstringRequired
Can be nullFormatdate-time
checkedAtstringRequired
Formatdate-time

AddressCheckListobject

objectstringRequired
One of"list"
dataAddressCheck[]Required

BimiReportobject

objectstringRequired
One of"bimi_report"
domainstringRequired
recordstringRequired

The BIMI record at default._bimi, or null.

Can be null
versionstring
Can be null
logoUrlstring

The l= of the record: where the SVG logo is served.

Can be null
authorityUrlstring

The a= of the record: where the mark certificate is served, or null without one.

Can be null
logoSvgstring

The logo as it was fetched, when it could be, to show it.

Can be null
logoReachableboolean
dmarcPolicystring

The p= of the DMARC record beside it.

Can be null
dmarcEnforcedboolean

Whether that policy is quarantine or reject, the only ones under which a logo is drawn.

statusstringRequired
One of"present""partial""absent""invalid"
issuesstring[]Required

CostEstimateobject

objectstringRequired
One of"cost_estimate"
intervalstringRequired
One of"month""year"
needobjectRequired

The usage that was priced, with the defaults filled in.

sendsintegerRequired
domainsintegerRequired
peopleintegerRequired
aiActionsintegerRequired
plansPlanEstimate[]Required
cheapeststringRequired

The id of the cheapest plan that fits, or null when none does.

Can be null

DeliverabilityCheckobject

idstringRequired
One of"mx""spf""dkim""dmarc""bimi"
labelstringRequired
statusstringRequired
One of"pass""warn""fail""absent"
verdictstringRequired

One line saying what was found.

recordstringRequired

The record that was read, when there is one.

Can be null
notesstring[]Required

DeliverabilityReportobject

objectstringRequired
One of"deliverability_report"
domainstringRequired
scoreintegerRequired
At least 0At most 100
gradestringRequired
One of"A""B""C""D""F"
providerstringRequired

The mail provider its MX records point at, such as Google Workspace, when it is known.

Can be null
checksDeliverabilityCheck[]Required

DmarcReportobject

objectstringRequired
One of"dmarc_report"
domainstringRequired

The domain that was checked, lower-cased.

recordstringRequired

The DMARC record as published, or null when there is none.

Can be null
inheritedFromstringRequired

The parent domain whose record applies, when the domain has none of its own. Null when the record is its own or there is none.

Can be null
tagsRecord<string, string>Required

Every tag of the record, such as p, sp, pct and rua, as written.

stagestringRequired
One of"missing""invalid""monitor""quarantine""reject"
issuesstring[]Required

Problems found, each written to be shown to a person. Empty when there are none.

PlanEstimateobject

objectstringRequired
One of"plan_estimate"
planstringRequired
One of"free""starter""business""enterprise"
namestringRequired

The plan as it is named on the pricing page.

fitsbooleanRequired

Whether the plan can carry the usage at all. False when blockers names anything.

blockersstring[]Required

What the plan cannot carry: domains beyond the ones it includes, people without team access, or sends beyond its limit on a plan that bills no extra sends.

One of"domains""people""sends"
baseCentsintegerRequired

The plan price per month, or its monthly equivalent when paid yearly.

extraSendsintegerRequired

Sends beyond what the plan includes in a month.

sendsCentsintegerRequired

What those extra sends cost in a month.

extraAiActionsintegerRequired

AI actions beyond what the plan includes, over a 30-day month.

aiCentsintegerRequired

What those extra AI actions cost in a month.

extrasCentsintegerRequired

sendsCents and aiCents together.

totalCentsintegerRequired

The plan price and the extras: what a month costs.

VerificationCodeResultobject

objectstringRequired
One of"verification_code"
codestringRequired

The code as you would type it, or null when the message holds no code the reader is sure of.

Can be null