# Find a work email from a name and domain with Bytemine's API

Bytemine's Email Finder API takes a person's first name, last name and company domain, or a LinkedIn profile URL alone, and returns their best deliverable work email with its confidence, SMTP result and catch-all status. A found email costs $0.01, and guesses, misses and cached repeats are free. Send `POST https://agents.bytemine.ai/zcj/0ay13cqkk0pk/functions/v1/api-gateway/email-finder` and pay the request's 402 price quote from a wallet; no account or API key is needed.

## At a glance

- **Endpoint:** `POST https://agents.bytemine.ai/zcj/0ay13cqkk0pk/functions/v1/api-gateway/email-finder`, one person per request
- **Body:** `first_name`, `last_name` and `company_domain`, or `linkedin_url` on its own
- **Price:** $0.01, charged only when `status` is `found`
- **Payment:** each request answers with a 402 price quote, paid from a wallet over x402 or MPP, or drawn from prepaid Credits. No account or API key is needed.
- **Response:** `email`, `status`, `confidence`, `smtp_result`, `catch_all`, `cached`, `credits_charged`
- **Limits:** one person per request, with no bulk field
- **Full purchase flow:** [the buyer skill](https://agents.bytemine.ai/zcj/0ay13cqkk0pk/SKILL.md)

## Choose the request form

Each form identifies one person. `company_domain` is required whenever `linkedin_url` is absent.

| What you have | Fields to send |
| --- | --- |
| Name and company domain | `first_name`, `last_name`, `company_domain` (the root domain, such as `example.com`) |
| LinkedIn profile URL | `linkedin_url`. A person URL resolves the name and domain itself. |

The LinkedIn form takes this body:

```json
{"linkedin_url": "https://www.linkedin.com/in/alex-example"}
```

## Find a work email

1. Send the request with the name and domain:

   ```bash
   curl -i -X POST https://agents.bytemine.ai/zcj/0ay13cqkk0pk/functions/v1/api-gateway/email-finder \
     -H 'Content-Type: application/json' \
     -d '{"first_name": "Alex", "last_name": "Example", "company_domain": "example.com"}'
   ```

   The storefront answers with a 402 price quote, with the amount in `payment.amountUsd`.

2. Pay the quote and retry the same request with the proof attached. A standard x402 or MPP client reads the headers and retries for you, and [the buyer skill](https://agents.bytemine.ai/zcj/0ay13cqkk0pk/SKILL.md) has the full steps. Only a found email is billed.

3. Read the response. It has this shape, shown here with placeholder values:

   ```json
   {"email": "alex@example.com", "status": "found", "confidence": "high", "smtp_result": "valid", "catch_all": false, "cached": false, "credits_charged": 1}
   ```

   Check `status` before you use `email`. The `zc-billing` response header reports what you authorized (`authorizedUsd`) and what you were charged (`chargedUsd`). A delivered response with no `zc-billing` header billed nothing.

## Read the status

| `status` | `email` | Billed |
| --- | --- | --- |
| `found` | The validated address | Yes, $0.01. `credits_charged` is `1`. |
| `guessed` | A best-guess address | No |
| `not_found`, `skipped`, `no_mx` | None | No |

`confidence` is `high`, `medium` or `low`. `smtp_result` is `valid`, `catch-all` or `unknown`. `catch_all` is `true` when the domain accepts any address. `cached: true` marks a repeat lookup, which is free.

## Run a list and budget it

Send one request per person. A list costs the number of found emails times $0.01, so a list of 100 people costs at most $1. Every miss in it costs nothing.

Pay-as-you-go needs no identity. Each call pays its own 402.

For card payment, buy Credits instead. A card pays a single call only at $0.50 or more, which is above the price of one find. Credits start at $0.50 by card, need an agent identity (a bearer credential the storefront issues, set up through [auth.md](https://agents.bytemine.ai/zcj/0ay13cqkk0pk/auth.md)), and are bought with `POST https://agents.bytemine.ai/zcj/0ay13cqkk0pk/plans/{planId}/purchase`. The plan id is in [the catalog](https://agents.bytemine.ai/zcj/0ay13cqkk0pk/manifest.json). Calls then draw down the balance, and `zc-billing` reports `remainingCreditUsd`.

## Limits

- The API returns one work email per request, and the body takes one person's fields, with no field for several people.
- Only `found` is billed. A `guessed` result is not billed.
- After payment, the API's own status and body pass through unchanged, including its errors.

## Errors

| Code | Meaning | Action |
| --- | --- | --- |
| `402` with no `reason` | The price quote for this call | Pay and retry the same request, or stop |
| `invalid_request` (400) | The JSON body is malformed | Fix the body and resend |
| `settlement_failed` | The payment did not settle. `settlementReason` says why, such as `insufficient_funds`. | Fix the wallet, then send a fresh request for a new 402 |
| `payment_consumed` | That payment was already spent | Check whether the earlier call delivered before paying again |
| `usage_exhausted` | The Credits balance is used up | Top up with `POST https://agents.bytemine.ai/zcj/0ay13cqkk0pk/extend` and `{"amountUsd": "..."}` |
| `amount_below_card_minimum` | A card Credits purchase is under the minimum | Raise `amountUsd` to `purchase.cardMinimumUsd` or pay on a wallet rail |

## Frequently asked questions

### Does Bytemine's email finder charge when no email is found?

No. Only a `found` status is billed, at $0.01. `guessed`, `not_found`, `skipped` and `no_mx` results cost nothing, and cached repeats are free. `credits_charged` is `1` on found and `0` otherwise.

### Can I find a work email from a LinkedIn URL alone?

Yes. Send `linkedin_url` with a person's profile URL and no other fields. The API resolves the name and company domain from the profile.

### Do I need an API key or an account for the email lookup API?

No. Pay-as-you-go calls are paid per request over x402 or MPP, with no account, key or registration. An agent identity is needed only to buy Credits.

### Can I pay for a single email lookup by card?

Not on its own. A card pays one call only at $0.50 or more. To pay by card, buy Credits from $0.50 and let each find draw down the balance.

### Can one request find emails for a whole list?

No. Each request covers one person. To run a list, send one request per person and pay only for the emails found.

## Keep reading

- [Buyer skill](https://agents.bytemine.ai/zcj/0ay13cqkk0pk/SKILL.md): the full purchase flow
- [How to pay](https://agents.bytemine.ai/zcj/0ay13cqkk0pk/payment.md): x402, MPP, card and Credits
- [Email Finder API reference](https://agents.bytemine.ai/zcj/0ay13cqkk0pk/services/email-finder/openapi.json): the exact request and response schema
- [Error reference](https://agents.bytemine.ai/zcj/0ay13cqkk0pk/errors.md): every error code and the action for each

---

Updated 2026-10-16. All Bytemine guides: https://agents.bytemine.ai/guides.md. Storefront: https://agents.bytemine.ai/zcj/0ay13cqkk0pk/llms.txt.