# Get started with the ValidatedMails Validate API

Create a key, verify one email, and use its result in your application.

## 1. Create an API key

Sign in and [create an API key](/app/api-keys). Copy it when it appears; you cannot view the secret again. Save it as an environment variable on your server:

```bash
export VALIDATEDMAILS_API_KEY="YOUR_API_KEY"
```

Keep your key out of browser code and public repositories. Validation uses your account’s prepaid credits.

## 2. Check your connection for free

```bash
curl https://api.validatedmails.com/api-keys/me \
  -H "Authorization: Bearer $VALIDATEDMAILS_API_KEY"
```

A successful response includes `ok: true`. This request checks your key without using credits. An HTTP 401 means the key was rejected.

## 3. Verify an email

Replace the example address with an address you want to check. Choose your language below; the Python example requires `requests`.

```bash
curl -X POST https://api.validatedmails.com/validate \
  -H "Authorization: Bearer $VALIDATEDMAILS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"email":"person@example.com"}'
```

```json
{
  "email": "person@example.com",
  "status": "valid",
  "is_valid": true,
  "score": 95,
  "reason": "Valid"
}
```

This response is illustrative. Use the `status` from your actual response. One credit is charged for a valid, risky, or invalid result; unknown results are free.

## 4. Handle all four statuses

- valid: the address passed the verification checks.
- risky: there is a risk signal, such as a catch-all domain. Apply your own acceptance policy.
- invalid: the checks found evidence that the address cannot receive mail.
- unknown: the evidence is inconclusive. Keep this separate from invalid.

`is_valid` is true only for valid. Branch on `status` to preserve all four outcomes. Verification does not guarantee inbox placement.

## Next steps

- [Read the request fields, response fields, and errors](/docs/api-response).
- [Verify a batch of emails](#high-volume-batches), or [upload a CSV in the console](/app/bulk).
- [Connect an AI assistant with MCP](/docs/mcp).

## Verify a batch

Use `POST /validate/batch` for 1–100 addresses. Results follow the input order; inspect each item for errors.

```bash
curl -X POST https://api.validatedmails.com/validate/batch \
  -H "Authorization: Bearer $VALIDATEDMAILS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"emails":["alex@example.com","sales@example.org"]}'
```

See the [batch reference](/docs/api-response#batch-requests) for partial failures and limits. A timeout may occur after a request has completed; automatically resending it can consume credits again.
