Docs · API reference

Find a work email

Send a first name, a last name and a company domain. The finder works out the likely addresses, checks each with the company's mail server, and answers with the one it confirms, or a status saying why there isn't one.

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/find. What it's for, and how it works: Email finder API.

Request

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

Field	Type	Required	What it is
`first_name`	string	Yes	The person's first name.
`last_name`	string	Yes	The person's last name.
`domain`	string	Yes	The company's website domain, such as `examplefreight.example`.
`country`	string	No	Two-letter code, if you know it, such as `GB`. It helps with the formats likely there.

Example

Request · POST /find

curl https://api.magpie-cloud.com/v1/find \
  -H "Authorization: Bearer $MAGPIE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "first_name": "Alex",
    "last_name": "Sample",
    "domain": "examplefreight.example"
  }'

const res = await fetch("https://api.magpie-cloud.com/v1/find", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.MAGPIE_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    first_name: "Alex",
    last_name: "Sample",
    domain: "examplefreight.example",
  }),
});
const data = await res.json();

import os
import requests

res = requests.post(
    "https://api.magpie-cloud.com/v1/find",
    json={
        "first_name": "Alex",
        "last_name": "Sample",
        "domain": "examplefreight.example",
    },
    headers={"Authorization": f"Bearer {os.environ['MAGPIE_API_KEY']}"},
    timeout=90,
)
data = res.json()

Response · 200

{
  "email": "alex.sample@examplefreight.example",
  "status": "verified",
  "pattern": "first.last"
}

At a catch-all domain nothing can be confirmed, so no email comes back, and the call isn't charged.

Response: no email confirmed

{
  "status": "catch_all",
  "email": null,
  "pattern": null
}

Response

Field	Type	What it is
`status`	string	`verified`, `catch_all`, `risky`, `not_found`, `unknown`. Only `verified` comes with an email.
`email`	string or null	The confirmed address when `status` is `verified`; otherwise `null`.
`pattern`	string or null	The format the address follows, such as `first.last`, when `status` is `verified`; 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`	A name or the domain is missing.
`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 email found. It may change before launch. A call that finds no email (any status but verified) is free.

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.
It checks up to 6 likely addresses per person, starting with the company's known format when there is one, and stops at the first the mail server confirms.
Only the company's format, such as first.last, is remembered, never the name or the address.
catch_all means the domain accepts every address, so a guess can't be confirmed there. You get no email rather than a guess.

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