> ## Documentation Index
> Fetch the complete documentation index at: https://leadmagic.io/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Email Validation API
> POST /v1/email-validation — verify deliverability with SMTP + engagement signals.
# Validate Email
Verify email addresses with industry-leading accuracy. Our validation system combines SMTP verification with engagement data for the most reliable results.
## Endpoint Details
| Metric | Value |
| ---------------- | ------------------------------------------ |
| **Cost** | **0.25 credits** per validation |
| **Calculation** | 4 validations = 1 credit |
| **Free Results** | `unknown` and RFC-invalid results are free |
You only pay for definitive SMTP results (`valid`, `invalid`). Inconclusive results (`unknown`) and RFC syntax failures are always free.
**RFC 5321/5322 Compliance:** Emails that fail RFC syntax validation are automatically marked `invalid` and returned instantly — **no credits charged**. This includes malformed addresses, invalid characters, and improper formatting.
### Per-Endpoint Limit
| Metric | Value |
| ------------------- | ------------------- |
| **Requests/Minute** | 300 |
| **Burst Capacity** | \~5 requests/second |
Rate limits are subject to change. Custom rate limits are available on enterprise plans — [contact us](mailto:support@leadmagic.io).
***
## Quick Example
```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl -X POST 'https://api.leadmagic.io/v1/people/email-validation' \
-H 'X-API-Key: YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{"email": "alex.rivera@example.com"}'
```
```javascript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
const response = await fetch('https://api.leadmagic.io/v1/people/email-validation', {
method: 'POST',
headers: {
'X-API-Key': 'YOUR_API_KEY',
'Content-Type': 'application/json'
},
body: JSON.stringify({ email: 'alex.rivera@example.com' })
});
const data = await response.json();
console.log(data.email_status); // 'valid', 'invalid', or 'unknown'
```
```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
import requests
response = requests.post(
'https://api.leadmagic.io/v1/people/email-validation',
headers={'X-API-Key': 'YOUR_API_KEY'},
json={'email': 'alex.rivera@example.com'}
)
data = response.json()
print(f"Status: {data['email_status']}")
```
***
## Request Parameters
The email address to validate. Must be a properly formatted email address.
***
## Response
The validated email address (normalized)
Validation result: `valid`, `invalid`, or `unknown`
Credits used for this request (0.25 for `valid`/`invalid`, 0 for `unknown`)
Human-readable status message
Primary MX record for the domain
Email provider (Example Mail, Example Mail Suite, etc.)
Security gateway vendor name (null if none)
Security gateway type (null if none)
Whether a security gateway is present
Company name derived from email domain
Company industry
Employee count range
Year founded
Ownership type (private, public, etc.)
B2B company profile URL
B2B company profile ID
Facebook page URL (null if unavailable)
Twitter/X profile URL (null if unavailable)
Full location with city, state, country, coordinates
### Example Response
```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
"email": "alex.rivera@example.com",
"email_status": "valid",
"credits_consumed": 0.25,
"message": "Email is valid.",
"mx_record": "mx1.example.com",
"mx_provider": "Example Mail",
"mx_gateway": null,
"mx_gateway_type": null,
"mx_security_gateway": false,
"company_name": "Leadmagic",
"company_industry": "Internet",
"company_size": "11-50",
"company_founded": 2022,
"company_type": "Private",
"company_location": {
"name": "Boston, Massachusetts, United States",
"locality": "Boston",
"region": "Massachusetts",
"metro": "Boston",
"country": "United States",
"continent": "North America",
"street_address": "1 Seaport Lane",
"address_line_2": null,
"postal_code": "02210",
"geo": null
},
"company_linkedin_url": "linkedin.com/company/leadmagichq",
"company_linkedin_id": "75153174",
"company_facebook_url": null,
"company_twitter_url": null
}
```
***
## Status Codes
**Safe to email** - Bounce rate \<1%
Email verified by mail server. Costs 0.25 credits.
**Do NOT email** - Will bounce
Mail server confirmed non-existent. Costs 0.25 credits.
**Inconclusive** - Could not determine validity
Couldn't reach mail server or domain is unverifiable. **FREE** (no charge).
### RFC Compliance
Emails that don't comply with RFC 5321/5322 standards are **automatically marked `invalid`** — no credits charged:
| RFC Violation | Example | Result |
| ------------------ | ------------------------ | ---------------- |
| Missing `@` symbol | `johnleadmagic.io` | `invalid` (FREE) |
| Invalid characters | `alex @example.com` | `invalid` (FREE) |
| Missing domain | `alex@` | `invalid` (FREE) |
| Double dots | `john..doe@leadmagic.io` | `invalid` (FREE) |
| Invalid TLD | `alex@leadmagic` | `invalid` (FREE) |
RFC validation happens instantly before SMTP verification. Malformed emails are rejected immediately at no cost — reserved credits are rolled back.
***
## Success Messages
| Message | Status | Cost |
| ---------------------------------------------- | --------- | ---- |
| `Email is valid.` | `valid` | 0.25 |
| `Email is invalid.` | `invalid` | 0.25 |
| `Email is invalid (RFC non-compliant format).` | `invalid` | FREE |
| `Email is invalid (malformed address).` | `invalid` | FREE |
| `Unable to determine email validity.` | `unknown` | FREE |
***
## Best Practices
Run basic regex validation before API calls to catch obvious RFC violations. While RFC failures are free, client-side checks reduce unnecessary API calls.
```javascript theme={"theme":{"light":"github-light","dark":"github-dark"}}
// Basic RFC-compliant check before API call
const emailRegex = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
if (!emailRegex.test(email)) {
// Skip API call - obviously invalid
return { email_status: 'invalid', reason: 'malformed' };
}
```
Note: Our API catches all RFC violations, but client-side pre-validation can reduce unnecessary API calls.
Always validate your email list before sending to maintain high deliverability and protect your sender reputation. Invalid emails hurt your domain reputation.
For `unknown` results, consider retrying later or using Email Finder to verify the specific address exists before adding to campaigns.
For large lists, batch your requests to stay within rate limits. Use the response headers to monitor your remaining quota.
```javascript theme={"theme":{"light":"github-light","dark":"github-dark"}}
const remaining = response.headers.get('RateLimit-Remaining');
if (remaining < 100) {
await sleep(1000); // Slow down if approaching limit
}
```
Every response includes `X-Credits-Remaining` so you can track spending without extra API calls.
***
## Use Cases
Validate email lists before campaigns to reduce bounces and protect sender reputation.
Validate emails at point of capture to ensure data quality from the start.
Regularly validate CRM contacts to maintain deliverability rates.
Use validation status as a lead quality signal in your scoring models.
## OpenAPI
````yaml post /v1/people/email-validation
openapi: 3.1.0
info:
title: LeadMagic API
version: 1.4.34
description: >
# LeadMagic API Documentation
The LeadMagic API provides comprehensive B2B data enrichment services
including email validation, email finding, profile search, company
intelligence, and more.
## Quick Start
1. Get your API key from the [LeadMagic Dashboard](https://app.leadmagic.io)
2. Add the `X-API-Key` header to all requests
3. Start enriching your data!
## Base URL
All API requests should be made to: `https://api.leadmagic.io`
## Rate Limits
Each endpoint has specific rate limits (requests per minute). Exceeding
limits returns a `429 Too Many Requests` response.
## Credits
API calls consume credits based on the endpoint used. Check your balance
with the `/v1/credits` endpoint.
## Support
Contact us at support@leadmagic.io for assistance.
contact:
name: LeadMagic Support
email: support@leadmagic.io
url: https://leadmagic.io
termsOfService: https://leadmagic.io/legal/terms
servers:
- url: https://api.leadmagic.io
description: Production API Server
security:
- ApiKeyAuth: []
tags:
- name: Credits
description: Manage and check your credit balance
- name: Analytics
description: >-
Monitor your API usage with comprehensive analytics endpoints (FREE - no
credits consumed)
- name: People Enrichment
description: Find and validate contact information for individuals
- name: Company Data
description: Discover company information and intelligence
- name: Jobs Data
description: Search job listings and detect career changes
- name: Ads Data
description: Search advertising data across platforms
paths:
/v1/people/email-validation:
post:
tags:
- People Enrichment
summary: Email Validation
description: >-
Validate an email address for deliverability and get company enrichment
data.
operationId: email-validation
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
email:
type: string
format: email
description: Email address to validate
example: alex.rivera@example.com
required:
- email
responses:
'200':
description: Successful validation
content:
application/json:
schema:
type: object
properties:
email:
type: string
example: alex.rivera@example.com
email_status:
type: string
example: valid
credits_consumed:
type: number
example: 0.25
message:
type: string
example: Email is valid.
mx_record:
type: string
example: mx1.example.com
mx_provider:
type: string
example: Example Mail
mx_gateway:
type: string
nullable: true
description: Security gateway vendor name
example: null
mx_gateway_type:
type: string
nullable: true
description: Security gateway type
example: null
mx_security_gateway:
type: boolean
example: false
company_name:
type: string
example: Leadmagic
company_industry:
type: string
example: Internet
company_size:
type: string
example: 11-50
company_founded:
type: integer
example: 2022
company_type:
type: string
example: Private
company_location:
type: object
properties:
name:
type: string
example: Boston, Massachusetts, United States
locality:
type: string
example: Boston
region:
type: string
example: Massachusetts
metro:
type: string
example: Boston
country:
type: string
example: United States
continent:
type: string
example: North America
street_address:
type: string
example: 1 Seaport Lane
address_line_2:
type: string
nullable: true
example: null
postal_code:
type: string
example: '02210'
geo:
type: string
nullable: true
example: null
company_linkedin_url:
type: string
description: Legacy field name for the B2B company profile.
example: linkedin.com/company/leadmagichq
company_linkedin_id:
type: string
example: '75153174'
company_facebook_url:
type: string
nullable: true
example: null
company_twitter_url:
type: string
nullable: true
example: null
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'402':
$ref: '#/components/responses/PaymentRequired'
'429':
$ref: '#/components/responses/RateLimitExceeded'
'500':
$ref: '#/components/responses/InternalServerError'
components:
responses:
BadRequest:
description: |
Bad Request - The request was malformed or contains invalid parameters.
**Common causes:**
- Missing required fields
- Invalid field format (e.g., malformed email)
- Invalid JSON syntax
- Invalid parameter values
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ValidationError'
Unauthorized:
description: |
Unauthorized - Authentication failed.
**Common causes:**
- Missing X-API-Key header
- Invalid or expired API key
- Malformed API key
content:
application/problem+json:
schema:
oneOf:
- $ref: '#/components/schemas/MissingAuthenticationError'
- $ref: '#/components/schemas/InvalidApiKeyError'
PaymentRequired:
description: >
Payment Required - Insufficient credits for this request.
**Action required:** Add credits to your account at
https://app.leadmagic.io/billing
content:
application/problem+json:
schema:
$ref: '#/components/schemas/InsufficientCreditsError'
RateLimitExceeded:
description: |
Too Many Requests - Rate limit exceeded.
**Action required:** Check the `Retry-After` header for when to retry.
**Headers returned:**
- `Retry-After`: Seconds until you can retry
- `RateLimit-Limit`: Your limit per minute
- `RateLimit-Remaining`: Remaining requests this minute
- `RateLimit-Reset`: Seconds until limit resets
headers:
Retry-After:
schema:
type: integer
description: Seconds to wait before retrying
RateLimit-Limit:
schema:
type: integer
description: Maximum requests per minute
RateLimit-Remaining:
schema:
type: integer
description: Remaining requests this minute
RateLimit-Reset:
schema:
type: integer
description: Seconds until limit resets
content:
application/problem+json:
schema:
$ref: '#/components/schemas/RateLimitExceededError'
InternalServerError:
description: >
Internal Server Error - Something went wrong on our end.
**Action required:** Wait 30 seconds and retry. If the problem persists,
contact support@leadmagic.io
content:
application/problem+json:
schema:
$ref: '#/components/schemas/InternalServerError'
schemas:
ValidationError:
allOf:
- $ref: '#/components/schemas/ErrorResponse'
example:
success: false
errors:
- type: https://api.leadmagic.io/errors/validation_error
title: Request validation failed. Check your input parameters.
status: 400
code: validation_error
param:
- email
detail: 'Email format is invalid. Expected format: user@domain.com'
action: Provide a valid email address in the 'email' field.
docs: https://leadmagic.io/docs/api-reference/errors
meta:
request_id: ea6e3248-f4d2-437d-bca3-20881b529129
timestamp: '2024-02-01T12:00:00.000Z'
MissingAuthenticationError:
allOf:
- $ref: '#/components/schemas/ErrorResponse'
example:
success: false
errors:
- type: https://api.leadmagic.io/errors/missing_authentication
title: >-
Authentication required. Provide a valid API key in the X-API-Key
header (case-insensitive).
status: 401
code: missing_authentication
docs: https://leadmagic.io/docs/api-reference/authentication
meta:
request_id: ea6e3248-f4d2-437d-bca3-20881b529129
timestamp: '2024-02-01T12:00:00.000Z'
InvalidApiKeyError:
allOf:
- $ref: '#/components/schemas/ErrorResponse'
example:
success: false
errors:
- type: https://api.leadmagic.io/errors/invalid_api_key
title: Invalid API key. The key does not exist or is incorrect.
status: 401
code: invalid_api_key
docs: https://leadmagic.io/docs/api-reference/authentication
meta:
request_id: ea6e3248-f4d2-437d-bca3-20881b529129
timestamp: '2024-02-01T12:00:00.000Z'
InsufficientCreditsError:
allOf:
- $ref: '#/components/schemas/ErrorResponse'
example:
success: false
errors:
- type: https://api.leadmagic.io/errors/insufficient_credits
title: 'Insufficient credits: need 5, have 2.50. Add credits to continue.'
status: 402
code: insufficient_credits
detail: >-
This request requires 5 credit(s) but your account only has 2.50
credits remaining.
action: >-
Add credits to your account at https://app.leadmagic.io/billing or
contact support@leadmagic.io for enterprise plans.
docs: https://leadmagic.io/docs/api-reference/credits
context:
credits_required: 5
credits_available: 2.5
credits_needed: 2.5
meta:
request_id: ea6e3248-f4d2-437d-bca3-20881b529129
timestamp: '2024-02-01T12:00:00.000Z'
RateLimitExceededError:
allOf:
- $ref: '#/components/schemas/ErrorResponse'
example:
success: false
errors:
- type: https://api.leadmagic.io/errors/rate_limit_exceeded
title: >-
Rate limit exceeded: 300 requests per 1 minute. Wait and try
again.
status: 429
code: rate_limit_exceeded
detail: >-
You have exceeded the maximum allowed request rate. Please wait
before making additional requests.
action: >-
Wait 42 seconds before retrying. Consider implementing exponential
backoff.
docs: https://leadmagic.io/docs/api-reference/rate-limits
context:
limit: 300
window: 1 minute
remaining: 0
reset_at: 1706745642
retry_after_seconds: 42
meta:
request_id: ea6e3248-f4d2-437d-bca3-20881b529129
timestamp: '2024-02-01T12:00:00.000Z'
InternalServerError:
allOf:
- $ref: '#/components/schemas/ErrorResponse'
example:
success: false
errors:
- type: https://api.leadmagic.io/errors/INTERNAL_ERROR
title: >-
Something went wrong on our end. Our team has been notified and is
investigating.
status: 500
code: INTERNAL_ERROR
detail: >-
This is a temporary server error. The issue has been automatically
reported to our team.
action: >-
Wait 30 seconds and retry your request. If the problem persists,
contact support@leadmagic.io
docs: https://leadmagic.io/docs/api-reference/errors
meta:
request_id: ea6e3248-f4d2-437d-bca3-20881b529129
timestamp: '2024-02-01T12:00:00.000Z'
ErrorResponse:
type: object
description: RFC 9457 Problem Details error response
required:
- success
- errors
properties:
success:
type: boolean
example: false
description: Always false for error responses
errors:
type: array
description: Array of error details (typically one, but can be multiple)
items:
$ref: '#/components/schemas/ErrorDetail'
meta:
$ref: '#/components/schemas/ResponseMeta'
ErrorDetail:
type: object
description: RFC 9457 compliant error detail
required:
- type
- title
- status
properties:
type:
type: string
format: uri
description: RFC 9457 - URI reference identifying the error type
example: https://api.leadmagic.io/errors/validation_error
title:
type: string
description: RFC 9457 - Short human-readable summary
example: Request validation failed. Check your input parameters.
status:
type: integer
description: RFC 9457 - HTTP status code
example: 400
detail:
type: string
description: RFC 9457 - Human-readable explanation specific to this occurrence
example: The email field is required but was not provided.
instance:
type: string
format: uri
description: RFC 9457 - URI reference for this specific occurrence
example: /v1/people/email-validation#req_abc123
code:
type: string
description: Machine-readable error code for programmatic handling
example: validation_error
param:
type: array
description: Parameters that caused the error
items:
type: string
example:
- email
action:
type: string
description: Suggested action to resolve the error
example: Provide a valid email address in the 'email' field.
docs:
type: string
format: uri
description: Link to relevant documentation
example: https://leadmagic.io/docs/api-reference/errors
context:
type: object
description: Additional context specific to this error type
additionalProperties: true
ResponseMeta:
type: object
description: Metadata included in all responses
properties:
request_id:
type: string
format: uuid
description: Unique identifier for this request (use for debugging/support)
example: ea6e3248-f4d2-437d-bca3-20881b529129
timestamp:
type: string
format: date-time
description: ISO 8601 timestamp when the response was generated
example: '2024-02-01T12:00:00.000Z'
environment:
type: string
description: API environment (production, staging)
example: production
securitySchemes:
ApiKeyAuth:
type: apiKey
in: header
name: X-API-Key
description: >-
Your LeadMagic API key. Header name is case-insensitive (X-API-Key,
X-API-KEY, x-api-key all work).
````