Docs · Guides

Enrich leads

You have a name and a company, from a form, a spreadsheet or a search. The finder adds a work email the company's mail server has confirmed, or tells you why it can't.

Preview: may change before launch · Updated

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.

What works today

API keys aren't issued yet. Today, MagpieCRM on Magpie Cloud does this in the app: in Prospect Search, save people to a list and their work emails are found and checked as they're saved. Over MCP, your AI app can search for the people, and you save them in the app.

What you need

  • The person's first and last name.
  • Their company's website domain, such as examplefreight.example. If you only have a company name, find its domain first: Search companies returns it.

The code

Finding a lead's email
const MAGPIE = "https://api.magpie-cloud.com/v1";

// A lead with a name and a company domain, such as from a demo request form.
export async function findEmail(lead) {
  const res = await fetch(`${MAGPIE}/find`, {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.MAGPIE_API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      first_name: lead.firstName,
      last_name: lead.lastName,
      domain: lead.domain,
    }),
    signal: AbortSignal.timeout(90_000), // up to 6 checks with a mail server
  });
  if (!res.ok) throw new Error(`Find failed: HTTP ${res.status}`);
  const { status, email } = await res.json();

  if (status === "verified") {
    return { ...lead, email, emailStatus: "verified", checkedAt: new Date().toISOString() };
  }
  // catch_all, risky, not_found or unknown: no email, and the call wasn't charged.
  return { ...lead, email: null, emailStatus: status, checkedAt: new Date().toISOString() };
}

The finder may check up to 6 addresses with the company's mail server before it answers, so run it from a background job with a long timeout, not while someone waits on a page.

What to do with each status

StatusWhat to do
verifiedUse the email. The mail server confirmed it.
catch_allDon't guess an address: the domain accepts every one, so a guess may bounce. Ask the person, or reach them another way.
riskyThe same: nothing was confirmed, so don't send to a guess.
not_foundCheck the domain is the company's real one. If it is, the person may have left, or use an address that isn't in a usual format.
unknownThe mail server didn't give a clear answer. It's free, so try again later.

Only confirmed finds are charged

A call that comes back without an email costs nothing, so it's fine to try every lead.

To find new leads rather than enrich ones you have, start with Search people. It returns each person's name and company domain, with no email. Pick the ones you want, then call the finder for each. Split the full name into first and last in the way that suits your data.

What to store

  • The email, its status, and when you found it. People change jobs, so check an older address again before you send to it.
  • Nothing for a lead without an email beyond the status, so you don't ask again too soon.
  • From a search, only the people you'll contact. See Data handling.

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