Docs · API reference

Verify an email address

Send one email address. Our verification servers ask its mail server whether the mailbox exists, without sending an email, and answer with a verdict and the checks behind it.

Preview: may change before launch · Updated 1 November 2026

Preview

This is how the API is planned to work. Names and fields may change before launch. The APIs are in early access: join early access to get a key when they're ready.

POST https://api.magpie-cloud.com/v1/verify. What it's for, and how it works: Email verification API.

Request

A JSON body, with your API key in the Authorization header (see Authentication).

Field	Type	Required	What it is
`email`	string	Yes	The address to check.

Example

Request · POST /verify

curl https://api.magpie-cloud.com/v1/verify \
  -H "Authorization: Bearer $MAGPIE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "email": "alex.sample@examplefreight.example" }'

const res = await fetch("https://api.magpie-cloud.com/v1/verify", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.MAGPIE_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ email: "alex.sample@examplefreight.example" }),
});
const data = await res.json();

import os
import requests

res = requests.post(
    "https://api.magpie-cloud.com/v1/verify",
    json={"email": "alex.sample@examplefreight.example"},
    headers={"Authorization": f"Bearer {os.environ['MAGPIE_API_KEY']}"},
    timeout=90,
)
data = res.json()

Response · 200

{
  "email": "alex.sample@examplefreight.example",
  "verdict": "valid",
  "summary": "The mail server says this mailbox exists.",
  "checks": {
    "syntax": true,
    "domain": true,
    "mailbox": "exists",
    "disposable": false,
    "role": false,
    "free": false,
    "provider": null
  }
}

At a domain that accepts every address, the mailbox can't be confirmed, so the verdict is catch_all, not valid.

Response: a catch-all domain

{
  "email": "sam.sample@exampleretail.example",
  "verdict": "catch_all",
  "summary": "The domain accepts every address, so this mailbox can't be confirmed.",
  "checks": {
    "syntax": true,
    "domain": true,
    "mailbox": "accepts_all",
    "disposable": false,
    "role": false,
    "free": false,
    "provider": null
  }
}

Response

Field	Type	What it is
`email`	string	The address checked.
`verdict`	string	`valid`, `invalid`, `catch_all`, `risky` or `unknown`. See Results and catch-all for what each means.
`summary`	string	One sentence saying what the mail server said, to show or log.
`checks.syntax`	boolean	Whether the address is well formed.
`checks.domain`	boolean or null	Whether the domain exists and takes email. `null` if it wasn't checked.
`checks.mailbox`	string	`exists`, `missing`, `accepts_all` (the domain accepts every address) or `unknown` (no clear answer).
`checks.disposable`	boolean or null	Whether the address is at a throwaway email service.
`checks.role`	boolean or null	Whether it's a shared role address, such as `info@` or `sales@`.
`checks.free`	boolean or null	Whether it's at a free email provider rather than a company's own domain.
`checks.provider`	string or null	The mail provider, when it's recognised; otherwise `null`.

Errors

Errors come back as JSON with a code and a message. See Errors for the shape, and when to try again.

Status	Code	When
`400`	`invalid_request`	`email` is missing or isn't a string.
`401`	`unauthorized`	The API key is missing, wrong or revoked.
`402`	`out_of_credits`	Your credits have run out.
`429`	`rate_limited`	Too many requests. Wait the number of seconds in the `Retry-After` header, then try again.
`5xx`	Varies	Something went wrong on our side. Safe to try again after a short wait.

Billing

The planned price is 1 credit (£0.004$0.006) for each address checked. It may change before launch.

See Credits and prices for how credits work.

Notes

A mail server can be slow to answer, and some take up to a minute. Give your HTTP client a long timeout, such as 90 seconds, and call from a background job where you can.
No email is sent: the check stops before a message would be.
Whether a domain is catch-all is remembered for 30 to 180 days.
One address per call. Checking a whole list in one call is planned but not built.

Questions about the APIs? Email pele@magpiecrm.com.