API Reference · identifier

Enrich email addresses via API

Pass a work email address and get back the complete person and company behind it — verified contact data, current title, seniority, employer firmographics, and email deliverability status. Reverse email lookup powered by 15+ providers.

Endpoint

POST https://api.cleanlist.ai/v1/enrich/email

Request

POST https://api.cleanlist.ai/v1/enrich/email
Authorization: Bearer clnl_live_...
Content-Type: application/json

{
  "email": "jane@acme.com"
}

Response

{
  "id": "ev_e2p5tf9",
  "status": "completed",
  "email": {
    "address": "sarah.park@growthco.com",
    "status": "valid",
    "mx_verified": true,
    "smtp_verified": true,
    "is_catch_all": false,
    "is_disposable": false,
    "is_role_based": false,
    "risk_score": 0.05,
    "first_name": "Sarah",
    "last_name": "Park",
    "title": "Head of Growth",
    "seniority": "director",
    "company_name": "GrowthCo",
    "company_domain": "growthco.com",
    "company_industry": "Marketing Technology",
    "company_size": "51-200"
  },
  "meta": {
    "credits_used": 1,
    "providers_queried": 15,
    "providers_matched": 7,
    "confidence": 0.94,
    "enriched_at": "2026-04-15T16:42:11Z"
  }
}

Field reference

Field	Type	Description
address	string	The email address that was verified.
status	enum	Verification result: valid, invalid, risky, catch-all, disposable, role-based, unknown.
mx_verified	boolean	Whether the domain has valid MX records configured for receiving email.
smtp_verified	boolean	Whether the SMTP handshake confirmed the specific mailbox exists.
is_catch_all	boolean	Whether the domain accepts mail to any address (catch-all configuration).
is_disposable	boolean	Whether the address uses a temporary/disposable email service.
is_role_based	boolean	Whether the address is a group alias (info@, support@, admin@).
risk_score	float	0.0 to 1.0 risk score. Lower = safer to send. Factors: catch-all probability, domain age, complaint history.
first_name	string	Contact first name associated with the email address.
last_name	string	Contact last name.
title	string	Current job title of the email owner.
seniority	enum	Seniority level: entry, individual_contributor, manager, director, vp, c_level, owner.
company_name	string	Company name associated with the email domain.
company_domain	string	Company primary domain.
company_industry	string	Industry classification.
company_size	string	Employee count range.

Code samples

curl

curl -X POST https://api.cleanlist.ai/v1/enrich/email \
  -H "Authorization: Bearer $CLEANLIST_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"email": "jane@acme.com"}'

Node.js

import Cleanlist from "cleanlist";

const client = new Cleanlist(process.env.CLEANLIST_API_KEY);

const result = await client.enrich.email({
  email: "jane@acme.com",
});
console.log(result.email.title);

Python

from cleanlist import Cleanlist

client = Cleanlist(api_key=os.environ["CLEANLIST_API_KEY"])

result = client.enrich.email(email="jane@acme.com")
print(result["email"]["title"])

Common use cases

Pre-send verification

Verify every email in your outbound sequence before sending. Remove invalids, flag catch-alls, and protect your sender reputation from bounce damage.

Form submission enrichment

When a prospect submits a form with their work email, instantly enrich the record with title, company, and seniority — then route to the right rep or sequence.

CRM hygiene sweeps

Run your CRM email list through verification quarterly. Flag stale addresses, identify job changes, and update contact records before your next campaign.

Purchased list validation

Before importing a third-party lead list, verify every email to filter out the 15-30% that are typically invalid. Save credits by only enriching validated addresses.

Pricing

Credit-based, no per-seat fees. This endpoint uses the standard enrichment rate:

Email only: 1 credit per enriched email.
Email + phone: 11 credits per enriched email.
Free tier: 30 credits/mo. See all pricing.

FAQ

What is the difference between email verification and email enrichment?

Email verification confirms whether an address is deliverable (valid/invalid/risky). Email enrichment goes further: it returns the person behind the email — their name, title, seniority, and company firmographics. The emails endpoint does both in a single API call. Use it when you need both verification status and contact context.

How does catch-all detection work?

Cleanlist sends a probe to a randomly generated address at the domain during SMTP verification. If the server accepts the random address, the domain is catch-all. This means a valid SMTP response for the target address does not guarantee the mailbox exists. Catch-all addresses are flagged with is_catch_all: true and a higher risk_score.

What is the risk_score and how should I use it?

The risk_score is a 0.0 to 1.0 float that quantifies send risk. Scores below 0.1 are safe to send. Scores between 0.1 and 0.3 are moderate risk (typically catch-all domains with some positive signals). Scores above 0.3 should be excluded from cold outreach. Use risk_score to set your own bounce tolerance threshold rather than relying on binary pass/fail.

Does email verification work for personal email addresses (Gmail, Yahoo)?

Yes, but with limitations. Gmail and Yahoo use catch-all configurations for their consumer domains, so SMTP verification cannot confirm individual mailbox existence. These addresses will return status 'risky' with is_catch_all: true. For B2B outreach, focus on corporate email addresses where SMTP verification provides definitive results.

Next steps

Full REST reference: /product/api.
Related glossary: data enrichment, waterfall enrichment.
Ready to ship? Start free with 30 credits.