Black Friday Sale

Use code: BLACKFRIDAY50

50% OFF on all prices
Ends in: 00d: 00h: 00m: 00s

Clay Integration

Docs index for AI agents: https://mailvalid.io/llms.txt. Every docs page is also available as Markdown: add .md to 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

  1. 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_.
  2. Add the enrichment. In your Clay table, open Tools, search for HTTP API and pick it. Open the Configure tab.
  3. Save your key as an account. Under Account, click Add account. Name it MailValid, add mailvalid.io under Allowed websites, then add a header with the key X-API-Key and 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.
  4. Set the method and endpoint. Set Method to POST and Endpoint to https://mailvalid.io/api/v1/verify/single.
  5. 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 a Content-Type header.
{"email": "/Email"}
  1. Save and run. Open the Save menu and pick Save and run on the first few rows. Each cell shows Status Code: 200 when the call worked. Referencing the email column also means new rows run on their own when auto-run is on.
  2. Map the result fields to columns. Click a finished cell, expand Result, and use Add to column on Status and any other fields you want. See Fields to map below.
  3. 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_all and do_not_mail.
  • unknown results 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.

We value your privacy. Cookies keep you signed in and, if you allow, help us improve MailValid. Privacy Policy