`https://lumail.io/api/v1/emails/verify`

Validates an email address for syntax, domain existence, disposable/spam domains, and common typos before adding it to your subscriber list.

## Response

- **Success (200 OK)** - Returns the verification result. The `success` field indicates whether the email passed all checks.
- **Error (500 Internal Server Error)** - Returned if verification fails due to an unexpected server error.

## Response Fields

| Field        | Type       | Description                                                                                                                                |
| ------------ | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| `success`    | boolean    | `true` if the email passed all validation checks, `false` otherwise                                                                        |
| `error`      | string     | Human-readable error message (present when `success` is `false`)                                                                           |
| `code`       | string     | Error code: `invalid_format`, `disposable_email`, `spam_domain`, `invalid_domain`, `test_email`, or `internal_error`                       |
| `suggestion` | string     | Corrected email suggestion when a domain typo is detected (e.g. `user@gmail.cpm` → `user@gmail.com`)                                       |
| `warnings`   | string\[\] | Non-fatal issues such as role-based address (`admin@`, `info@`, `support@`) or missing MX records (only returned when `success` is `true`) |

## Request Schema

```json
{
  "email": "string" // Required: Email address to verify
}
```

## Usage Example

Use this API endpoint to validate email addresses before adding them to your subscriber list. It helps maintain list quality and reduce bounce rates by checking for:

- Syntax validation (proper email format)
- Domain existence and validity
- Mail server configuration
- Detection of disposable or temporary email domains
- Recognition of role-based accounts (like info@, support@)

Disposable providers currently flagged by this check include common temporary-mail domains such as `passmail.net` and `yopmail.com`. These requests still return `200 OK`; inspect `success: false` and `code: "disposable_email"` to reject the address in your app.

Integrating this verification step into your signup forms and subscriber import processes can significantly improve your email deliverability and sender reputation.


## API Reference
**Method:** POST
**Endpoint:** /api/v1/emails/verify

### SDK
```ts
import { Lumail } from "lumail";
const lumail = new Lumail({ apiKey: "YOUR_API_TOKEN" });

const result = await lumail.emails.verify({
  email: "user@example.com",
});

if (result.success) {
  console.log(result.warnings);
} else {
  console.log(result.code, result.error, result.suggestion);
}
```

### cURL
```bash
curl -X POST https://lumail.io/api/v1/emails/verify \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"email": "user@example.com"}'
```

### JavaScript
```javascript
const response = await fetch('https://lumail.io/api/v1/emails/verify', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    email: 'user@example.com',
  }),
});

const data = await response.json();
console.log(data);
```

### Python
```python
import requests

url = "https://lumail.io/api/v1/emails/verify"
headers = {
    "Authorization": "Bearer YOUR_API_TOKEN",
    "Content-Type": "application/json"
}
payload = {
    "email": "user@example.com"
}

response = requests.post(url, json=payload, headers=headers)
data = response.json()
print(data)
```

### Success Response
```json
{
  "success": true,
  "warnings": ["Role-based email address detected"]
}
```

### Error Response
```json
{
  "success": false,
  "error": "Invalid email domain",
  "code": "invalid_domain",
  "suggestion": "user@gmail.com"
}
```