# Email Enrichment

## Use case

Find a professional email address from a profile URL or a name and company domain.

## Endpoint

```http
POST https://api-public.clodo.ai/api/public/v1/enrich/email/
```

Send your API key in the `x-api-key` header. See [Authentication](https://docs.clodo.ai/api-reference/authentication).

## Pricing

See [Credits & Pricing](https://docs.clodo.ai/guides/credits-and-pricing) for credit costs and charging behavior.

## Errors

For error responses and retry guidance, see [Handling Errors](https://docs.clodo.ai/api-reference/errors).

`POST /api/public/v1/enrich/email/` — sync. 5 credits per call.

## Request

Provide at least one of:

- `professional_url`
- `first_name` + `last_name` + `company_name`
- `first_name` + `last_name` + `domain`

> Use `professional_url`, or `first_name` + `last_name` + `domain`, to resolve an email. The name + `company_name` shape is accepted for compatibility, but without a profile URL or domain it returns `404 not_found`. Completed lookups that find no match still cost 5 credits.

| Field | Type | Notes |
|---|---|---|
| `professional_url` | string | LinkedIn URL. |
| `first_name` | string | Required when not using `professional_url`. |
| `last_name` | string | Required when not using `professional_url`. |
| `company_name` | string | Accepted with `first_name` + `last_name`, but cannot resolve an email without `professional_url`. Mutually exclusive with `domain`. |
| `domain` | string | e.g. `acme.com`. Pair with `first_name` + `last_name`. Must contain a dot. |

## Response

```json
{
  "email": "patrick@stripe.com"
}
```

A miss returns `404 not_found` (see Status mapping below).

## Status mapping

| Outcome | HTTP | Charged |
|---|---|---|
| Email found | `200 OK` | 5 credits |
| No match found | `404 not_found` | 5 credits |
| Invalid input | `400 invalid_request` | 0 |
| Upstream failure | `502 upstream_error` | 0 |

## Examples

By LinkedIn URL:

```bash
curl -X POST https://api-public.clodo.ai/api/public/v1/enrich/email/ \
  -H "x-api-key: ck_live_..." \
  -H "Content-Type: application/json" \
  -d '{"professional_url": "https://www.linkedin.com/in/patrickcollison/"}'
```

```python
import os
import requests

response = requests.post(
    "https://api-public.clodo.ai/api/public/v1/enrich/email/",
    headers={"x-api-key": os.environ["CLODO_API_KEY"]},
    json={"professional_url": "https://www.linkedin.com/in/patrickcollison/"},
    timeout=30,
)
response.raise_for_status()
print(response.json())
```

```javascript
const response = await fetch(
  "https://api-public.clodo.ai/api/public/v1/enrich/email/",
  {
    method: "POST",
    headers: {
      "x-api-key": process.env.CLODO_API_KEY,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      professional_url: "https://www.linkedin.com/in/patrickcollison/",
    }),
  },
);
if (!response.ok) {
  throw new Error(`HTTP ${response.status}: ${await response.text()}`);
}
console.log(await response.json());
```

By profile URL with name + company context:

```bash
curl -X POST https://api-public.clodo.ai/api/public/v1/enrich/email/ \
  -H "x-api-key: ck_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "professional_url": "https://www.linkedin.com/in/patrickcollison/",
    "first_name": "Patrick",
    "last_name": "Collison",
    "company_name": "Stripe"
  }'
```

By name + domain:

```bash
curl -X POST https://api-public.clodo.ai/api/public/v1/enrich/email/ \
  -H "x-api-key: ck_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "first_name": "Patrick",
    "last_name": "Collison",
    "domain": "stripe.com"
  }'
```

## Rate limit

| Limit | Value |
|---|---|
| Sustained rate | 30 requests / minute |
| Burst | 5 requests |

Exceeding any returns `429`.

## See also

- [Authentication](https://docs.clodo.ai/api-reference/authentication)
- [Error Envelope](https://docs.clodo.ai/api-reference/errors)
- [Credit Semantics](https://docs.clodo.ai/guides/credits-and-pricing)