# Quickstart

> 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 your first email with the MailValid API in under 2 minutes. MailValid checks syntax, domain, MX records and the SMTP mailbox, and flags disposable, role-based and catch-all addresses.

## Base URL

```
https://mailvalid.io/api/v1
```

## 1. Get an API key

Create a free account at [mailvalid.io/register](https://mailvalid.io/register) (100 free credits, no credit card) and generate a key from [Dashboard → API Keys](https://mailvalid.io/dashboard/api-keys). Send it in the `X-API-Key` header. See [Authentication](https://mailvalid.io/docs/authentication).

## 2. Verify an email

### cURL

```bash
curl -X POST https://mailvalid.io/api/v1/verify/single \
  -H "X-API-Key: mv_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"email": "john@company.com"}'
```

### Python

```python
import requests

API_KEY = "mv_live_your_key_here"

response = requests.post(
    "https://mailvalid.io/api/v1/verify/single",
    headers={"X-API-Key": API_KEY},
    json={"email": "john@company.com"}
)

result = response.json()
print(f"Status: {result['result']['status']}")  # valid, invalid, catch_all, unknown, do_not_mail
print(f"Valid: {result['result']['is_valid']}")
print(f"Confidence: {result['result']['confidence_score']}")
print(f"Reason: {result['result']['status_reason']}")
```

### JavaScript (Node.js)

```javascript
const API_KEY = "mv_live_your_key_here";

const response = await fetch(
  "https://mailvalid.io/api/v1/verify/single",
  {
    method: "POST",
    headers: {
      "X-API-Key": API_KEY,
      "Content-Type": "application/json"
    },
    body: JSON.stringify({ email: "john@company.com" })
  }
);

const data = await response.json();
console.log(`Status: ${data.result.status}`);  // valid, invalid, catch_all, unknown, do_not_mail
console.log(`Valid: ${data.result.is_valid}`);
console.log(`Confidence: ${data.result.confidence_score}`);
```

### PHP

```php
<?php
$apiKey = "mv_live_your_key_here";

$ch = curl_init("https://mailvalid.io/api/v1/verify/single");
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST => true,
    CURLOPT_HTTPHEADER => [
        "X-API-Key: " . $apiKey,
        "Content-Type: application/json"
    ],
    CURLOPT_POSTFIELDS => json_encode(["email" => "john@company.com"])
]);

$result = json_decode(curl_exec($ch), true);
echo "Status: " . $result['result']['status'];  // valid, invalid, catch_all, unknown, do_not_mail
echo "Valid: " . ($result['result']['is_valid'] ? 'Yes' : 'No');
echo "Confidence: " . $result['result']['confidence_score'];
?>
```

## Next steps

- [Single email verification](https://mailvalid.io/docs/verify-single): full request and response reference
- [Bulk verification](https://mailvalid.io/docs/verify-bulk): verify up to 10,000 emails per job
- [Status values](https://mailvalid.io/docs/status-values): what `valid`, `catch_all`, `unknown` and `do_not_mail` mean
- [MCP server](https://mailvalid.io/docs/mcp): connect Claude, Cursor or VS Code to MailValid