Email Compliance

curl -X POST "https://developer.encrata.com/api/lookup/email/compliance" \
  -H "Authorization: Bearer enc_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"email": "priya.sharma@example.in"}'

import requests

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

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

{
  "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"],
    "signals": {
      "points": 7,
      "max_points": 8,
      "checks": 4,
      "latency_ms": 412
    },
    "result_id": 918273,
    "credits": 1
  },
  "message": "Cold emailing this address is allowed under India's rules."
}

{
  "success": true,
  "result": {
    "email": "anon@protonmail.com",
    "country": "",
    "country_code": "",
    "email_type": "consumer",
    "recommendation_code": "consent_required",
    "recommendation": "Treat consent as required before emailing.",
    "main_laws": [],
    "law_reference_urls": [],
    "main_restrictions": [
      "We could not establish which country's rules apply to this address.",
      "Obtain explicit consent before sending, and include a clear unsubscribe option."
    ],
    "applicability": "No jurisdiction could be identified from this address. The strictest common requirements are shown; confirm the recipient's country before sending.",
    "confidence": "unknown",
    "signals": {
      "points": 0,
      "max_points": 8,
      "checks": 3,
      "latency_ms": 286
    },
    "result_id": 918274,
    "credits": 1
  },
  "message": "We couldn't establish a jurisdiction for this address. Treat it as consent-required."
}

{
  "success": true,
  "result": {
    "email": "sam@example.de",
    "country": "Germany",
    "country_code": "DE",
    "email_type": "business",
    "recommendation_code": "consent_required",
    "recommendation": "Obtain consent before emailing.",
    "main_laws": ["GDPR", "UWG"],
    "law_reference_urls": ["https://gdpr-info.eu/"],
    "main_restrictions": ["Prior opt-in required"],
    "applicability": "National scope. Sector rules may add requirements.",
    "confidence": "medium",
    "jurisdictions_applicable": ["DE", "AT"],
    "signals": {
      "points": 3,
      "max_points": 8,
      "checks": 2,
      "latency_ms": 190
    },
    "checking": true,
    "result_id": 918275,
    "credits": 1
  },
  "message": "Compliance resolved from the available signals. An additional check is still running and you'll be notified if it adds anything."
}

{ "success": false, "result": { "code": "insufficient_credits" },
  "message": "You don't have enough credits for this lookup. Top up to continue." }

POST

api

lookup

compliance

curl -X POST "https://developer.encrata.com/api/lookup/email/compliance" \
  -H "Authorization: Bearer enc_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"email": "priya.sharma@example.in"}'

import requests

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

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

{
  "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"],
    "signals": {
      "points": 7,
      "max_points": 8,
      "checks": 4,
      "latency_ms": 412
    },
    "result_id": 918273,
    "credits": 1
  },
  "message": "Cold emailing this address is allowed under India's rules."
}

{
  "success": true,
  "result": {
    "email": "anon@protonmail.com",
    "country": "",
    "country_code": "",
    "email_type": "consumer",
    "recommendation_code": "consent_required",
    "recommendation": "Treat consent as required before emailing.",
    "main_laws": [],
    "law_reference_urls": [],
    "main_restrictions": [
      "We could not establish which country's rules apply to this address.",
      "Obtain explicit consent before sending, and include a clear unsubscribe option."
    ],
    "applicability": "No jurisdiction could be identified from this address. The strictest common requirements are shown; confirm the recipient's country before sending.",
    "confidence": "unknown",
    "signals": {
      "points": 0,
      "max_points": 8,
      "checks": 3,
      "latency_ms": 286
    },
    "result_id": 918274,
    "credits": 1
  },
  "message": "We couldn't establish a jurisdiction for this address. Treat it as consent-required."
}

{
  "success": true,
  "result": {
    "email": "sam@example.de",
    "country": "Germany",
    "country_code": "DE",
    "email_type": "business",
    "recommendation_code": "consent_required",
    "recommendation": "Obtain consent before emailing.",
    "main_laws": ["GDPR", "UWG"],
    "law_reference_urls": ["https://gdpr-info.eu/"],
    "main_restrictions": ["Prior opt-in required"],
    "applicability": "National scope. Sector rules may add requirements.",
    "confidence": "medium",
    "jurisdictions_applicable": ["DE", "AT"],
    "signals": {
      "points": 3,
      "max_points": 8,
      "checks": 2,
      "latency_ms": 190
    },
    "checking": true,
    "result_id": 918275,
    "credits": 1
  },
  "message": "Compliance resolved from the available signals. An additional check is still running and you'll be notified if it adds anything."
}

{ "success": false, "result": { "code": "insufficient_credits" },
  "message": "You don't have enough credits for this lookup. Top up to continue." }

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 checking: true and a provisional verdict. To get the settled verdict, send the same request again. The repeat returns the finalised result and is not charged again during the 6-month free-repeat window, so polling costs nothing. result_id stays the same across both responses, so you can correlate them.

email.compliance_completed is an internal realtime event for the dashboard. It is not one of the subscribable webhook events, so you cannot register a webhook to be told when a verdict settles.

Authentication

Requires an API key in the Authorization header.

Authorization: Bearer enc_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Request

string

required

The email address to place under a jurisdiction.

Example request

curl -X POST "https://developer.encrata.com/api/lookup/email/compliance" \
  -H "Authorization: Bearer enc_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"email": "priya.sharma@example.in"}'

import requests

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

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

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.

boolean

Whether the lookup succeeded.

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.

object

The applicable jurisdiction and its cold-email rule.

Show result

string

The address that was placed.

string

Resolved country name. Empty when confidence is unknown.

string

ISO alpha-2 code. An empty string when confidence is unknown - the key is always present. When confidence is medium, this is the strictest of jurisdictions_applicable, not simply the most likely.

string

consumer or business.

string

The machine-readable verdict, ordered here from strictest to most permissive: prohibited, consent_required, exception_required, case_by_case, allowed_with_conditions, allowed, allowed_by_policy, safe_to_send.Branch on this rather than on recommendation, whose wording varies by jurisdiction. Treat an unrecognised code conservatively: the backend ranks unknown codes alongside case_by_case.

string

The plain-language recommendation for this jurisdiction.

string[]

The governing laws (e.g. ["Digital Personal Data Protection Act 2023"]).

string[]

Reference URLs for the cited laws.

string[]

The key restrictions that apply.

string

Scope note (e.g. national scope, sector rules may add requirements).

string

confident, medium, or unknown. Drives the whole presentation - see the table below.

string[]

Every country still in contention. More than one entry means the strictest was applied. Omitted when empty.

string[]

Countries whose only evidence was a lone one-off signup - reported as travel, never counted as applicable law. Omitted when empty.

object

Consolidated, provider-anonymized summary of the checks behind the verdict. Always present.

Show signals

number

Points earned from the checks that produced a usable signal.

number

The maximum points available. Use points / max_points as an evidence-strength ratio.

number

How many checks have reported, whether or not they contributed. A pending check is not counted until it reports.

number

Combined time across the checks that have reported, in milliseconds.

boolean

true while the deeper attribution check is still running. When true the verdict is provisional and is finalised shortly after.Omitted when false, so read it as “provisional if present and true”.

number

Row id for this result. The settled email.compliance_completed event correlates on this id. Omitted when zero.

number

Credits billed: 1 on a fresh charge, or 0 during the 6-month free-repeat window.

`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`	`This endpoint only accepts POST requests.`
`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 during the 6-month free-repeat window. A repeat that finalises a previously provisional verdict is not charged again. See Credits.

curl -X POST "https://developer.encrata.com/api/lookup/email/compliance" \
  -H "Authorization: Bearer enc_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"email": "priya.sharma@example.in"}'

import requests

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

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

{
  "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"],
    "signals": {
      "points": 7,
      "max_points": 8,
      "checks": 4,
      "latency_ms": 412
    },
    "result_id": 918273,
    "credits": 1
  },
  "message": "Cold emailing this address is allowed under India's rules."
}

{
  "success": true,
  "result": {
    "email": "anon@protonmail.com",
    "country": "",
    "country_code": "",
    "email_type": "consumer",
    "recommendation_code": "consent_required",
    "recommendation": "Treat consent as required before emailing.",
    "main_laws": [],
    "law_reference_urls": [],
    "main_restrictions": [
      "We could not establish which country's rules apply to this address.",
      "Obtain explicit consent before sending, and include a clear unsubscribe option."
    ],
    "applicability": "No jurisdiction could be identified from this address. The strictest common requirements are shown; confirm the recipient's country before sending.",
    "confidence": "unknown",
    "signals": {
      "points": 0,
      "max_points": 8,
      "checks": 3,
      "latency_ms": 286
    },
    "result_id": 918274,
    "credits": 1
  },
  "message": "We couldn't establish a jurisdiction for this address. Treat it as consent-required."
}

{
  "success": true,
  "result": {
    "email": "sam@example.de",
    "country": "Germany",
    "country_code": "DE",
    "email_type": "business",
    "recommendation_code": "consent_required",
    "recommendation": "Obtain consent before emailing.",
    "main_laws": ["GDPR", "UWG"],
    "law_reference_urls": ["https://gdpr-info.eu/"],
    "main_restrictions": ["Prior opt-in required"],
    "applicability": "National scope. Sector rules may add requirements.",
    "confidence": "medium",
    "jurisdictions_applicable": ["DE", "AT"],
    "signals": {
      "points": 3,
      "max_points": 8,
      "checks": 2,
      "latency_ms": 190
    },
    "checking": true,
    "result_id": 918275,
    "credits": 1
  },
  "message": "Compliance resolved from the available signals. An additional check is still running and you'll be notified if it adds anything."
}

{ "success": false, "result": { "code": "insufficient_credits" },
  "message": "You don't have enough credits for this lookup. Top up to continue." }

Known issue: A provisional response says, “Compliance resolved from the available signals. An additional check is still running and you’ll be notified if it adds anything.” No subscribable notification exists. Re-send the request to get the settled verdict.

Overview

Email

Breaches

Malware

API Keys

Webhooks

Account

Email Compliance

Overview

Authentication

Request

Example request

Response

`confidence` drives the presentation

Errors

Credits

​Overview

​Authentication

​Request

​Example request

​Response

​confidence drives the presentation

​Errors

​Credits

Overview

Authentication

Request

Example request

Response

`confidence` drives the presentation

Errors

Credits