Quickstart

1. Get a key

Join early access and tell us what you'd build. We'll write when keys are ready, starting with the people who'll use them first. Until then, the free email verifier on magpiecrm.com runs the same check on one address at a time, 10 a day, and MCP works today through a MagpieCRM workspace.

2. Keep it on your server

Put the key in an environment variable on your server, not in your code. Never put it in a web page or a mobile app, where anyone can read it. The examples on these pages read it from MAGPIE_API_KEY.

export MAGPIE_API_KEY="<your API key>"

3. Make your first call

Send an address to https://api.magpie-cloud.com/v1/verify. Our verification servers ask its mail server whether the mailbox exists, and stop before an email would be sent.

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()

A slow mail server can take up to a minute to answer, so the examples give the request a long timeout. Use an address you're allowed to check, such as one at your own company.

4. Read the response

{
  "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
  }
}

• verdict is the answer: valid, invalid, catch_all, risky or unknown. valid means the mail server said the mailbox exists.
• summary says the same in a sentence you can show or log.
• checks are the steps behind it: the address's syntax, its domain, the mailbox, and whether it's a throwaway, role or free address.

Results and catch-all says what each verdict means and what to do with it.

Next steps

• Authentication: keys per app, and replacing one.
• Errors: what can go wrong, and when to try again.
• Verify sign-ups: the same call, in a sign-up form.
• Verify an email address: every field.