> ## Documentation Index
> Fetch the complete documentation index at: https://gtmapis.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Catch-all recovery in a Clay waterfall

> Flag catch-all results in Clay, then recover the send-worthy ones with outcome-based credit economics

# Catch-all recovery in a Clay waterfall

Clay runs per-row HTTP enrichment, which is a perfect fit for **email
validation** — but catch-all *recovery* is a **batch** step that runs over a
whole CSV job, not one row at a time. So the recipe is two stages: use Clay to
clean the list and flag catch-alls per row, then run recovery on the catch-all
segment as a single batch call. You only pay for the leads recovery makes
send-worthy — see [step 3](#3-you-only-pay-for-recovered). If you are deciding
which results belong in the recovery segment, first read
[Catch-all detection vs recovery](/concepts/catch-all-detection-vs-recovery).

Recovery adds confidence, reason, and recommended-action fields beside the
original `risky` catch-all result. It does not prove mailbox existence
deterministically or rewrite the canonical validation status to `valid`.

## 1. Email validation column (per row, GA today)

**Add Enrichment → HTTP API**:

| Field   | Value                                                           |
| ------- | --------------------------------------------------------------- |
| Method  | `POST`                                                          |
| URL     | `https://api.gtmapis.com/v1/validate`                           |
| Headers | `X-API-Key: {{your_api_key}}`, `Content-Type: application/json` |
| Body    | `{ "email": "{{Email}}" }`                                      |

The key needs the `email:validate:single` scope. Mint one from the
[dashboard](https://www.gtmapis.com/dashboard/api-keys).

Map `result` and `is_catchall` to columns and filter to `result = risky` plus
`is_catchall = true` — that filtered segment is what recovery works on. Rows
where `result = valid` are your already-clean list; `invalid` and non-recovered
`risky` rows are normally suppressed.

## 2. Recover the catch-all segment (batch)

Recovery is keyed by a **CSV batch id**, not by email, so it runs once over the
job rather than once per Clay row. Export the catch-all segment to a CSV, upload
it through the [CSV API](/guides/csv-upload) (or the dashboard), then trigger
recovery on that job:

| Field   | Value                                                              |
| ------- | ------------------------------------------------------------------ |
| Method  | `POST`                                                             |
| URL     | `https://api.gtmapis.com/v1/csv/jobs/{batch_id}/recover-catchalls` |
| Headers | `X-API-Key: {{your_api_key}}`, `Content-Type: application/json`    |

The key needs the `email:validate:bulk` scope. Fetch results later with
`GET https://api.gtmapis.com/v1/csv/jobs/{batch_id}/recovery`.

<CodeGroup>
  ```json Response (excerpt) theme={null}
  {
    "recovery": {
      "eligible_count": 120,
      "recovered_count": 71,
      "suppressed_count": 18,
      "manual_review_count": 31,
      "credits_reserved": 360,
      "credits_consumed": 213,
      "credits_refunded": 147
    },
    "results": [
      {
        "email": "jane.doe@acme.com",
        "recovery_status": "send_with_caution",
        "recommended_action": "send_with_caution",
        "recovery_confidence": 0.71,
        "reason": "Name-match strong; pattern matches verified domain history; MX is a security gateway."
      }
    ]
  }
  ```
</CodeGroup>

Each result carries a human-readable `reason` (the "why" behind the call), plus a
`recovery_status` and `recommended_action`:

| `recommended_action` | Meaning                                 |
| -------------------- | --------------------------------------- |
| `safe_to_send`       | High confidence — add to the send queue |
| `send_with_caution`  | Send-worthy with reputation care        |
| `manual_review`      | Inconclusive — hold for a human         |
| `suppress`           | Don't send                              |

## 3. You only pay for recovered

Recovery charges **3 credits only on a send-worthy result**
(`likely_deliverable` / `send_with_caution`). `manual_review`, `suppress`,
`insufficient_signal`, and `provider_error` cost **0** — reserved credits are
refunded. In the example above, 120 eligible reserved 360 credits, 71 recovered
consumed 213, and 147 were refunded. The buying frame is **cost per recovered
lead**, not cost per lookup. See [API Integration](/guides/api-integration).