# Check Credits
Source: https://docs.enrichley.io/api-reference/credits/check-credits
GET /me
Check available credits for the authenticated Enrichley user.
# Check Credits
The **Check Credits** endpoint lets you see how many Enrichley credits you have remaining, along with important rate limit information.
## Endpoint
```http theme={null}
GET /me
Host: api.enrichley.io
```
This endpoint uses the same base URL as the rest of the Enrichley API:
```text theme={null}
https://api.enrichley.io/api/v1
```
## Authentication
All requests must include your API key in the `X-Api-Key` header:
```http theme={null}
X-Api-Key: YOUR_API_KEY
```
You can find your API key on your [profile page](https://app.enrichley.io/profile) after [signing up](https://app.enrichley.io/sign-up) for a paid plan.
## Response
On success, the endpoint returns a JSON body with your remaining credits:
```json theme={null}
{
"credits": 999999
}
```
In addition, a number of HTTP response headers convey rate limit and credit information:
* `x-ratelimit-limit` – Maximum number of requests allowed in the current rate limit window (for example, `100`).
* `x-ratelimit-remaining` – Number of requests remaining in the current window (for example, `99`).
* `x-ratelimit-reset` – Unix timestamp (milliseconds) when the current window resets (for example, `1700000000000`).
* `x-credits-remaining` – Number of credits remaining on your account after this request (for example, `999999`).
These headers are also modeled in the OpenAPI specification so you can inspect them directly in the API playground and in client SDKs.
# Email Validation
Source: https://docs.enrichley.io/api-reference/endpoint/email-validation
POST /validate-single-email
Validate a single email address with the Enrichley API.
# Email Validation
This endpoint validates a single email address using the Enrichley API and returns validation and enrichment data.
* **Method:** `POST`
* **Path:** `/validate-single-email`
* **Auth:** `X-Api-Key` header
The request body accepts a single field:
```json theme={null}
{
"email": "jane.doe@example.com"
}
```
A typical response includes both a JSON body and useful rate-limit / credit headers. For example:
```json theme={null}
{
"email": "jane.doe@example.com",
"valid": true,
"result": "catch_all_validated",
"mx_domain": "example.com",
"email_type": "business",
"mx_provider": "example",
"credits_consumed": true,
"mx_secure_email_gateway": true
}
```
And response headers such as:
* `x-ratelimit-limit`
* `x-ratelimit-remaining`
* `x-ratelimit-reset`
* `x-credits-remaining`
The OpenAPI specification models this endpoint so the API playground in these docs can be used to send real requests by providing your `X-Api-Key`.
# API reference
Source: https://docs.enrichley.io/api-reference/introduction
Authenticate with the Enrichley API and understand usage limits.
# Enrichley API overview
Enrichley helps you recover valid emails that other verification tools discard, especially **catch-all** and other "risky" emails. On average, 40–60% of unverified lists contain catch-all emails, and Enrichley's verification is built to recover as many of these as possible—often resulting in **20–30% more valid emails** on the same lists.
## Base URL
```text theme={null}
https://api.enrichley.io/api/v1
```
## Authentication
All requests are authenticated with an API key via the `X-Api-Key` header:
```http theme={null}
X-Api-Key: YOUR_API_KEY
```
API keys are generated automatically when you [sign up for a paid plan](https://app.enrichley.io/sign-up). Once you have a paid plan, find your key on your [profile page](https://app.enrichley.io/profile) — it works across all Enrichley APIs.
## Rate limits
* 10 requests per second
If you need higher throughput, contact support.
## Endpoints overview
The main public endpoints currently available are:
* `POST /validate-single-email` — Validate a single email address and return its validation status.
* `GET /me` — Retrieve information about your API key, including monthly and remaining credits.
# Authentication
Source: https://docs.enrichley.io/authentication
How authentication works for the Enrichley API.
# Authentication
The Enrichley API uses **API keys** to authenticate requests. Every request must include your key in the request headers; requests without a valid key will be rejected.
## Obtaining your API key
1. Log in to the [Enrichley app](https://app.enrichley.io/sign-in).
2. [Upgrade to a paid plan](https://app.enrichley.io/plans) if you haven’t already.
3. Navigate to your [account profile](https://app.enrichley.io/profile).
4. Locate the **API key** section and copy your key.
API keys are generated automatically for paid accounts and can be reused across all of your Enrichley integrations.
## Using your API key
Include your key in every API request using the `X-Api-Key` header:
```bash theme={null}
curl -X POST "https://api.enrichley.io/api/v1/validate-single-email" \
-H "Content-Type: application/json" \
-H "X-Api-Key: YOUR_API_KEY" \
-d '{
"email": "user@example.com"
}'
```
All current Enrichley endpoints expect this header:
* **Header name:** `X-Api-Key`
* **Location:** HTTP header
* **Applies to:** all Enrichley API endpoints
## Summary
* You authenticate with a single API key, passed in the `X-Api-Key` header.
* Keys are issued from your Enrichley dashboard for paid plans.
* Every request to the email validation endpoint must include this header.
## Best practices for API key security
1. **Keep it private** – Treat your API key like a password. Do not share it in public repos, support forums, or client-side code.
2. **Use environment variables** – Store keys in environment variables or a secrets manager, not directly in your code.
3. **Rotate if compromised** – If you suspect a key has leaked, regenerate it in your [Enrichley profile](https://app.enrichley.io/profile) and update your services.
4. **Limit access** – Only share the key with services and team members who absolutely need it.
# Company Lookalike
Source: https://docs.enrichley.io/discovery/company-lookalike
Turn a few seed domains into a list of similar companies — preview 25 matches free, then unlock the full enriched list at 5 credits per company.
Company Lookalike turns a handful of your best-fit customers into a list of similar companies you haven't touched yet. Feed it seed domains, refine on company and keyword matches, then run a paid search to unlock the full enriched list.
Available in the Enrichley app under **Companies → Company Lookalike**. New to the page? Click the **How To** button for a guided walkthrough.
## How it works
Paste in the domains of companies you want more of — start with 2–3 of your best customers. At least one seed domain is required to preview.
Enrichley surfaces up to **25 lookalike candidates** with limited columns visible. The preview is always free — no credits used.
Mark the preview rows that look right, review and tweak the keyword filters inferred from your seeds, then confirm everything before kicking off the paid search.
Pick a preset (1,000 / 5,000 / 10,000) or type an exact number, up to **50,000 companies per run**. Each company costs **5 credits** and comes back fully enriched.
## Preview vs. full results
Preview rows show the company, match strength, industry, website, description, and keywords. Location, employee count, revenue, funding, and categories unlock when you run a paid search.
## Pricing and limits
| Item | Value |
| ------------------ | -------------------------- |
| Company discovered | 5 credits |
| Preview | Free — up to 25 candidates |
| Companies per run | Up to 50,000 |
| Rows per export | Up to 50,000 |
Credits are reserved when a run starts and reconciled when it completes — if fewer companies come back than requested, you only pay for what was actually delivered.
## Status badges
| Badge | Meaning |
| ------------------ | ---------------------------------------------------------------- |
| **Free Preview** | You haven't paid for this discovery yet |
| **Fetching** | A paid run is in flight |
| **More available** | The run completed but there's more matching data you could fetch |
| **Complete** | You've fetched all available lookalikes for this discovery |
| **No matches** | Nothing came back — try different seeds or broaden keywords |
If your most recent attempt failed but you already have results from prior paid runs, the discovery's overall status stays the same and you'll see a small "last attempt failed" note. Your prior data and credits are unaffected — retry whenever you're ready.
## Search criteria disclosure
On any saved discovery, expand the read-only **Search criteria** section to see exactly which filters the run used — handy for audits or for spinning up a new discovery with similar criteria. Filters stay editable during free preview and lock once you run the paid search.
## Feed People Search
Lookalike results plug directly into [People Search](/discovery/people-search): use the **Lookalike source** filter to find people at the companies a lookalike run discovered.
## History
Every discovery is saved at **Lookalike History** with its coverage status, seed domains, and run count. Click in to view aggregated results or export from the row's actions menu.
## Export your results
Download a CSV, push to a Clay table via webhook, or push companies to HubSpot. See [Exporting results](/discovery/exporting-results).
## Learn more
For a step-by-step walkthrough with screenshots, see the help center article: [Company Lookalike: find companies similar to your best customers](https://help.enrichley.io/en/articles/17-company-lookalike-find-companies-similar-to-your-best-customers).
# Exporting results
Source: https://docs.enrichley.io/discovery/exporting-results
Get People Search and Company Lookalike results out of Enrichley — CSV download, Clay webhook push, or HubSpot export with field mapping and destination lists.
People Search and Company Lookalike share the same three export paths. All three are available from a search's results view and from the History pages.
Up to 50,000 rows per export. No extra plan requirement.
Send results straight into a Clay table via webhook.
Create or update Contacts and Companies, with field mapping and destination lists.
## CSV download
Open the actions menu on a search's results (or on its history row) and choose **Export CSV**. The download includes the saved rows for that search — the full enriched record for each person or company — up to **50,000 rows per export**. If you can see the results, you can download them; no extra plan is required.
For exports above the 50,000-row limit, contact [support@enrichley.io](mailto:support@enrichley.io).
## Push to Clay
Choose **Push to Clay** and paste a Clay webhook URL to send results straight into a Clay table — the same flow [Email Validation uses](/integrations/clay#push-to-clay) for validated emails. The push runs as a background job, and the same 50,000-row limit applies.
## Push to HubSpot
**Requirements:** a Professional plan or higher, and HubSpot already connected — see [Connect HubSpot](/integrations/hubspot#connect-hubspot).
Select the rows you want to push (Select-All sends the whole result set) and click **Push to HubSpot**.
Standard HubSpot properties are mapped out of the box. Adjust them if you like, and save the mapping to reuse it on future pushes.
Choose **No list** (just create or update the records), **Add to existing list**, or **Create new list**. The list options need HubSpot list permissions — if you're prompted, reconnect HubSpot to grant them; "No list" always works.
The push runs as a background job. Follow its progress in your job history.
### What gets pushed where
| Source | HubSpot object | Mapped by default | Optional Enrichley properties |
| ----------------- | -------------- | ----------------------------------------------------------------------------- | ---------------------------------------------------------------------------------- |
| People Search | Contacts | First name, last name, job title, company, LinkedIn URL, email (when present) | Phone, city, state, country |
| Company Lookalike | Companies | Name, domain, LinkedIn company page | Industry, employee count, annual revenue, description, phone, city, state, country |
Optional fields are created as [custom `enrichley_*` properties](/integrations/hubspot#custom-hubspot-properties) when you enable them in the mapping — they never overwrite HubSpot's standard properties.
### How Enrichley avoids duplicates in HubSpot
* **Contacts** — rows you've pushed before are recognized and updated. New rows are matched by email when one is present, otherwise by LinkedIn URL. Since People Search results don't include emails today, LinkedIn URL does most of the matching — once Email Finder adds emails to your saved people, email takes priority.
* **Companies** — matched by domain first, then by company LinkedIn page, then by additional domains.
When a match is found, the existing record is updated. When it isn't, a new record is created.
### Things worth knowing
* **Preview-only rows are skipped** on Company Lookalike pushes. If a row hasn't been unlocked by a paid run yet, the push warns you and excludes it.
* **Large pushes take a few minutes** — they run in the background and are automatically paced to stay within HubSpot's API quotas.
## Learn more
For a step-by-step walkthrough with screenshots, see the help center article: [Exporting discovery results: CSV, Clay, and HubSpot](https://help.enrichley.io/en/articles/18-exporting-discovery-results-csv-clay-and-hubspot).
# People Search
Source: https://docs.enrichley.io/discovery/people-search
Build a targeted list of people by role, seniority, location, company profile, and more — preview for free, then save results at 1 credit per person.
People Search builds a fresh list of people based on who you want to reach — it's for finding new leads, not cleaning an existing list. Set your filters, preview the match count for free, then run a paid search to save the people you want.
Available in the Enrichley app under **Leads → People Search**. New to the page? Click the **How To** button for a guided walkthrough.
## How it works
Combine contact filters (who the person is) with company filters (where they work). Every filter narrows the result set.
Click **Get Search Count** to see how many people match, along with a small sample. You get **100 free previews per billing cycle**; beyond that, a preview costs 10 credits. Filters stay editable while you preview.
Pick a preset (1,000 / 5,000 / 10,000) or type an exact number, up to **50,000 people per run**. Each saved person costs **1 credit**. Once a paid run starts, the filters for that search lock — start a new search to try a different cut.
**Fetch more** picks up where the search stopped. People you've already saved are excluded automatically, so you're never charged twice for the same person.
## Available filters
| Group | Filters |
| ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Contact** | Job titles (with exact vs. broader match modes), excluded job-title keywords, seniority (Manager through C-suite), locations, department & job function, LinkedIn profile badge, follower count, connection count |
| **Company** | Industries, products & services, company domains, employee count (total or by department), annual revenue, company type, company LinkedIn URLs, funding (type, amounts, and last funding date), lookalike source |
You can target a specific set of companies instead of filtering by attributes — import companies from a connected [HubSpot](/integrations/hubspot) account, or start from the companies a [Company Lookalike](/discovery/company-lookalike) run already found.
## What each person includes
Every saved person includes name, job title, company (with domain), location, industry, seniority, department, company size, annual revenue, keywords, company type, website, LinkedIn followers and connections, profile badges, and a link to their LinkedIn profile.
People Search results don't include email addresses. Finding verified emails is a separate feature, **Email Finder** — it takes a saved People Search and finds verified email addresses for those people, charging only for emails it actually finds. Email Finder is rolling out soon.
## Pricing and limits
| Item | Value |
| ------------------- | --------------------- |
| Saved person | 1 credit |
| Free previews | 100 per billing cycle |
| Additional previews | 10 credits each |
| People per run | Up to 50,000 |
| Rows per export | Up to 50,000 |
Credits are reserved when a run starts and reconciled when it finishes — if a run returns fewer people than requested, you only pay for what was actually delivered.
## Search history
Every search is saved. Open **Search History** to revisit any prior search, check its status, re-open the results, or export from the row's actions menu.
## Export your results
Download a CSV, push to a Clay table via webhook, or push contacts to HubSpot. See [Exporting results](/discovery/exporting-results).
## Learn more
For a step-by-step walkthrough with screenshots, see the help center article: [People Search: find leads by role, seniority, location, and more](https://help.enrichley.io/en/articles/16-people-search-find-leads-by-role-seniority-location-and-more).
# Introduction
Source: https://docs.enrichley.io/index
Overview of the Enrichley email validation API.
# Introduction
The Enrichley API focuses on one thing: **high-quality email validation**, with a special emphasis on validating catch-all and other “risky” email addresses. Instead of throwing away those addresses, Enrichley helps you safely recover more of your list and protect your sender reputation.
Beyond the API, the Enrichley app includes **lead discovery** — build targeted prospect lists with [People Search](/discovery/people-search) and find companies similar to your best customers with [Company Lookalike](/discovery/company-lookalike), then [export the results](/discovery/exporting-results) to CSV, Clay, or HubSpot.
## Key features
### Email validation for real-world lists
* Validate individual email addresses through the API.
* Detect and handle catch-all domains so you don’t need to discard them by default.
* Designed to keep bounce rates low while maximizing the number of usable contacts.
### Lead discovery in the app
* [People Search](/discovery/people-search) — build a list of people by role, seniority, location, company profile, and more.
* [Company Lookalike](/discovery/company-lookalike) — turn a few seed domains into a list of similar companies.
* [Export results](/discovery/exporting-results) to CSV, Clay, or HubSpot.
## Benefits
### Recover more valid emails
On many unverified lists, 40–60% of emails are considered “risky” because they’re on catch-all domains. Enrichley is designed to safely recover a large portion of those addresses, often resulting in **20–30% more valid emails** on the same list compared to traditional verification tools.
### Protect sender reputation
By validating emails before you send, you reduce hard bounces and help keep your sending domains and IPs healthy. Enrichley’s real-time checks are tuned to help keep bounce rates low when used with clean data sources.
### Use your data more efficiently
Data is expensive. Rather than discarding a large percentage of your list due to catch-all results, Enrichley lets you keep more of the prospects you’ve already paid to acquire.
## Use cases
* **Sales & marketing teams** – Clean prospect lists before campaigns and preserve valuable catch-all leads instead of deleting them.
* **Email deliverability & ops** – Monitor list quality across different sources and maintain strong sender reputation.
* **Product & engineering teams** – Integrate validation checks directly into signup flows, CRMs, and internal tools via the API.
Enrichley’s API is designed to be straightforward for developers while giving growth teams the confidence to send to more of their list.
# Apollo
Source: https://docs.enrichley.io/integrations/apollo
Use Enrichley as an email validation source inside Apollo's enrichment waterfall.
Apollo's email enrichment waterfall lets you stack a separate **validation source** on top of the data sources that find emails. Adding Enrichley as your validation source means every email Apollo surfaces is verified by Enrichley before it lands in your search results — keeping bounce rates low while you prospect.
## Why use Enrichley inside Apollo
* **Validate every email Apollo finds, automatically.** No second tool, no separate workflow.
* **Choose how you pay.** Use Apollo credits, or connect your Enrichley API key to use your Enrichley credits instead.
* **Save money.** Using your own Enrichley key is typically much cheaper per validation than Apollo's bundled credits — especially if you already have an Enrichley plan.
## Plan requirements
You can use Enrichley inside Apollo without an Enrichley account by paying with Apollo credits. To use your own API key (recommended for cost savings), you need any paid [Enrichley plan](https://app.enrichley.io/plans).
## Setup
Go to **Find people** (or any saved search) inside Apollo.
Hover the **Emails** column header and click the chart icon to open **Email enrichment**, then click the gear/settings icon to open the full configuration panel.
Scroll to **Validation source (optional)** and click **Add**. Select **Enrichley** from the provider list.
By default, Enrichley validations are billed to your Apollo credits. To use your Enrichley credits instead (cheaper), click **Connect with API key** next to Enrichley and paste your [Enrichley API key](https://app.enrichley.io/profile).
Click **Save**. Apollo will now route every email it finds through Enrichley before showing it as **Verified** in your results.
Apollo lets you choose when validation kicks in: **A verified email is found** (highest credit usage, single validation per record) or **Any email is found** (lower credit usage, validates whatever Apollo's data sources return). Pick based on your accuracy vs. cost preference.
## Credit usage
When using your Enrichley API key inside Apollo, **1 Enrichley credit** is consumed per validated email. Apollo's data-source credits (1–3 per enriched record) still apply for finding the email.
## Get help
* **Apollo support:** see Apollo's documentation for the People Search and Enrichment Waterfall settings.
* **Enrichley support:** [support@enrichley.io](mailto:support@enrichley.io)
* **View Enrichley on Apollo:** [apollo.io/product/integrations/enrichley](https://www.apollo.io/product/integrations/enrichley)
# Cargo
Source: https://docs.enrichley.io/integrations/cargo
Verify emails inside Cargo's multi-agent workflows with Enrichley.
Cargo turns data into action with multi-agent workflows. The Enrichley app inside Cargo gives those workflows email validation as a building block — verify deliverability, classify risk, and route emails to the right next step.
## What you can do
| Action | Description |
| ---------- | ----------------------------------------------------------------------------------------- |
| **Verify** | Validate a single email address. Returns deliverability status, validity, and risk level. |
## Plan requirements
A paid [Enrichley plan](https://app.enrichley.io/plans) with API access is required.
## Setup
Copy your API key from your [Enrichley profile](https://app.enrichley.io/profile).
In Cargo, add a step that uses the Enrichley integration. When prompted, paste your Enrichley API key.
Set the **Object type** to `Email` and pass the email address you want to validate as the input.
Cargo calls Enrichley for each email and returns the validation result, which downstream steps in your workflow can branch on.
## Credit usage
Cargo bills **0.1 credit per Verify call** against your Enrichley balance.
## Use cases
* **List cleaning** — validate large contact lists before they enter a sequence.
* **Lead validation** — gate inbound leads on deliverable email addresses.
* **Deliverability optimization** — route risky and unknown emails through alternative outreach channels.
## Get help
* **Cargo documentation:** [docs.getcargo.ai/integration/enrichley](https://docs.getcargo.ai/integration/enrichley)
* **Enrichley support:** [support@enrichley.io](mailto:support@enrichley.io)
# Clay
Source: https://docs.enrichley.io/integrations/clay
Use Enrichley as a Clay data provider, or push validated data from Enrichley back to Clay.
Enrichley and Clay work together in two complementary ways:
1. **Enrichley as a data provider in Clay** — call Enrichley's email validation from inside Clay tables, paying with either Clay credits or your own Enrichley credits.
2. **Push to Clay from Enrichley** — push results into a Clay table via webhook, from a completed validation job or from [People Search](/discovery/people-search) and [Company Lookalike](/discovery/company-lookalike) results.
You can use one or both depending on how your team works.
***
## Enrichley in Clay
Use Enrichley as one of Clay's enrichment providers. Inside any Clay table, add an Enrichley enrichment to validate emails alongside the rest of your Clay workflow.
### Why use your own Enrichley API key
Clay supports two billing modes for Enrichley enrichments:
| Mode | How you pay | When to choose it |
| ---------------------------------- | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| Clay-managed account (default) | Clay credits | One-off testing, no Enrichley account |
| **Your own API key (recommended)** | Enrichley credits | You already have an Enrichley plan and want to save money — Enrichley credits are typically much cheaper than Clay's bundled credits |
### Plan requirements
You can use Enrichley in Clay without an Enrichley account by paying with Clay credits. To use your own API key, you need any paid [Enrichley plan](https://app.enrichley.io/plans).
### Setup
Sign in to [Enrichley](https://app.enrichley.io/sign-in) and copy your key from your [profile](https://app.enrichley.io/profile).
In your Clay table, click **Add Enrichment** and search for **Enrichley**.
Click **Add new account** → **Use your own API key** → paste your Enrichley API key.
Pick the column to validate and run the enrichment. Validations consume your Enrichley credits, not Clay credits.
Place Enrichley early in your Clay waterfalls. High validation accuracy means fewer fallback calls to expensive backup providers.
***
## Push to Clay
Run a validation job in Enrichley, then push the results to a Clay table via webhook. Useful when Enrichley is your validation hub and Clay is where your team operates downstream.
The same flow works for discovery results — see [Push discovery results](#push-discovery-results) below.
### Plan requirements
A paid [Enrichley plan](https://app.enrichley.io/plans) is required.
### Setup
In Clay, create or open the table you want to receive validated rows. Add a **Webhook** source and copy its URL — it will look like `https://api.clay.com/v3/sources/webhook/...`.
Upload a list to Enrichley and run email validation. Wait for the job to complete.
From the completed job's actions, click **Push to Clay**.
Paste the webhook URL you copied from Clay.
Pick **Valid only** (only emails marked `ok` or `catch_all_validated`) or **All emails** (every result, including invalid and unknown). Click **Submit** to start the push.
### What gets pushed
Each row is sent to Clay as a JSON object with the original input columns plus Enrichley's validation fields:
* `email` — the email that was validated
* `result_status` — `ok`, `catch_all_validated`, `catch_all`, `invalid`, or `unknown`
* `valid` — boolean
* `mx_domain`, `mx_provider`, `email_type` — MX and classification info
* Plus any custom columns from your original input
### Reliability
Enrichley retries failed pushes automatically (up to 3 attempts per row, with exponential backoff) and respects Clay's rate-limit response. If a row can't be delivered after retries, it's logged so you can re-run the push or contact support.
Enrichley does not store your Clay webhook URLs. You'll paste the URL each time you push a job.
## Push discovery results
[People Search](/discovery/people-search) and [Company Lookalike](/discovery/company-lookalike) results can be pushed to Clay the same way: open the actions menu on a search's results (or its history row), choose **Push to Clay**, and paste your Clay webhook URL. Instead of validation fields, each row carries the person or company record from the search.
Discovery pushes run as background jobs and support up to **50,000 rows per export**. See [Exporting results](/discovery/exporting-results) for details.
## Get help
* **Clay's listing for Enrichley:** [clay.com/integrations/data-provider/enrichley](https://www.clay.com/integrations/data-provider/enrichley)
* **Enrichley support:** [support@enrichley.io](mailto:support@enrichley.io)
# HubSpot
Source: https://docs.enrichley.io/integrations/hubspot
Native bi-directional sync — import contacts and companies from HubSpot, validate them, and export results back.
The Enrichley HubSpot integration is in beta. Setup steps and capabilities may evolve as we add features.
The Enrichley HubSpot integration lets you move contacts and companies between Enrichley and HubSpot so you can validate, enrich, and clean data before it powers your campaigns.
Pull contacts, companies, and lists from HubSpot into Enrichley for validation and enrichment.
Push validated and enriched data back to HubSpot — with field mapping, duplicate handling, and a guided wizard.
Create custom HubSpot properties on the fly during export to capture validation results and enrichment fields.
## Plan requirements
The HubSpot integration is available on **Professional, Scale, Advanced, Growth, and Ultimate** Enrichley plans. **Starter plans do not include HubSpot access** — [upgrade your plan](https://app.enrichley.io/plans) to enable the integration.
You also need permission inside HubSpot to authorize OAuth applications.
## Connect HubSpot
In Enrichley, go to [Integrations → HubSpot](https://app.enrichley.io/integrations/hubspot) and click **Connect**.
You'll be redirected to HubSpot's login page. Sign in with your HubSpot credentials.
If you have access to multiple HubSpot accounts, select the one you want to connect and click **Choose Account**.
Review the permissions Enrichley is requesting — read and write access to contacts, companies, and lists. Click **Connect app** to approve.
Type **"I accept the risk"** in the text field and click **Connect** to proceed past HubSpot's verification warning.
You'll see a success message and be redirected back to Enrichley. Your Hub Domain and granted scopes will appear on the [HubSpot integration page](https://app.enrichley.io/integrations/hubspot).
## Using the integration
All imports and exports are **manual** — there are no automated syncs. You control when data moves between Enrichley and HubSpot.
### Import from HubSpot
Pull HubSpot data into Enrichley to validate or enrich it. You can import:
* **Contacts** — contact records from your HubSpot CRM
* **Companies** — company records from your HubSpot CRM
* **Lists** — specific HubSpot contact lists
Imports are available from the Email Validation and [People Search](/discovery/people-search) workflows in Enrichley — for example, importing a HubSpot company list to target with People Search.
### Export to HubSpot
Push validated and enriched data back to HubSpot using the guided 8-step export wizard:
Pick a saved snapshot or completed validation job as the source data.
Map your Enrichley columns to HubSpot contact or company properties. Save mappings to reuse them on future exports.
Enrichley shows you matches, conflicts, and how many records will be created vs. updated.
For ambiguous matches, choose how to handle each one (update, skip, or create new).
Final review before execution.
If you mapped fields to properties that don't exist yet, Enrichley creates the custom HubSpot properties for you.
Execute the export job. Progress streams in real time on the Sync History page.
Review the completion summary — records created, records updated, any failures.
### Push discovery results to HubSpot
[People Search](/discovery/people-search) and [Company Lookalike](/discovery/company-lookalike) results push to HubSpot through a lighter flow than the validation export wizard: select rows (or Select-All), review the field mapping, pick a destination list (**No list**, **Add to existing list**, or **Create new list**), and run the push as a background job.
* People Search rows create or update HubSpot **Contacts**, matched by email when present, otherwise by LinkedIn URL.
* Company Lookalike rows create or update HubSpot **Companies**, matched by domain first, then by company LinkedIn page, then by additional domains.
See [Exporting results](/discovery/exporting-results#push-to-hubspot) for the full field mappings and duplicate-handling details.
### Custom HubSpot properties
When you map an Enrichley field to a HubSpot property that doesn't exist, Enrichley can create it for you during the **Prepare** step (requires the `crm.schemas.*.write` scope, which is requested by default).
Custom properties you create through Enrichley follow HubSpot's naming conventions (lowercase, alphanumeric, underscores) and are typically grouped under an `enrichley_*` prefix so they're easy to find in HubSpot.
### Saved field mappings
Save your field mappings during the export wizard to reuse them on future exports without remapping every column.
### Sync history
Every export job appears on the **Sync History** page with status (queued, running, succeeded, failed), progress, and a link to the detailed job page where you can see per-record results.
## Limits
| Limit | Default |
| ------------------------------- | ------- |
| Records per import | 50,000 |
| Records per filtered validation | 10,000 |
If you need higher limits, contact [support@enrichley.io](mailto:support@enrichley.io).
## Disconnect
You can disconnect HubSpot from Enrichley at any time.
Go to [Integrations → HubSpot](https://app.enrichley.io/integrations/hubspot) in Enrichley.
Confirm the disconnection when prompted.
Disconnecting removes the ability to import or export data between Enrichley and HubSpot. **Your HubSpot data is not affected** — Enrichley only loses access.
### Delete integration data
If you also want to remove all integration data Enrichley has stored (saved mappings, import/export history, job logs), use **Delete All Data** in the **Danger Zone** section of the HubSpot integration page.
Deleting integration data does **not** alter your HubSpot account. It only removes data Enrichley has stored about your past imports, exports, and mappings.
## Uninstall from HubSpot
To remove Enrichley from your HubSpot account entirely:
In HubSpot, go to **Settings**.
Navigate to **Integrations → Connected Apps**.
Locate **Enrichley** in your list of connected apps.
Click the **Actions** dropdown and select **Uninstall**.
Uninstalling Enrichley does not affect your HubSpot data. You can reconnect anytime by following the setup steps above.
## Get help
If you run into trouble or have questions about the HubSpot integration, contact [support@enrichley.io](mailto:support@enrichley.io).
# Lindy
Source: https://docs.enrichley.io/integrations/lindy
Add Enrichley email validation to your Lindy AI agents.
Lindy lets you build AI agents that automate work across hundreds of integrations. The Enrichley action gives those agents email validation as a first-class capability — useful for any agent that touches contacts, leads, or inbox triage.
## What you can do
| Action | Description |
| ------------------ | --------------------------------------------------------------------------- |
| **Validate Email** | Verify an email address's deliverability and classification with Enrichley. |
## Plan requirements
A paid [Enrichley plan](https://app.enrichley.io/plans) with API access is required.
## Setup
Copy your API key from your [Enrichley profile](https://app.enrichley.io/profile).
In Lindy, edit the agent you want to add validation to. Add an action and search for **Enrichley**.
Paste your Enrichley API key when prompted.
Pass the email address (typically a variable from an upstream trigger) into the action.
Branch your Lindy agent on the validation result — for example, only continue if the email is `ok` or `catch_all_validated`.
## Use cases
* **Inbox triage** — only respond to or route messages from valid email addresses.
* **Lead qualification** — verify form submissions before passing them to sales.
* **Outbound campaigns** — clean lists generated by other Lindy agents before sending.
## Get help
* **Lindy's listing for Enrichley:** [lindy.ai/integrations/enrichley](https://www.lindy.ai/integrations/enrichley)
* **Enrichley support:** [support@enrichley.io](mailto:support@enrichley.io)
# Integrations
Source: https://docs.enrichley.io/integrations/overview
Connect Enrichley to your sales, marketing, and automation stack.
Use Enrichley wherever you already work. Enrichley plugs into popular sales, marketing, and automation platforms so you can validate emails and enrich contacts without writing code.
Use Enrichley as a validation source inside Apollo's email enrichment waterfall.
Verify emails inside Cargo's multi-agent workflows.
Use Enrichley as a Clay data provider, or push validated data from Enrichley back to Clay.
Native bi-directional sync — import contacts, validate, and export back to HubSpot.
Add email validation to your Lindy AI agents.
Validate emails inside any Pipedream workflow.
Connect Enrichley to 6,000+ apps via Zapier.
## How integrations work
Enrichley integrations come in two flavors. Knowing which you're using helps you understand where setup happens and how credits are billed.
**Built and maintained by Enrichley.** You configure these inside the Enrichley app. Data flows directly between Enrichley and the partner platform.
* [HubSpot](/integrations/hubspot) — bi-directional sync of contacts and companies
* [Clay (push to Clay)](/integrations/clay#push-to-clay) — outbound export from a completed validation job or a [discovery search](/discovery/exporting-results)
These integrations are part of your Enrichley plan and use your Enrichley credits for any validation work.
**Built by partners, powered by your Enrichley API key.** You configure these inside the partner's product. The partner calls the Enrichley API on your behalf.
* [Apollo](/integrations/apollo) and [Clay (data provider)](/integrations/clay#enrichley-in-clay) let you choose between partner credits or your own Enrichley API key. Using your Enrichley key is usually significantly cheaper.
* [Zapier](/integrations/zapier), [Pipedream](/integrations/pipedream), [Lindy](/integrations/lindy), and [Cargo](/integrations/cargo) require an Enrichley API key — they call our API directly.
## Plan requirements
| Integration | Requires |
| --------------------------------- | ---------------------------------------------------------------------------------------------- |
| HubSpot | Professional, Scale, Advanced, Growth, or Ultimate plan (Starter not supported) |
| Clay (push to Clay) | Any paid Enrichley plan |
| Apollo | Optional — works with Apollo credits, or a paid Enrichley plan if you want to use your API key |
| Clay (Enrichley as data provider) | Optional — works with Clay credits, or a paid Enrichley plan if you want to use your API key |
| Zapier, Pipedream, Lindy, Cargo | Any paid Enrichley plan with API access |
Get your API key from your [Enrichley profile](https://app.enrichley.io/profile). [Sign up](https://app.enrichley.io/sign-up) or [upgrade your plan](https://app.enrichley.io/plans) if you don't have one yet.
## Don't see your tool?
If your platform supports remote MCP servers, connect via the [Enrichley MCP Server](/mcp/overview). Otherwise, every Enrichley capability is available through the [REST API](/api-reference/introduction) — point any HTTP-capable tool at it with your API key.
# Pipedream
Source: https://docs.enrichley.io/integrations/pipedream
Validate emails inside any Pipedream workflow.
Pipedream is an integration platform built for developers — connect APIs, schedule jobs, and build serverless workflows fast. The Enrichley component lets any Pipedream workflow validate an email with a single step.
## What you can do
| Action | Description |
| ------------------ | ------------------------------------------------------------- |
| **Validate Email** | Check the validity of a single email address using Enrichley. |
## Plan requirements
A paid [Enrichley plan](https://app.enrichley.io/plans) with API access is required.
## Setup
Copy your API key from your [Enrichley profile](https://app.enrichley.io/profile).
In your Pipedream workflow, click **+ Add a step** → search for **Enrichley** → select **Validate Email**.
Click **Connect Enrichley** and paste your Enrichley API key.
Pass the email to validate — usually from an upstream trigger or workflow variable — into the action's `email` field.
Run a test event. The action returns the full Enrichley validation response, which downstream steps can branch on.
## Use cases
* **Form submission validation** — validate emails as soon as a form is submitted (HTTP trigger), then branch.
* **Scheduled list cleaning** — run a Pipedream cron that pulls a list, validates each email, and writes results back.
* **Multi-tool orchestration** — combine Enrichley with any of Pipedream's 3,000+ other integrations.
## Get help
* **Pipedream's listing for Enrichley:** [pipedream.com/apps/enrichley](https://pipedream.com/apps/pipedream/integrations/enrichley)
* **Enrichley support:** [support@enrichley.io](mailto:support@enrichley.io)
# Zapier
Source: https://docs.enrichley.io/integrations/zapier
Connect Enrichley to 6,000+ apps via Zapier.
Zapier connects Enrichley to virtually every SaaS tool. Add the **Validate Single Email** action to any Zap and you can validate emails as part of any workflow — from form submissions to CRM updates to Slack notifications.
## What you can do
| Action | Description |
| ------------------------- | ------------------------------------------------ |
| **Validate Single Email** | Validates a single email address with Enrichley. |
There are no triggers — Enrichley is used as an action inside Zaps triggered by other apps.
## Plan requirements
A paid [Enrichley plan](https://app.enrichley.io/plans) with API access is required.
## Setup
Copy your API key from your [Enrichley profile](https://app.enrichley.io/profile).
In Zapier, create a new Zap or open one you want to add validation to.
Add an action step → search for **Enrichley** → select **Validate Single Email**.
Click **Connect a new account** and paste your Enrichley API key.
Map the email address from your trigger step to the **Email** input.
Run a test, confirm the validation result returns as expected, then turn on the Zap.
## Use cases
* **Validate form submissions in real time** — Typeform, Webflow, Google Forms → Enrichley → CRM.
* **Clean new CRM contacts** — HubSpot, Salesforce, Pipedrive create → Enrichley → update record.
* **Pre-send safety checks** — Mailchimp, Klaviyo new subscriber → Enrichley → tag or suppress invalid addresses.
## Get help
* **Zapier's listing for Enrichley:** [zapier.com/apps/enrichley/integrations](https://zapier.com/apps/enrichley/integrations)
* **Enrichley support:** [support@enrichley.io](mailto:support@enrichley.io)
# Making API calls
Source: https://docs.enrichley.io/making-api-calls
How to make your first request to the Enrichley API.
# Making API calls
This guide walks you through making your first request to the Enrichley email validation API. Whether you are new to APIs or an experienced developer, the steps below will help you integrate Enrichley quickly.
## Quick start
### 1. Obtain your API key
1. Log in to the [Enrichley app](https://app.enrichley.io/sign-in).
2. [Sign up](https://app.enrichley.io/sign-up) for a paid plan if you haven’t already.
3. Go to your [account profile](https://app.enrichley.io/profile) and locate your **API key**.
4. Copy the key and store it securely.
API keys are generated automatically when you sign up for a paid plan and can be used across all Enrichley APIs.
### 2. Make your first API call
Use any HTTP client (curl, Postman, your backend language, etc.) to call the single email validation endpoint:
```bash theme={null}
curl -X POST "https://api.enrichley.io/api/v1/validate-single-email" \
-H "Content-Type: application/json" \
-H "X-Api-Key: YOUR_API_KEY" \
-d '{
"email": "user@example.com"
}'
```
* **URL:** `https://api.enrichley.io/api/v1/validate-single-email`
* **Method:** `POST`
* **Auth header:** `X-Api-Key: YOUR_API_KEY`
### 3. Check the response
A successful request returns a JSON object describing the status of the email address (for example, whether it’s valid and whether the domain is catch-all). The exact fields depend on your integration, but typically you’ll see:
* Whether it's valid (`true`or `false` ).
* The status of the email ( `ok `,`catch_all_validated`,`catch_all`,`unknown`,` or invalid )`
* Statuses `ok` and `catch_all_validated` are the only valid emails, the rest should not be emailed.
Use this response to decide how to treat the email in your application (send, suppress, or review).
> 💡 **Keep your key secret:** Treat your API key like a password. Never commit it to public repositories, client-side code, or share it in screenshots or support tickets.
# Authentication
Source: https://docs.enrichley.io/mcp/authentication
How OAuth sign-in and account authorization work for the Enrichley MCP server.
The Enrichley MCP server uses OAuth 2.1 with PKCE to authorize AI clients. You sign in once per client, and your Enrichley API key stays server-side — your AI assistant never sees it.
Industry-standard OAuth 2.1 with PKCE. Your AI client receives a short-lived token, not your API key.
Your account credential is resolved server-side, never exposed to the AI client or returned in tool responses.
Validation calls deduct from the same credit balance as the Enrichley REST API.
## How it works
When you connect Enrichley to a new client, it opens a browser window to begin the OAuth flow.
Sign in to your Enrichley account in the browser.
The server confirms your Enrichley account, plan, and API credential are ready before completing the flow.
Your AI client only receives a short-lived OAuth token — never the API key itself.
When your assistant calls a tool, the server refreshes the backend grant, calls the Enrichley API on your behalf, and returns the result.
## Account requirements
You need an Enrichley account on a paid plan. The MCP server resolves your account credential server-side; you do not paste an API key into the MCP authorization flow.
## Scopes
When you authorize an AI client, you grant the following scopes:
| Scope | What it allows |
| ---------------- | -------------------------------------------------- |
| `account.read` | Read your remaining credits and rate-limit window. |
| `validation.run` | Validate email addresses (consumes credits). |
Both scopes are requested by default. The same scopes apply to every connected client.
## Security best practices
Treat your API key like a password. Never paste it into a chat, share it in screenshots, or commit it to a public repo.
* **Use your own paid Enrichley account.** Usage and credits are billed to the signed-in account.
* **Rotate your key if you think it has leaked.** Generating a new key on your [Enrichley profile](https://app.enrichley.io/profile) immediately invalidates the old one.
* **Disconnect MCP clients you no longer use.** Each client holds its own OAuth token; revoke them when you stop using a device or workspace.
## Disconnecting and revoking access
You have three ways to revoke access:
1. **Disconnect inside your AI client.**
* **Claude Code:** run `/mcp` and clear authentication for `enrichley`.
* **Cursor:** disable the Enrichley server in the MCP panel.
* **MCP Inspector:** close the session.
2. **Rotate your Enrichley API key.** Generate a new key on your [Enrichley profile](https://app.enrichley.io/profile). The old key is revoked immediately, and existing MCP clients may need to reconnect.
3. **Contact support.** Email [support@enrichley.io](mailto:support@enrichley.io) if you need help revoking access for a specific client or session.
## Authentication errors
If something goes wrong during connection or a tool call, you may see one of these:
| Error | What it means | What to do |
| ---------------------- | ---------------------------------------------------------------------------- | -------------------------------------------------------------------- |
| `Account not eligible` | The signed-in account does not have an active plan or ready API credential. | Sign in with the right account or upgrade your plan, then reconnect. |
| `Credential not ready` | The account API credential is missing, disabled, or temporarily unavailable. | Check your Enrichley profile, then reconnect the client. |
| `Session expired` | Your AI client's OAuth token has expired. | Reconnect the client to refresh the token. |
| `Unauthorized` | The client did not include a valid token. | Run the setup flow again for that client. |
## Next steps
Connect the MCP server to your AI client.
See what each tool does and how credits work.
# Enrichley MCP Server
Source: https://docs.enrichley.io/mcp/overview
Use Enrichley email validation directly inside Claude, Cursor, and other AI assistants.
The Enrichley MCP server lets your AI assistant validate emails and check your account status without leaving the conversation. Connect once, then ask your assistant to validate a list of emails or check your remaining credits in plain language.
The Enrichley MCP server is in public beta. Setup steps and the server URL may change as we add features.
Connect Enrichley MCP to Claude Code, Cursor, VS Code, or Codex in a couple of minutes.
The two tools, what they cost, and example agent prompts.
How OAuth sign-in and account authorization work, plus security best practices.
Common issues and how to fix them.
## What you can do
Once connected, ask your AI assistant things like:
* *"Validate these emails: [john@acme.com](mailto:john@acme.com), [jane@stripe.com](mailto:jane@stripe.com), [bob@notion.so](mailto:bob@notion.so)"*
* *"Check my Enrichley credit balance."*
* *"Is [jane.doe@example.com](mailto:jane.doe@example.com) a valid email I can send to?"*
Your assistant calls the Enrichley API on your behalf, returns the validation result, and tells you how many credits you have left.
## Supported clients
The Enrichley MCP server works with any client that supports remote MCP servers over Streamable HTTP and OAuth.
| Client | Status |
| ----------- | --------- |
| Claude Code | Supported |
| Cursor | Supported |
| VS Code | Supported |
| Codex CLI | Supported |
## How it works
Use the install command for your client (see [Setup](/mcp/setup)).
Your browser opens. Sign in to your Enrichley account and authorize the requested scopes. Your API key stays server-side — your AI client never sees it.
Subsequent requests reuse the same authorization. You only do this once per client.
## MCP endpoint
```text theme={null}
https://mcp.enrichley.io/mcp
```
Connect Enrichley MCP to your AI assistant.
# Setup
Source: https://docs.enrichley.io/mcp/setup
Connect Enrichley MCP to Claude Code, Cursor, and MCP Inspector.
Connect the Enrichley MCP server to your AI assistant in a couple of minutes. You will need an Enrichley account on a paid plan.
## Prerequisites
* An Enrichley paid plan ([sign up](https://app.enrichley.io/sign-up)).
* An AI client that supports remote MCP servers with OAuth (Claude Code, Cursor, VS Code, or Codex).
## MCP endpoint
Use this URL wherever your client asks for the MCP server URL:
```text theme={null}
https://mcp.enrichley.io/mcp
```
## Client setup
Add the server with the Claude Code CLI:
```sh theme={null}
claude mcp add --transport http enrichley https://mcp.enrichley.io/mcp
```
Then open Claude Code and run:
```text theme={null}
/mcp
```
Follow the browser prompt to sign in to your Enrichley account and authorize the requested scopes. Claude Code stores and refreshes the OAuth token on your machine.
**Scope options**
Pass `--scope` to control where the server is available and where the config is stored:
| Flag | Scope | Config file |
| ------------------------- | -------------------- | --------------------------- |
| `--scope local` (default) | Current project only | `~/.claude.json` |
| `--scope project` | Shared with team | `.mcp.json` in project root |
| `--scope user` | All your projects | `~/.claude.json` |
Example — share with your team via the project-level config:
```sh theme={null}
claude mcp add --scope project --transport http enrichley https://mcp.enrichley.io/mcp
```
Each teammate still completes the OAuth flow with their own Enrichley account.
**Alternative — add via JSON**
```sh theme={null}
claude mcp add-json enrichley '{"type":"http","url":"https://mcp.enrichley.io/mcp"}'
```
**Project-local `.mcp.json`**
If you prefer to commit the config directly, drop this in your repo root:
```json theme={null}
{
"mcpServers": {
"enrichley": {
"type": "http",
"url": "https://mcp.enrichley.io/mcp",
"oauth": {
"scopes": "account.read validation.run"
}
}
}
}
```
Use the `/mcp` menu in Claude Code to clear authentication or reconnect.
Add the Enrichley server to your Cursor MCP configuration.
**File:** `.cursor/mcp.json` (project-level) or `~/.cursor/mcp.json` (global)
```json theme={null}
{
"mcpServers": {
"enrichley": {
"url": "https://mcp.enrichley.io/mcp"
}
}
}
```
Open `.cursor/mcp.json` in your project root, or `~/.cursor/mcp.json` for all projects.
Save the file.
Restart Cursor, enable the Enrichley server in the MCP/tools panel, and complete the OAuth browser flow when prompted.
Use the project-level config (`.cursor/mcp.json`) to scope Enrichley to a single repo. Use the global config (`~/.cursor/mcp.json`) to make it available everywhere.
VS Code's built-in MCP client supports remote HTTP servers with OAuth.
**File:** `.vscode/mcp.json` (workspace) or open the user `mcp.json` via `Cmd+Shift+P` → **MCP: Open User Configuration**
```json theme={null}
{
"servers": {
"enrichley": {
"type": "http",
"url": "https://mcp.enrichley.io/mcp"
}
}
}
```
Add `.vscode/mcp.json` to your workspace, or open the user-level file via the command palette.
Save the file. VS Code picks up MCP server changes automatically.
Run **MCP: List Servers** from the command palette, select `enrichley`, and complete the browser sign-in.
VS Code uses `"servers"` (not `"mcpServers"`) and requires `"type": "http"` for remote servers.
The OpenAI Codex CLI supports remote streamable HTTP MCP servers with OAuth.
**Quick install** — register the server, then complete the OAuth login:
```sh theme={null}
codex mcp add enrichley \
--url https://mcp.enrichley.io/mcp \
--scopes account.read,validation.run
codex mcp login enrichley
```
`codex mcp login` opens your browser to sign in to Enrichley and authorize the requested scopes. After it completes, run `codex mcp list` to confirm the server is connected.
**Manual config**
Edit `~/.codex/config.toml` (user-level) or `.codex/config.toml` in your project root (project-level, trusted projects only):
```toml theme={null}
[mcp_servers.enrichley]
url = "https://mcp.enrichley.io/mcp"
scopes = ["account.read", "validation.run"]
```
After saving, run `codex mcp login enrichley` to complete the OAuth flow.
If you run multiple OAuth-protected MCP servers and need a fixed callback port (for example, behind a corporate proxy), set `mcp_oauth_callback_port` at the top level of `~/.codex/config.toml`. Otherwise Codex picks an ephemeral port automatically.
Need to test the server outside of an AI client? See [Debugging with MCP Inspector](/mcp/troubleshooting#debugging-with-mcp-inspector).
## More clients
Beyond the four clients above, the Enrichley MCP server has been validated against these additional MCP-compatible clients. Pick your client below for setup details.
Amazon Q Developer CLI supports remote HTTP MCP servers with OAuth.
**Config file:** `~/.aws/amazonq/mcp.json` (global) or `.amazonq/mcp.json` (workspace)
```json theme={null}
{
"mcpServers": {
"enrichley": {
"type": "http",
"url": "https://mcp.enrichley.io/mcp"
}
}
}
```
After saving, start a Q CLI session with an agent that includes this server. Run `/mcp` — Q CLI will mark the server as "not yet loaded" and provide an authorization URL. Open it in your browser, sign in to Enrichley, and authorize the requested scopes.
Cline supports remote HTTP MCP servers via the `streamableHttp` transport, including OAuth.
Open the Cline panel → **Configure** → **Configure MCP Servers**, and add:
```json theme={null}
{
"mcpServers": {
"enrichley": {
"type": "streamableHttp",
"url": "https://mcp.enrichley.io/mcp"
}
}
}
```
On first connect, Cline displays an OAuth URL in VS Code. Click it to complete sign-in in your browser. Cline stores credentials securely and reconnects automatically when you reload.
Gemini CLI supports remote HTTP MCP servers with OAuth via auto-discovery.
**Config file:** `~/.gemini/settings.json` (user) or `.gemini/settings.json` (project)
```json theme={null}
{
"mcpServers": {
"enrichley": {
"url": "https://mcp.enrichley.io/mcp"
}
}
}
```
Gemini CLI auto-detects HTTP transport, falls back to SSE if needed, and discovers the OAuth flow from the server's protected-resource metadata. On first use it opens your browser for sign-in.
JetBrains AI Assistant supports remote MCP servers with OAuth 2.1 + PKCE in version 2025.2 and newer.
Open **Settings → Tools → AI Assistant → Model Context Protocol (MCP)** and add a new server, or edit the JSON config directly:
```json theme={null}
{
"mcpServers": {
"enrichley": {
"url": "https://mcp.enrichley.io/mcp"
}
}
}
```
When you first invoke an Enrichley tool, the IDE opens your browser to complete the OAuth flow. Tokens are stored and refreshed automatically.
Requires AI Assistant 2025.2 or newer for full OAuth + Streamable HTTP support.
Roo Code's native `streamable-http` transport does not yet trigger OAuth flows reliably on a 401 challenge ([tracked in Issue #8119](https://github.com/RooCodeInc/Roo-Code/issues/8119)). Until that ships, use [`mcp-remote`](https://github.com/geelen/mcp-remote) as a local stdio bridge — it handles OAuth on Roo Code's behalf.
Open Roo Code's MCP settings and add:
```json theme={null}
{
"mcpServers": {
"enrichley": {
"command": "npx",
"args": [
"-y",
"mcp-remote",
"https://mcp.enrichley.io/mcp"
]
}
}
}
```
`mcp-remote` opens your browser for OAuth on first run and caches tokens locally. Once Roo Code adds native OAuth 2.1 support, you can switch to a direct HTTP config.
Zed supports remote HTTP MCP servers with OAuth. Note that Zed uses **`context_servers`** in its config (not `mcpServers`).
Open Zed's settings (`Cmd+,` on macOS) and add:
```json theme={null}
{
"context_servers": {
"enrichley": {
"url": "https://mcp.enrichley.io/mcp"
}
}
}
```
When no `Authorization` header is configured, Zed initiates the standard MCP OAuth flow on first use.
There are open reports of Zed's OAuth flow not always triggering reliably ([Issue #43162](https://github.com/zed-industries/zed/issues/43162)). If you hit this, fall back to [`mcp-remote`](https://github.com/geelen/mcp-remote) as a stdio bridge.
### Not currently supported
**GitHub Copilot Coding Agent** cannot be used with the Enrichley MCP server. Per [GitHub's documentation](https://docs.github.com/en/copilot/concepts/agents/coding-agent/mcp-and-coding-agent), the Copilot cloud agent does not support remote MCP servers that use OAuth for authentication. We will revisit this when GitHub adds OAuth support.
### Other MCP-compatible clients
The Enrichley MCP server works with any client that implements **Streamable HTTP transport with OAuth 2.1 + PKCE**. If your client meets that bar, point it at:
```text theme={null}
https://mcp.enrichley.io/mcp
```
Static-API-key client configurations (using a header field like `x-api-key`) are **not** supported. The Enrichley MCP server requires OAuth.
If you get it working with a client we haven't documented, let us know at [support@enrichley.io](mailto:support@enrichley.io) and we'll add it.
## Verify the connection
Ask your AI assistant:
> *"Check my Enrichley credit balance."*
Your assistant should call the `enrichley_get_account_status` tool and return your remaining credits and current rate-limit window. This call is free — it does not consume credits.
If it works, you're done. If not, see [Troubleshooting](/mcp/troubleshooting).
## Next steps
See what each tool returns and how credits are counted.
Learn how authorization works and how to disconnect.
# Tools & Resources
Source: https://docs.enrichley.io/mcp/tools
The two MCP tools, their parameters, costs, and example outputs.
The Enrichley MCP server exposes two tools and one resource. Both tools return structured results so your AI assistant can reason about credit usage and rate limits between calls.
## Credit cost summary
| Tool | Credits per call | Notes |
| ------------------------------ | ---------------- | ---------------------------------------- |
| `enrichley_validate_email` | 1 | Consumes one credit per email validated. |
| `enrichley_get_account_status` | 0 | Free. Use this to check your balance. |
Credits are deducted from the same balance as the REST API. See [Making API calls](/making-api-calls) for plan details.
## `enrichley_validate_email`
Validate a single email address and return its deliverability status, MX info, and email type.
**When to use it:** any time you want to confirm an email is safe to send to before adding it to a campaign or contact list.
### Parameters
| Field | Type | Required | Description |
| ------- | ------ | -------- | ------------------------------ |
| `email` | string | Yes | The email address to validate. |
### Example agent prompts
> *"Validate these emails: [john@acme.com](mailto:john@acme.com), [jane@stripe.com](mailto:jane@stripe.com), [bob@notion.so](mailto:bob@notion.so)"*
> *"Is [jane.doe@example.com](mailto:jane.doe@example.com) safe to send to?"*
The assistant calls `enrichley_validate_email` once per address and summarizes the results.
### Example response
```json theme={null}
{
"ok": true,
"status": 200,
"data": {
"email": "jane.doe@example.com",
"valid": true,
"result": "catch_all_validated",
"mx_domain": "example.com",
"email_type": "business",
"mx_provider": "example",
"credits_consumed": true,
"mx_secure_email_gateway": true
},
"usage": {
"rateLimitLimit": 100,
"rateLimitRemaining": 99,
"rateLimitReset": 1700000000000,
"rateLimitResetAt": "2026-05-06T23:59:59.000Z",
"creditsRemaining": 999999,
"creditsConsumed": 1
}
}
```
### `result` values
| Value | Meaning | Safe to send? |
| --------------------- | ------------------------------------------------------ | ------------- |
| `ok` | The address is valid. | Yes |
| `catch_all_validated` | The domain is catch-all but the address was validated. | Yes |
| `catch_all` | Catch-all domain, address could not be validated. | No |
| `invalid` | The address is invalid. | No |
| `unknown` | Validation status could not be determined. | No |
**Backed by REST endpoint:** [`POST /validate-single-email`](/api-reference/endpoint/email-validation)
## `enrichley_get_account_status`
Return your remaining Enrichley credits and current rate-limit window.
**When to use it:** to check your balance before running a large validation, or to confirm the connection is working.
### Parameters
This tool takes no parameters.
### Example agent prompts
> *"Check my Enrichley credit balance."*
> *"How many email validations do I have left?"*
### Example response
```json theme={null}
{
"ok": true,
"status": 200,
"data": {
"credits": 999998
},
"usage": {
"rateLimitLimit": 100,
"rateLimitRemaining": 99,
"rateLimitReset": 1700000000000,
"rateLimitResetAt": "2026-05-06T23:59:59.000Z",
"creditsRemaining": 999998,
"creditsConsumed": null
}
}
```
This tool is read-only and does not consume credits.
**Backed by REST endpoint:** [`GET /me`](/api-reference/credits/check-credits)
## The `usage` envelope
Every tool result includes a `usage` object with rate-limit and credit metadata. This lets your AI assistant pace requests and warn you before you run out of credits.
| Field | Type | Description |
| -------------------- | -------------- | ------------------------------------------------------------------------------- |
| `creditsRemaining` | number \| null | Credits left on your account after this request. |
| `creditsConsumed` | number \| null | Credits used by this specific request (`0` for free tools, `1` for validation). |
| `rateLimitLimit` | number \| null | Maximum requests allowed in the current window. |
| `rateLimitRemaining` | number \| null | Requests remaining in the current window. |
| `rateLimitReset` | number \| null | Unix timestamp in milliseconds when the window resets. |
| `rateLimitResetAt` | string \| null | ISO 8601 form of `rateLimitReset` for human-readable contexts. |
Missing values are returned as `null`, never `0`. A `null` means the upstream API did not provide that field for this response (most often on errors).
## Errors
When a tool call fails, the response keeps the same envelope shape with `ok: false`:
```json theme={null}
{
"ok": false,
"status": 400,
"data": { "error": "Invalid email format" },
"usage": {
"rateLimitLimit": null,
"rateLimitRemaining": null,
"rateLimitReset": null,
"rateLimitResetAt": null,
"creditsRemaining": null,
"creditsConsumed": null
}
}
```
The MCP `isError` flag is set so your AI assistant can detect the failure and decide how to retry or report the issue.
## Resource: `enrichley://usage-guide`
The server publishes a single MCP resource at `enrichley://usage-guide`. It is a markdown document that explains:
* What each `result` value means and whether the address is safe to send to.
* How credits and rate limits work.
* How to interpret tool errors.
AI assistants can read this resource for in-context guidance without you having to paste it into the chat. Most clients will fetch it automatically the first time the Enrichley server is selected.
## Rate limits
The MCP server inherits the same rate limits as the Enrichley REST API:
* 10 requests per second
If you need higher throughput, contact [support@enrichley.io](mailto:support@enrichley.io).
# Troubleshooting
Source: https://docs.enrichley.io/mcp/troubleshooting
Common issues and how to fix them when using the Enrichley MCP server.
If something isn't working, start with the quick diagnostic below. Most issues fall into one of four categories: connection, authentication, client-specific, or tool errors.
## Quick diagnostic
Ask your AI assistant:
> *"Check my Enrichley credit balance."*
This calls `enrichley_get_account_status`, which is free and read-only.
* **Returns your credits:** the connection and authentication are healthy. If a different tool isn't working, it's likely a tool-specific issue.
* **Returns an authentication error:** see [Authentication errors](#authentication-errors) below.
* **Hangs or returns a connection error:** see [Connection issues](#connection-issues) below.
## Connection issues
Confirm the URL is exactly `https://mcp.enrichley.io/mcp`. Trailing slashes, missing `/mcp`, or substituting the base URL will all fail.
Test the health endpoint in a browser or with curl:
```sh theme={null}
curl https://mcp.enrichley.io/health
```
A healthy server returns `{ "ok": true, "service": "enrichley-mcp-worker" }`.
Some clients suppress popups. Look for a clickable link in the client's terminal or status bar that you can open manually. If you have a popup blocker, disable it for the client and retry.
The redirect URL your client is using may not match what the server expects. Reset the client's MCP configuration, remove and re-add the Enrichley server, and try again.
## Authentication errors
The signed-in account does not have an active Enrichley plan or a ready API credential. Sign in with the right account or upgrade your plan, then reconnect the client.
The account API credential is missing, disabled, or temporarily unavailable. Open your Enrichley profile to confirm the account is ready, then reconnect the client.
Your AI client's OAuth token has expired. Reconnect to refresh it.
* **Claude Code:** run `/mcp`, clear authentication for `enrichley`, then reconnect.
* **Cursor:** disable and re-enable the Enrichley MCP server.
The client is sending requests without a valid token. Run the setup flow again from scratch for that client.
## Client-specific issues
Run `claude mcp list` to confirm `enrichley` is registered. If it isn't, re-run the install command from [Setup](/mcp/setup). After install, run `/mcp` to start the OAuth flow — the server only becomes usable once you complete sign-in.
Restart Cursor after editing `mcp.json`. Open the MCP/tools panel and confirm the Enrichley server is enabled. If it's enabled but tools are missing, complete the OAuth browser flow when Cursor prompts you.
Make sure your config uses `"servers"` (not `"mcpServers"`) and includes `"type": "http"`. After saving, run **MCP: List Servers** from the command palette and select `enrichley` to start the OAuth flow.
The server is registered but you haven't completed OAuth yet. Run `codex mcp login enrichley` and complete the browser sign-in.
## Tool errors
The `enrichley_validate_email` tool requires a syntactically valid email. If your AI assistant pulled an address from text, double-check it for typos or missing characters.
You've hit the 10 requests/second limit. Wait until `rateLimitResetAt` (returned in the previous tool's `usage` envelope) and retry. For higher throughput, contact [support@enrichley.io](mailto:support@enrichley.io).
The validation tool consumes one credit per call. [Top up or upgrade your plan](https://app.enrichley.io/plans) to keep validating.
`result: "unknown"` means the upstream provider could not determine the address's status — usually because the receiving server didn't respond. Treat the address as not-safe-to-send and retry later if needed.
## FAQ
No. Streamable HTTP only.
No. The key is stored encrypted on the server. Your AI client only ever holds a short-lived OAuth token.
The fastest way is to disconnect inside the client itself (`/mcp` in Claude Code, the MCP panel in Cursor). To revoke access for every client at once, rotate your API key on your [Enrichley profile](https://app.enrichley.io/profile).
The Enrichley MCP server implements OAuth 2.1 with PKCE, which is what ChatGPT's developer-mode MCP support requires. We haven't validated the integration end-to-end yet, so we're not publishing official setup steps until we do. If you try it and it works, let us know at [support@enrichley.io](mailto:support@enrichley.io).
No self-hosted version is available. The hosted server at `https://mcp.enrichley.io/mcp` is the only supported deployment.
## Debugging with MCP Inspector
[MCP Inspector](https://modelcontextprotocol.io/legacy/tools/inspector) is the official open-source debugging tool from the Model Context Protocol team. Use it to test the Enrichley server outside of an AI client — it's especially helpful when you want to confirm whether an issue is on the server or on your client's MCP integration.
### Start the inspector
```sh theme={null}
npx @modelcontextprotocol/inspector
```
This starts a local UI in your browser.
### Connect to Enrichley
In the inspector UI, configure:
* **Transport:** `Streamable HTTP`
* **Connection type:** `Via Proxy`
* **URL:** `https://mcp.enrichley.io/mcp`
* **Scope:** `account.read validation.run`
* **Custom Authorization header:** disabled
Click **Connect**, complete the browser sign-in, and authorize the requested scopes. The inspector will list the two tools and let you call them interactively.
### Common inspector gotchas
Confirm the transport is set to `Streamable HTTP` (not SSE) and the URL ends with `/mcp`. Some inspector versions default to other transports or other paths.
The inspector relies on your default browser handling the OAuth redirect. If you have multiple browsers installed, set your preferred one as the system default before retrying.
Refresh the inspector's tool list by reconnecting. If they still don't show, check the inspector's network tab for a 401 response — that points to an authorization issue, not a tool issue.
## Still need help?
Contact our team for account or billing issues.
Full REST API documentation with an interactive playground.
# Support
Source: https://docs.enrichley.io/support
How to get help with the Enrichley API.
# Support
We want Enrichley users to get the most value out of our email validation API. If you have questions, run into issues, or need guidance on best practices, our team is here to help.
## Contacting support
* **Email support** – Reach us at [support@enrichley.io](mailto:support@enrichley.io) for any questions, bugs, or billing issues. Please include enough detail for us to understand what’s happening (see tips below).
If your question involves production traffic or deliverability concerns, mention that in the subject line so we can prioritize appropriately.
## Best practices for reaching out
To help us resolve your issue quickly, please include:
* **A clear description** – What you were trying to do and what you expected to happen.
* **Request details** – The endpoint you called (for example, `POST /api/v1/validate-single-email`) and approximate timestamp.
* **Safe key reference** – If relevant, share only the first few characters of your API key so we can identify the account. Never paste the full key.
* **Error information** – Any HTTP status codes, error messages, or snippets of the response body (with sensitive data removed).
Whenever possible, check the documentation and API reference first—many common questions are already covered there.
## Feedback
We’re always working to improve Enrichley’s email validation accuracy, performance, and developer experience. If you have ideas or suggestions—from new fields you’d like in the response to better examples in the docs—please email [support@enrichley.io](mailto:support@enrichley.io). Your feedback directly influences our roadmap.