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

# Email Compliance

> Resolve which country's cold-email law applies to an address, and get that jurisdiction's recommendation. 1 credit, with free repeats.

## Overview

Email Compliance answers one question: **may I cold-email this address, and under
whose law?** It resolves an email to the most likely jurisdiction, returns that
jurisdiction's rule and recommendation, and tells you how much to trust the
attribution.

The verdict can arrive in **two phases**. Most checks resolve inside the request;
a deeper attribution check may still be running when the first response returns.
In that case the response carries `pending` and a provisional verdict, and the
result is finalised shortly after - subscribe to [realtime events](/webhooks) to
be notified when it settles.

## Authentication

Requires an API key in the `Authorization` header.

```bash theme={"dark"}
Authorization: Bearer YOUR_API_KEY
```

## Request

<ParamField body="email" type="string" required>
  The email address to place under a jurisdiction.
</ParamField>

### Example request

<CodeGroup>
  ```bash cURL (API Key) theme={"dark"}
  curl -X POST "https://developer.encrata.com/api/lookup/email/compliance" \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{"email": "priya.sharma@example.in"}'
  ```

  ```python Python theme={"dark"}
  import requests

  resp = requests.post(
      "https://developer.encrata.com/api/lookup/email/compliance",
      headers={"Authorization": "Bearer YOUR_API_KEY"},
      json={"email": "priya.sharma@example.in"},
  )
  print(resp.json())
  ```

  ```javascript JavaScript theme={"dark"}
  const resp = await fetch("https://developer.encrata.com/api/lookup/email/compliance", {
    method: "POST",
    headers: {
      Authorization: "Bearer YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ email: "priya.sharma@example.in" }),
  });
  const data = await resp.json();
  ```
</CodeGroup>

## Response

Unlike the older email endpoints, this route always returns the
`{success, result, message}` envelope - including on validation and method
errors. The HTTP status is real; a `200` never carries `success: false`.

<ResponseField name="success" type="boolean">
  Whether the lookup succeeded.
</ResponseField>

<ResponseField name="message" type="string">
  A sentence written for your end user. It already reflects whether the verdict
  is provisional, confident, or unknown - render it as-is rather than composing
  your own from the fields.
</ResponseField>

<ResponseField name="result" type="object">
  The applicable jurisdiction and its cold-email rule.

  <Expandable title="result">
    <ResponseField name="email" type="string">
      The address that was placed.
    </ResponseField>

    <ResponseField name="country" type="string">
      Resolved country name. Empty when `confidence` is `unknown`.
    </ResponseField>

    <ResponseField name="country_code" type="string">
      ISO alpha-2 code. Absent when `confidence` is `unknown`. When
      `confidence` is `medium`, this is the **strictest** of
      `jurisdictions_applicable`, not simply the most likely.
    </ResponseField>

    <ResponseField name="email_type" type="string">
      `consumer` or `business`.
    </ResponseField>

    <ResponseField name="recommendation_code" type="string">
      One of `prohibited`, `consent_required`, `allowed_with_conditions`,
      `allowed_by_policy`.
    </ResponseField>

    <ResponseField name="recommendation" type="string">
      The plain-language recommendation for this jurisdiction.
    </ResponseField>

    <ResponseField name="main_laws" type="string[]">
      The governing laws (e.g. `["Digital Personal Data Protection Act 2023"]`).
    </ResponseField>

    <ResponseField name="law_reference_urls" type="string[]">
      Reference URLs for the cited laws.
    </ResponseField>

    <ResponseField name="main_restrictions" type="string[]">
      The key restrictions that apply.
    </ResponseField>

    <ResponseField name="applicability" type="string">
      Scope note (e.g. national scope, sector rules may add requirements).
    </ResponseField>

    <ResponseField name="confidence" type="string">
      `confident`, `medium`, or `unknown`. Drives the whole presentation - see
      the table below.
    </ResponseField>

    <ResponseField name="jurisdictions_applicable" type="string[]">
      Every country still in contention. More than one entry means the strictest
      was applied.
    </ResponseField>

    <ResponseField name="possible_travel" type="string[]">
      Countries whose only evidence was a lone one-off signup - reported as
      travel, never counted as applicable law.
    </ResponseField>

    <ResponseField name="pending" type="boolean">
      `true` while the deeper attribution check is still running. When `true` the
      verdict is provisional and is finalised shortly after.
    </ResponseField>

    <ResponseField name="credits" type="number">
      Credits billed: `1` on a fresh charge, or `0` inside the free-repeat window.
    </ResponseField>

    <ResponseField name="cached" type="boolean">
      Present and `true` when served from a previous lookup.
    </ResponseField>
  </Expandable>
</ResponseField>

### `confidence` drives the presentation

| `confidence` | Means                                                                                                       | Suggested handling                                                                        |
| ------------ | ----------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- |
| `confident`  | A clear jurisdiction with corroborating evidence                                                            | Show the country and its rule plainly                                                     |
| `medium`     | A likely jurisdiction, thinner corroboration. `country_code` is the strictest of `jurisdictions_applicable` | Show the rule; say it is the strictest of several candidates                              |
| `unknown`    | Nothing established. `country`/`country_code` are empty and the restrictive default is returned             | Do **not** print a country; show `recommendation`/`main_restrictions` as generic guidance |

`unknown` is a deliberate answer, not a failure - the response is still `200`
with a usable restrictive recommendation. Treating it as an error is the most
common way to get this integration wrong.

## Errors

Every response - including errors - uses the envelope, with a stable code in
`result.code`.

| Status | `result.code`          | Cause                                              |
| ------ | ---------------------- | -------------------------------------------------- |
| `400`  | `bad_request`          | Unreadable body, or `email` is not a valid address |
| `401`  | `unauthorized`         | Missing or unusable credentials                    |
| `402`  | `insufficient_credits` | Not enough credits and not a free repeat           |
| `405`  | `method_not_allowed`   | Wrong HTTP method - POST only                      |
| `413`  | `payload_too_large`    | Body exceeded the size limit                       |
| `500`  | `internal_error`       | Unexpected server error                            |
| `503`  | `upstream_unavailable` | Temporarily unavailable; retry later               |

## Credits

Each lookup costs **1 credit**, with free repeats inside the billing window. A
repeat that finalises a previously provisional verdict is not charged again. See
[Credits](/credits).

<ResponseExample>
  ```json 200 Confident theme={"dark"}
  {
    "success": true,
    "result": {
      "email": "priya.sharma@example.in",
      "country": "India",
      "country_code": "IN",
      "email_type": "business",
      "recommendation_code": "allowed_by_policy",
      "recommendation": "Cold emailing is allowed.",
      "main_laws": ["Digital Personal Data Protection Act 2023"],
      "law_reference_urls": ["https://www.meity.gov.in/"],
      "main_restrictions": ["Provide an opt-out in every message"],
      "applicability": "National scope. Sector rules may add requirements.",
      "confidence": "confident",
      "jurisdictions_applicable": ["IN"],
      "possible_travel": [],
      "pending": false,
      "credits": 1
    },
    "message": "Cold emailing this address is allowed under India's rules."
  }
  ```

  ```json 200 Unknown theme={"dark"}
  {
    "success": true,
    "result": {
      "email": "anon@protonmail.com",
      "country": "",
      "email_type": "consumer",
      "recommendation_code": "consent_required",
      "recommendation": "Treat as consent-required. No jurisdiction could be established.",
      "confidence": "unknown",
      "jurisdictions_applicable": [],
      "possible_travel": [],
      "pending": false,
      "credits": 1
    },
    "message": "We couldn't establish a jurisdiction for this address. Treat it as consent-required."
  }
  ```

  ```json 402 theme={"dark"}
  { "success": false, "result": { "code": "insufficient_credits" },
    "message": "You don't have enough credits for this lookup. Top up to continue." }
  ```
</ResponseExample>