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

> POST /v1/email-finder — find verified work emails by name + company. 97% accuracy.

# Find Work Email

Find professional email addresses from a person's name and company. Every email found is automatically validated for deliverability.

## Endpoint Details

> [tab] Pricing
>
> | Metric | Value |
> | - | - |
> | **Cost** | **1 credit** per valid email found |
> | **No Results** | **FREE** if no email found (`null`) |
>
> > [!TIP]
> >
> > You only pay when we find a `valid` email. If no email is found (status `null`), you are not charged.

> [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-finder' \
  -H 'X-API-Key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "first_name": "Jesse",
    "last_name": "Ouellette",
    "domain": "leadmagic.io"
  }'
```

```javascript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
const response = await fetch('https://api.leadmagic.io/v1/people/email-finder', {
  method: 'POST',
  headers: {
    'X-API-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    first_name: 'Jesse',
    last_name: 'Ouellette',
    domain: 'leadmagic.io'
  })
});
const data = await response.json();
if (data.status === 'valid') {
  console.log(`Found: ${data.email}`);
} else {
  console.log('No email found (not charged)');
}
```

```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
import requests

response = requests.post(
    'https://api.leadmagic.io/v1/people/email-finder',
    headers={'X-API-Key': 'YOUR_API_KEY'},
    json={
        'first_name': 'Jesse',
        'last_name': 'Ouellette',
        'domain': 'leadmagic.io'
    }
)
data = response.json()
if data.get('status') == 'valid':
    print(f"Found: {data['email']}")
else:
    print('No email found (not charged)')
```

***

## Request Parameters

**first\_name** `string`

Person's first name. Required if `full_name` not provided. If both are sent, `first_name` + `last_name` are used first.

**last\_name** `string`

Person's last name. Required if `full_name` not provided.

**full\_name** `string`

Person's full name. Alternative to `first_name` + `last_name`. Leave this field out when sending split names.

**domain** `string`

Company website domain (preferred). More accurate than `company_name`; if both are sent, `domain` is used first.

**company\_name** `string`

Company name. Use only if `domain` is not available.

> [!WARNING]
>
> You must provide at least one name field (`first_name`, `last_name`, or `full_name`) AND one company field (`domain` or `company_name`).

***

## Response

**email** `string`

The found email address (`null` if not found)

**status** `string` *required*

Result status: `valid` or `null`

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

Credits used (1 for `valid`, 0 for `null`)

**message** `string` *required*

Human-readable status message

**employment\_verified** `boolean`

Whether employment at this company was verified

**Deliverability Intelligence**

**mx\_record** `string`

Primary MX record

**mx\_provider** `string`

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

**has\_mx** `boolean`

Whether the domain has valid MX records

**Company Data (Included Free)**

**company\_name** `string`

Company name

**company\_industry** `string`

Company industry

**company\_size** `string`

Employee count range

**company\_profile\_url** `string`

Professional profile URL

### Example Responses

```json Valid Email Found theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "email": "jesse.ouellette@leadmagic.io",
  "status": "valid",
  "credits_consumed": 1,
  "message": "Valid email found.",
  "first_name": "Jesse",
  "last_name": "Ouellette",
  "domain": "leadmagic.io",
  "mx_provider": "Example Mail",
  "employment_verified": true,
  "company_name": "LeadMagic",
  "company_industry": "Technology"
}
```

```json No Email Found (Free) theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "email": null,
  "status": null,
  "credits_consumed": 0,
  "message": "No email found for this person at this company.",
  "first_name": "Jesse",
  "last_name": "Ouellette",
  "domain": "leadmagic.io"
}
```

***

## Status Codes

> [card] valid
>
> **1 credit** - Email immediately
>
> Verified email found. Safe to send.

> [card] null
>
> **FREE** - No email found
>
> No email found for this person at this company. Not charged.

***

## Best Practices

> [accordion] Use domain over company name
>
> Domain lookups are more accurate. `leadmagic.io` will always find the right company, while "LeadMagic" might match similar names.

> [accordion] Check employment verification
>
> The `employment_verified` field tells you if we confirmed this person works at the company.

> [accordion] Handle null results gracefully
>
> If the result is `null`, try variations: different name spellings, company domain instead of name, or `full_name` instead of `first_name`/`last_name`.

***

## Use Cases

> [card] Sales Outreach
>
> Find decision-maker emails for personalized outreach campaigns.

> [card] Lead Enrichment
>
> Complete partial lead records with verified email addresses.

> [card] ABM Campaigns
>
> Build contact lists for target accounts with verified emails.

> [card] Recruiting
>
> Reach passive candidates with verified work emails.


## OpenAPI

````yaml post /v1/people/email-finder
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-finder:
    post:
      tags:
        - People Enrichment
      summary: Email Finder
      description: >-
        Find a person's work email address using their name and company
        information.
      operationId: email-finder
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                first_name:
                  type: string
                  description: >-
                    First name of the person. If both split names and full_name
                    are sent, first_name + last_name are used first.
                  example: Jesse
                last_name:
                  type: string
                  nullable: true
                  description: >-
                    Last name of the person. Send with first_name when
                    available.
                  example: Ouellette
                full_name:
                  type: string
                  nullable: true
                  description: >-
                    Full name of the person. Alternative to first_name +
                    last_name; omit when sending split names.
                  example: Jesse Ouellette
                domain:
                  type: string
                  description: >-
                    Company domain name. Preferred over company_name; if both
                    are sent, domain is used first.
                  example: leadmagic.io
                company_name:
                  type: string
                  description: Company name. Use only if domain is not available.
                  example: LeadMagic
            example:
              first_name: Jesse
              last_name: Ouellette
              domain: leadmagic.io
      responses:
        '200':
          description: Successful response with email details
          content:
            application/json:
              schema:
                type: object
                properties:
                  email:
                    type: string
                    nullable: true
                    example: jesse.ouellette@leadmagic.io
                  status:
                    type: string
                    nullable: true
                    example: valid
                  credits_consumed:
                    type: integer
                    example: 1
                  message:
                    type: string
                    example: Email was confidently found and verified.
                  first_name:
                    type: string
                    example: Jesse
                  last_name:
                    type: string
                    example: Ouellette
                  domain:
                    type: string
                    example: leadmagic.io
                  mx_record:
                    type: string
                    example: alt3.mx1.example.com
                  mx_provider:
                    type: string
                    example: Example Mail
                  mx_security_gateway:
                    type: boolean
                    example: false
                  has_mx:
                    type: boolean
                    description: Whether the domain has MX records
                    example: true
                  mx_records_full:
                    type: array
                    description: Complete list of MX records with priorities
                    items:
                      type: object
                      properties:
                        priority:
                          type: integer
                          example: 10
                        exchange:
                          type: string
                          example: mx1.example.com
                  company_name:
                    type: string
                    example: Leadmagic
                  company_industry:
                    type: string
                    example: ''
                  company_size:
                    type: string
                    example: 11-50
                  company_founded:
                    type: integer
                    example: 2022
                  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, massachusetts
                      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
                        example: null
                      postal_code:
                        type: string
                        example: '02210'
                      geo:
                        type: string
                        example: 42.35,-71.06
                  company_profile_url:
                    type: string
                    example: leadmagichq
                  company_profile_id:
                    type: string
                    example: '75153174'
                  company_facebook_url:
                    type: string
                    example: ''
                  company_twitter_url:
                    type: string
                    example: ''
                  company_type:
                    type: string
                    example: private
                  employment_verified:
                    type: boolean
                    nullable: true
                    description: Whether the employment at the domain was verified
                    example: true
        '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.