# Clay Integration

> Docs index for AI agents: [https://mailvalid.io/llms.txt](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](https://app.clay.com/shared-workbook/share_0toliox8bTVUZknXFxb). 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](https://mailvalid.io/register) (100 free credits, no credit card). Open the [dashboard](https://mailvalid.io/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.

```json
{"email": "/Email"}
```

6. **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.
7. **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](#fields-to-map) below.
8. **Add a routing column.** See [Route by status](#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:

```bash
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

```json
{
  "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](https://mailvalid.io/docs/verify-single) 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](https://mailvalid.io/docs/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](https://mailvalid.io/docs/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](https://mailvalid.io/docs/verify-bulk) 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](mailto:support@mailvalid.io).
