Clay Integration
Docs index for AI agents: https://mailvalid.io/llms.txt. Every docs page is also available as Markdown: add
.mdto its URL.
Verify email addresses inside a Clay table. You add an HTTP API enrichment column that calls MailValid for each row. The call is synchronous: one request returns the verdict, so there is no polling and no webhook to set up. Then you route each row by its status: send, drop, or hold.
Fastest start: copy the MailValid for Clay template. It has the column set up and the result fields mapped. Add your own API key as described in step 3, then import your list.
| Setting | Value |
|---|---|
| Method | POST |
| Endpoint | https://mailvalid.io/api/v1/verify/single |
| Header | X-API-Key: <your key>, saved as a Clay account |
| Body | {"email": "/Email"} where /Email is your email column |
| Billing | 1 credit per billable result. unknown results are free. Credits never expire |
| Rate limit | Paid: 200 requests per minute. Free: 10 per minute |
Set up the column
- Get an API key. Create a free MailValid account (100 free credits, no credit card). Open the dashboard, go to API Keys and create a key. It starts with
mv_live_. - Add the enrichment. In your Clay table, open Tools, search for HTTP API and pick it. Open the Configure tab.
- Save your key as an account. Under Account, click Add account. Name it
MailValid, addmailvalid.iounder Allowed websites, then add a header with the keyX-API-Keyand your API key as the value. Save. Clay keeps the key in the account, so it is not stored in the table and is not shared if you share the table as a template. - Set the method and endpoint. Set Method to
POSTand Endpoint tohttps://mailvalid.io/api/v1/verify/single. - Add the body. Open Body and enter the JSON below. Type
/where the email goes and pick your email column. Clay sends the body as JSON, so you do not need to add aContent-Typeheader.
{"email": "/Email"}
- Save and run. Open the Save menu and pick Save and run on the first few rows. Each cell shows
Status Code: 200when the call worked. Referencing the email column also means new rows run on their own when auto-run is on. - Map the result fields to columns. Click a finished cell, expand Result, and use Add to column on
Statusand any other fields you want. See Fields to map below. - Add a routing column. See Route by status below.
Test your key first
Before you run a whole table, check the key works. This call is free and returns your credit balance:
curl https://mailvalid.io/api/v1/credits \
-H "X-API-Key: mv_live_your_key_here"
You get back your balance and lifetime_used. A 401 means the key is wrong or inactive.
What the API returns
{
"success": true,
"credits_used": 1,
"result": {
"email": "john@company.com",
"status": "valid",
"is_valid": true,
"confidence_score": 95,
"status_reason": "mailbox_confirmed",
"is_catch_all": false,
"is_disposable": false,
"is_role_based": false,
"is_free_provider": false,
"provider": "corporate"
}
}
The real response has more fields. See Single Verification for the full list.
Fields to map
Map these fields from result to their own Clay columns:
| Field | Type | Meaning |
|---|---|---|
status |
string | valid, invalid, catch_all, unknown or do_not_mail |
is_valid |
boolean | true only when status is valid |
confidence_score |
number | 0 to 100 |
status_reason |
string | The specific reason, for example mailbox_confirmed, mailbox_not_found, accept_all |
is_catch_all |
boolean | true when the domain accepts every address |
is_disposable |
boolean | true for throwaway email providers |
is_role_based |
boolean | true for addresses like info@ or support@ |
is_free_provider |
boolean | true for Gmail, Outlook, Yahoo and similar |
provider |
string | The detected mail provider |
At minimum, map status. It is the one field you need for routing. See Status Values for every status_reason.
Route by status
Add a formula or filter column on status and send each row to the right place:
| Status | What to do |
|---|---|
valid |
Send. The mailbox was confirmed. |
invalid |
Drop it. It will bounce. |
do_not_mail |
Drop it for outreach. It is a disposable or role-based address. Keep role-based ones only if you want them. |
catch_all |
Move it to a separate, slower bucket. See the note below. |
unknown |
Retry later. The mail server did not answer. You are not charged for it. |
Catch-all domains
MailValid flags catch-all domains. It does not tell you whether the individual mailbox on a catch-all domain exists. The domain accepts every address, so no verifier can confirm one mailbox from the outside. Treat catch_all rows as higher risk. Send them in a smaller, slower batch and watch the bounce rate before you send more.
Rate limits
Paid plans allow 200 verification requests per minute per API key. Free accounts allow 10 per minute.
Set the HTTP API column's rate limit below your plan limit. On a paid plan, about 3 requests per second is a safe setting, because 200 per minute is 3.3 per second. On a free account, stay under 10 per minute.
If you go over the limit, the API returns 429 Too Many Requests with a Retry-After header. Lower the rate and re-run the failed rows. See Rate Limits.
Billing
- 1 credit per billable result:
valid,invalid,catch_allanddo_not_mail. unknownresults are free.- Credits never expire.
- New accounts get 100 free credits.
Tips
- Run it once per row. Re-running a column on the same rows uses credits again. Turn off auto-run while you set the column up, test on a few rows, then run the rest.
- Verify last. Put the MailValid column after the steps that find the email, so you only verify the addresses you will use.
- Large lists. For tens of thousands of existing contacts, upload a CSV in the dashboard or use the Bulk Verification API instead of running each row through Clay.
Troubleshooting
| Problem | Fix |
|---|---|
401 error |
Check the X-API-Key header in your Clay account holds the full key and the key is still active under API Keys |
| The column preview keeps loading | Save the column and run it on a few rows instead. The saved column calls the API normally |
402 or insufficient credits error |
Top up credits in the dashboard. Credits never expire |
422 error |
The body is wrong or the email is empty. Check the body is {"email": "/Email"} and the column only runs on filled rows |
429 error |
You went over the rate limit. Lower the column's rate limit and re-run |
Many unknown results |
Some providers block SMTP checks. These are free. Retry later or treat them as unverified |
Need help? Email support@mailvalid.io.