# Email Enrichment

Enriches contact records with email address data using multiple data sources.

## Overview
The Email Enrichment API enriches contact records with email address data using multiple data sources. The service uses various lookup methods to find professional email addresses for contacts based on their name and company information.

## Request Body
- record_id: Your unique identifier for this record (required) - used for caching and duplicate detection
- first_name: Contact's first name (required)
- last_name: Contact's last name (required)
- company: Company name or website URL where the contact works (required)
- domain: Company domain (optional) - if not provided, will be extracted from company field
- linkedin: Contact's linkedin url (optional) - improves lookup accuracy when available
- max_credits: Maximum credits to spend on this request (optional, defaults to your account limit)

## Request Constraints
- Single record per request
- Must include record_id, first_name, last_name, and company
- record_id must be unique per contact record in your system
- domain is optional but improves accuracy when provided
- linkedin is optional but improves accuracy when provided
- max_credits must be a positive integer if provided

## Response Fields
- success: Boolean indicating request success
- record_id: Echo of the input record ID
- first_name: Echo of input first name
- last_name: Echo of input last name
- company: Echo of input company
- email: Professional email address or null if not found
- confidence: Confidence level (high, medium, low) or null
- credits_consumed: Number of credits used for this request
- credits_remaining: Credits remaining in your account after this request
- processing_time_ms: Time taken to process the request in milliseconds
- cached: Boolean indicating if this result was returned from cache (no credits consumed if true)

## Credit Usage
Email enrichment consumes credits based on the data sources queried:
- Cached Result: 0 credits (if same record_id queried recently)
- Email Search: 5 credits

Endpoint: POST /v1/enrich/email
Version: 1.4.1
Security: BearerAuth

## Request fields (application/json):

  - `record_id` (string, required)
    Your unique identifier for this record

  - `first_name` (string, required)
    Contact's first name

  - `last_name` (string, required)
    Contact's last name

  - `company` (string, required)
    Company name or website URL where the contact works

  - `company_domain` (any)
    Company domain (optional)

  - `linkedin_id` (any)
    LinkedIn profile identifier/slug (e.g., 'john-doe-123456')

  - `max_credits` (any)
    Maximum credits to spend on this request

## Response 200 fields (application/json):

  - `success` (boolean, required)
    Boolean indicating request success

  - `record_id` (string, required)
    Echo of the input record ID

  - `first_name` (string, required)
    Echo of input first name

  - `last_name` (string, required)
    Echo of input last name

  - `company` (string, required)
    Echo of input company

  - `email` (any)
    Professional email address or null if not found

  - `confidence` (any)
    Confidence score (0.0-1.0) or null if disabled/not found

  - `credits_consumed` (integer, required)
    Number of credits used for this request

  - `credits_remaining` (integer, required)
    Credits remaining in your account after this request

  - `processing_time_ms` (integer, required)
    Time taken to process the request in milliseconds

  - `cached` (boolean, required)
    Boolean indicating if this result was returned from cache

## Response 400 fields (application/json):

  - `success` (boolean)
    Always false for error responses

  - `error` (string, required)
    Error message

  - `details` (any)
    Additional error details

  - `request_id` (any)
    Request ID for tracking

  - `credits_required` (any)
    Credits required for insufficient credit errors

  - `credits_remaining` (any)
    Credits remaining for insufficient credit errors

  - `retry_after` (any)
    Seconds to wait before retrying for rate limit errors

## Response 401 fields (application/json):

  - `success` (boolean)
    Always false for error responses

  - `error` (string, required)
    Error message

  - `details` (any)
    Additional error details

  - `request_id` (any)
    Request ID for tracking

  - `credits_required` (any)
    Credits required for insufficient credit errors

  - `credits_remaining` (any)
    Credits remaining for insufficient credit errors

  - `retry_after` (any)
    Seconds to wait before retrying for rate limit errors

## Response 402 fields (application/json):

  - `success` (boolean)
    Always false for error responses

  - `error` (string, required)
    Error message

  - `details` (any)
    Additional error details

  - `request_id` (any)
    Request ID for tracking

  - `credits_required` (any)
    Credits required for insufficient credit errors

  - `credits_remaining` (any)
    Credits remaining for insufficient credit errors

  - `retry_after` (any)
    Seconds to wait before retrying for rate limit errors

## Response 422 fields (application/json):

  - `detail` (array)

  - `detail.loc` (array, required)

  - `detail.msg` (string, required)

  - `detail.type` (string, required)

## Response 429 fields (application/json):

  - `success` (boolean)
    Always false for error responses

  - `error` (string, required)
    Error message

  - `details` (any)
    Additional error details

  - `request_id` (any)
    Request ID for tracking

  - `credits_required` (any)
    Credits required for insufficient credit errors

  - `credits_remaining` (any)
    Credits remaining for insufficient credit errors

  - `retry_after` (any)
    Seconds to wait before retrying for rate limit errors

## Response 500 fields (application/json):

  - `success` (boolean)
    Always false for error responses

  - `error` (string, required)
    Error message

  - `details` (any)
    Additional error details

  - `request_id` (any)
    Request ID for tracking

  - `credits_required` (any)
    Credits required for insufficient credit errors

  - `credits_remaining` (any)
    Credits remaining for insufficient credit errors

  - `retry_after` (any)
    Seconds to wait before retrying for rate limit errors