> ## Documentation Index
> Fetch the complete documentation index at: https://docs.enricho.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Email Intelligence

> Compliance, gender, validity, identity and breaches for email addresses, 5 credits per check.

Send the addresses in `emails` and the checks to run in `checks`. Each result has a section for every check you asked for.

```bash theme={null}
curl -X POST 'https://api.enricho.co/api/directory/email/intelligence' \
  -H 'Authorization: Bearer enr_YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"emails":["jane@company.com","sam@example.org"],"checks":["compliance","validity"]}'
```

## Checks

| Check | What it answers |
| - | - |
| `compliance` | The recipient's country and whether a cold email to them is allowed there, with the law, the conditions to meet and any exceptions. |
| `gender` | From the person's record when Enricho holds it, otherwise inferred from the name in the address (`source: "name_inference"`), with how sure it is. |
| `validity` | Valid format, whether the domain receives mail, and whether it's a throwaway or shared inbox (`info@`). The mailbox itself isn't probed yet (`mailbox: "not_checked"`). |
| `identity` | Who the address belongs to and their company: name, job title, LinkedIn and location, and the company's industry, size and head office. From Enricho's records, else LinkedIn. |
| `breaches` | The data breaches the address appears in, from [Have I Been Pwned](https://haveibeenpwned.com). Sensitive breaches are never included. |

Up to 100 checks per request, counting addresses × checks: 100 addresses with one check, or 20 addresses with all five.

## Identity

`match` says how the person was found:

| `match` | Meaning |
| - | - |
| `email` | Enricho's record of the person holds this exact address. |
| `name_at_company` | Someone with the name in the address (`anna.schmidt@`) works at the domain's company. A likely match: the address itself isn't confirmed as theirs. |

When the person isn't found, `company` can still describe the company behind the domain. Identity is charged when either is found.

## Compliance

The recipient's country is found in this order:

| `country_source` | `country_confidence` | Meaning |
| - | - | - |
| `person_record` | `high` | The address belongs to a person in Enricho, and their location is known. |
| `name_match` | `medium` | Someone with the name in the address (like `anna.schmidt@`) works at the domain's company: where they are. |
| `company_hq` | `medium` | The head office country of the domain's company. The person may work elsewhere. |
| `domain_tld` | `low` | The domain's country ending. Endings used worldwide (`.io`, `.co`, `.ai`…) are ignored. |

| `verdict` | Meaning |
| - | - |
| `allowed` | A cold email is allowed without prior consent if you meet every item in `conditions`. |
| `consent_required` | You need the recipient's prior consent, unless one of the `exceptions` applies to you. |
| `do_not_send` | A throwaway inbox or a domain that takes no mail. |
| `unknown` | No country found, or no rules for that country yet. |

Most laws treat a company address differently from a personal mailbox, so `recipient_type` (`business` or `personal`) changes the verdict. Where a law's position on business email is unclear, the stricter answer is returned.

> [!NOTE]
>
> Compliance is a summary of each country's cold-email rules, not legal advice. `rules_version` names the rules that answered; check with counsel before relying on a verdict.

## Credits

Each check on each address costs 5 credits, and only when it has an answer. These are free:

* an unknown gender or compliance country, and an identity where neither the person nor the company is found
* a breach lookup that didn't answer in time (`status: "unavailable"`)
* addresses that aren't valid
* any check you ran on the same address in the last year (counted in `already_purchased`)


## OpenAPI

````yaml api-reference/openapi.json POST /api/directory/email/intelligence
openapi: 3.1.0
info:
  title: Enricho Public REST API
  version: 1.0.0
  description: >-
    Public directory search and billing APIs. Every search costs 5 credits per
    new record; usage calls use no credits. The REST API has no previews:
    sending preview true returns 422. Request and response contracts reflect the
    current public gateway and service handlers.
servers:
  - url: https://api.enricho.co
security:
  - apiKey: []
  - headerKey: []
tags:
  - name: Directory
  - name: Billing
paths:
  /api/directory/email/intelligence:
    post:
      tags:
        - Directory
      summary: Email Intelligence
      description: >-
        Run checks on 1-100 email addresses: compliance (the recipient's country
        and whether a cold email is allowed there), gender, validity (format,
        mail servers, throwaway and shared inboxes; mailboxes are not probed),
        identity (who the address belongs to, from Enricho's records) and
        breaches (from Have I Been Pwned). Up to 100 checks per request
        (addresses × checks). Each check on each address costs 5 credits,
        charged only when it has an answer: an unknown gender or country, no
        identity found, a breach lookup that didn't answer and invalid addresses
        are free, as is any check the caller ran on the same address in the last
        year. Results are released only after an atomic debit is confirmed.
        Compliance is a summary of each country's rules, not legal advice;
        breach data comes from Have I Been Pwned.
      operationId: emailIntelligence
      requestBody:
        required: true
        description: 'Send JSON with Content-Type: application/json.'
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EmailIntelRequest'
            examples:
              cold:
                summary: May I cold email these?
                value:
                  emails:
                    - jane@company.com
                    - sam@example.org
                  checks:
                    - compliance
                    - validity
              who:
                summary: Who is this, and were they breached?
                value:
                  emails: jane@company.com
                  checks:
                    - identity
                    - breaches
      responses:
        '200':
          description: Success envelope.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    const: true
                  result:
                    $ref: '#/components/schemas/EmailIntelResponse'
                  message:
                    type: string
                required:
                  - success
                  - result
                  - message
        '400':
          description: 'bad_request: malformed JSON.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: 'unauthorized: missing, invalid or revoked API key.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '402':
          description: >-
            insufficient_credits: insufficient balance for the answered checks.
            No results returned and no credits deducted.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '405':
          description: 'method_not_allowed: this route takes POST.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '413':
          description: 'payload_too_large: the body is over 1 MiB.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '422':
          description: >-
            validation_failed: no addresses or checks, an unknown check, more
            than 100 checks (addresses × checks), blank values, unknown fields
            or wrong types. A rejected request costs nothing.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: >-
            rate_limited: key, account or IP request limit exceeded; wait a
            minute before retrying.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: 'internal: unexpected server failure.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '502':
          description: 'upstream_unavailable: gateway could not reach the service.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '503':
          description: >-
            upstream_unavailable: the breaches check is switched off (run the
            other checks without it), or directory or billing is unavailable. No
            results are returned; an unconfirmed charge may already have debited
            credits, so inspect usage before retrying.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    EmailIntelRequest:
      type: object
      additionalProperties: false
      required:
        - emails
        - checks
      properties:
        emails:
          description: One address, or a list of up to 100. Duplicates are checked once.
          oneOf:
            - type: string
              maxLength: 200
            - type: array
              minItems: 1
              maxItems: 100
              items:
                type: string
                maxLength: 200
        checks:
          description: The checks to run on every address.
          oneOf:
            - type: string
              enum:
                - compliance
                - gender
                - validity
                - identity
                - breaches
            - type: array
              minItems: 1
              maxItems: 5
              items:
                type: string
                enum:
                  - compliance
                  - gender
                  - validity
                  - identity
                  - breaches
    EmailIntelResponse:
      type: object
      required:
        - results
        - checks
        - credits_used
        - already_purchased
      properties:
        results:
          type: array
          items:
            $ref: '#/components/schemas/EmailIntelResult'
        checks:
          type: array
          items:
            type: string
          description: The checks that ran.
        credits_used:
          type: integer
        already_purchased:
          type: integer
          description: Checks run on the same address in the last year, free this time.
        rules_version:
          type: string
          description: 'With compliance: the date of the rules that answered.'
        disclaimer:
          type: string
          description: With compliance.
    Error:
      type: object
      properties:
        success:
          type: boolean
          const: false
        result:
          type: object
          properties:
            code:
              type: string
              description: Machine-readable error code.
          required:
            - code
        message:
          type: string
          description: Human-readable error; do not parse this as a stable identifier.
      required:
        - success
        - result
        - message
    EmailIntelResult:
      type: object
      required:
        - email
        - valid
      properties:
        email:
          type: string
          description: The address, lower-cased.
        valid:
          type: boolean
          description: >-
            false when it isn't an email address; such addresses have only
            reason and are free.
        reason:
          type: string
        compliance:
          $ref: '#/components/schemas/EmailIntelCompliance'
        gender:
          $ref: '#/components/schemas/EmailIntelGender'
        validity:
          $ref: '#/components/schemas/EmailIntelValidity'
        identity:
          $ref: '#/components/schemas/EmailIntelIdentity'
        breaches:
          $ref: '#/components/schemas/EmailIntelBreaches'
      description: Each check that ran has its section.
    EmailIntelCompliance:
      type: object
      required:
        - recipient_type
        - verdict
        - reason
        - conditions
        - exceptions
        - sources
      properties:
        recipient_type:
          type: string
          enum:
            - business
            - personal
          description: >-
            personal for mailbox providers such as Gmail or Outlook, else
            business.
        country_code:
          type: string
          description: ISO 3166-1 alpha-2 of the recipient's country, when found.
        country_source:
          type: string
          enum:
            - person_record
            - name_match
            - company_hq
            - domain_tld
        country_confidence:
          type: string
          enum:
            - high
            - medium
            - low
        verdict:
          type: string
          enum:
            - allowed
            - consent_required
            - do_not_send
            - unknown
          description: >-
            allowed: cold email allowed if the conditions are met.
            consent_required: needs prior consent unless an exception applies.
            do_not_send: throwaway inbox or a domain that takes no mail.
            unknown: no country found or no rule for it yet (free).
        law:
          type: string
        reason:
          type: string
        conditions:
          type: array
          items:
            type: string
          description: What the sender must do when sending.
        exceptions:
          type: array
          items:
            type: string
          description: Ways to send without prior consent where it is otherwise required.
        sources:
          type: array
          items:
            type: string
            format: uri
          description: >-
            Official pages (legislation, regulator guidance) the country's rule
            was checked against.
    EmailIntelGender:
      type: object
      required:
        - gender
      properties:
        gender:
          type: string
          enum:
            - male
            - female
            - unknown
          description: >-
            unknown (free) for shared inboxes, addresses without a first name
            and names used by both genders.
        probability:
          type: number
          description: How sure the source is, 0-1 (1 for person_record).
        source:
          type: string
          enum:
            - person_record
            - name_inference
          description: >-
            person_record: the person's record in Enricho. name_inference:
            inferred from the name in the address.
        first_name:
          type: string
          description: The first name read from the address.
    EmailIntelValidity:
      type: object
      required:
        - status
        - reason
        - domain_accepts_mail
        - disposable
        - role_address
        - free_provider
        - mailbox
      properties:
        status:
          type: string
          enum:
            - valid
            - risky
            - invalid
            - unknown
          description: >-
            invalid: the domain takes no mail. risky: a throwaway or shared
            inbox. unknown: DNS didn't answer.
        reason:
          type: string
        domain_accepts_mail:
          type:
            - boolean
            - 'null'
          description: >-
            The domain has mail servers (MX, or an address record). null when
            DNS didn't answer.
        disposable:
          type: boolean
        role_address:
          type: boolean
          description: A shared inbox such as info@ or sales@.
        free_provider:
          type: boolean
          description: A personal mailbox provider such as Gmail or Outlook.
        mailbox:
          type: string
          enum:
            - not_checked
          description: Whether the mailbox itself exists isn't checked yet.
    EmailIntelIdentity:
      type: object
      required:
        - found
      properties:
        found:
          type: boolean
          description: >-
            Whether the person was found. Identity is free when neither the
            person nor the company is found.
        match:
          type: string
          enum:
            - email
            - name_at_company
          description: >-
            email: Enricho's record holds this address. name_at_company: someone
            with the name in the address (like anna.schmidt@) works at the
            domain's company; the address itself isn't confirmed as theirs.
        person_id:
          type: string
        full_name:
          type: string
        job_title:
          type: string
        seniority:
          type: string
        linkedin_url:
          type: string
        city:
          type: string
        country_code:
          type: string
          description: Where the person is.
        company:
          $ref: '#/components/schemas/EmailIntelCompany'
          description: >-
            The company behind the address's domain (not for personal
            mailboxes).
    EmailIntelBreaches:
      type: object
      required:
        - status
        - breached
        - count
        - breaches
        - source
      properties:
        status:
          type: string
          enum:
            - ok
            - unavailable
          description: >-
            unavailable (free): Have I Been Pwned didn't answer in time; try
            again later.
        breached:
          type: boolean
        count:
          type: integer
        breaches:
          type: array
          items:
            $ref: '#/components/schemas/EmailIntelBreach'
          description: Newest first. Sensitive breaches are never included.
        source:
          type: string
          const: Have I Been Pwned
    EmailIntelCompany:
      type: object
      properties:
        company_id:
          type: string
        name:
          type: string
        domain:
          type: string
        industry:
          type: string
        employee_size_band:
          type: string
        linkedin_url:
          type: string
        country_code:
          type: string
          description: Head office country, ISO 3166-1 alpha-2.
    EmailIntelBreach:
      type: object
      required:
        - name
        - title
        - data_classes
        - verified
      properties:
        name:
          type: string
        title:
          type: string
        domain:
          type: string
        breach_date:
          type: string
          format: date
        data_classes:
          type: array
          items:
            type: string
          description: What leaked, e.g. Email addresses, Passwords.
        verified:
          type: boolean
  securitySchemes:
    apiKey:
      type: http
      scheme: bearer
      description: Enricho API key (enr_...)
    headerKey:
      type: apiKey
      in: header
      name: X-Api-Key
      description: >-
        An Enricho API key (enr_...). Use this or Authorization: Bearer, not
        both.

````

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