> ## 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

> [tab] Pricing
>
> | Metric | Value |
> | - | - |
> | **Cost** | **0.25 credits** per validation |
> | **Calculation** | 4 validations = 1 credit |
> | **Free Results** | `unknown` and RFC-invalid results are free |
>
> > [!TIP]
> >
> > You only pay for definitive SMTP results (`valid`, `invalid`). Inconclusive results (`unknown`) and RFC syntax failures are always free.
>
> > [!NOTE]
> >
> > **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.

> [tab] Rate Limits
>
> ### Per-Endpoint Limit
>
> | Metric | Value |
> | - | - |
> | **Requests/Minute** | 300 |
> | **Burst Capacity** | \~5 requests/second |
>
> > [!NOTE]
> >
> > 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

**email** `string` *required*

The email address to validate. Must be a properly formatted email address.

***

## Response

**email** `string` *required*

The validated email address (normalized)

**email\_status** `string` *required*

Validation result: `valid`, `invalid`, or `unknown`

**credits\_consumed** `number` *required*

Credits used for this request (0.25 for `valid`/`invalid`, 0 for `unknown`)

**message** `string` *required*

Human-readable status message

**mx\_record** `string`

Primary MX record for the domain

**mx\_provider** `string`

Email provider (Example Mail, Example Mail Suite, etc.)

**mx\_gateway** `string`

Security gateway vendor name (null if none)

**mx\_gateway\_type** `string`

Security gateway type (null if none)

**mx\_security\_gateway** `boolean`

Whether a security gateway is present

**Company Data (Included Free)**

**company\_name** `string`

Company name derived from email domain

**company\_industry** `string`

Company industry

**company\_size** `string`

Employee count range

**company\_founded** `integer`

Year founded

**company\_type** `string`

Ownership type (private, public, etc.)

**company\_linkedin\_url** `string`

B2B company profile URL

**company\_linkedin\_id** `string`

B2B company profile ID

**company\_facebook\_url** `string`

Facebook page URL (null if unavailable)

**company\_twitter\_url** `string`

Twitter/X profile URL (null if unavailable)

**company\_location** `object`

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

> [card] valid
>
> **Safe to email** - Bounce rate \<1%
>
> Email verified by mail server. Costs 0.25 credits.

> [card] invalid
>
> **Do NOT email** - Will bounce
>
> Mail server confirmed non-existent. Costs 0.25 credits.

> [card] unknown
>
> **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) |

> [!NOTE]
>
> 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

> [accordion] Pre-validate format client-side
>
> 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]
> >
> > Note: Our API catches all RFC violations, but client-side pre-validation can reduce unnecessary API calls.

> [accordion] Validate before sending campaigns
>
> Always validate your email list before sending to maintain high deliverability and protect your sender reputation. Invalid emails hurt your domain reputation.

> [accordion] Handle unknown results
>
> For `unknown` results, consider retrying later or using Email Finder to verify the specific address exists before adding to campaigns.

> [accordion] Batch your validations
>
> 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
> }
> ```

> [accordion] Use response headers for monitoring
>
> Every response includes `X-Credits-Remaining` so you can track spending without extra API calls.

***

## Use Cases

> [card] List Cleaning
>
> Validate email lists before campaigns to reduce bounces and protect sender reputation.

> [card] Form Validation
>
> Validate emails at point of capture to ensure data quality from the start.

> [card] CRM Hygiene
>
> Regularly validate CRM contacts to maintain deliverability rates.

> [card] Lead Scoring
>
> 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).

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.