Skip to main content
POST
Check cold-email compliance

Good to know

  • Branch on recommendation_code. The recommendation and message text can change. Treat a code you don’t recognize like case_by_case.
  • unknown is a valid answer. It means no jurisdiction could be established, so the restrictive consent_required default applies. Don’t show a country. Free mailboxes like Gmail and Proton usually come back unknown, because their domain says nothing about where the person is.
  • medium can mean several candidates. When jurisdictions_applicable has more than one entry, the strictest rule was applied and country_code is that strictest country.
  • checking: true is provisional. The website check is still running. Send the same request again a few seconds later. Re-checks are free.
  • Repeats are free for 6 months. The same account looking up the same address again costs 0 credits, and result_id stays the same.
  • This is guidance, not legal advice. The rules are compiled from public sources. Check with counsel before relying on them for a campaign.

Guide: cold-email compliance checks

Filter an outreach list by jurisdiction before you send.

Authorizations

Authorization
string
header
required

Your Finowl API key, for example finowl_3f9a.... Create keys in the dashboard under API Keys.

Body

application/json
email
string<email>
required

The address to place in a jurisdiction. Leading and trailing spaces are removed. It must be a plain address with a dotted domain.

Maximum string length: 254
Example:

"priya.sharma@example.in"

Response

The check completed. An unknown verdict is still a successful response.

email
string
required

The address that was checked.

country
string
required

The jurisdiction's country name. Empty when confidence is unknown.

country_code
string
required

ISO 3166-1 alpha-2 code. Empty when confidence is unknown. When several countries are possible, the code of the strictest one.

email_type
enum<string>
required

consumer for personal mailbox providers such as Gmail, otherwise business.

Available options:
consumer,
business
recommendation_code
enum<string>
required

Machine-readable verdict, strictest first in the list. Branch on this, not on recommendation. Treat codes you don't recognize like case_by_case.

Available options:
prohibited,
consent_required,
exception_required,
case_by_case,
allowed_with_conditions,
allowed,
allowed_by_policy,
safe_to_send
recommendation
string
required

Plain-language advice. Wording varies by jurisdiction.

message
string
required

A sentence ready to show to end users.

main_laws
string[]
required

The laws that govern cold email there.

law_reference_urls
string<uri>[]
required

Official sources for those laws or their regulators.

main_restrictions
string[]
required

Key obligations when emailing.

applicability
string
required

Scope of the rule.

confidence
enum<string>
required

confident: one country backed by two independent checks or a single-country mailbox provider. medium: a likely country with thinner evidence, or several candidates. unknown: no jurisdiction established.

Available options:
confident,
medium,
unknown
signals
object
required

Anonymized summary of the checks behind the verdict. points / max_points is a rough evidence-strength ratio.

credits
enum<integer>
required

1 for a charged lookup, 0 for a free repeat within 6 months.

Available options:
0,
1
jurisdictions_applicable
string[]

Every country still in contention, strictest first. Omitted when unknown. More than one entry means the strictest rule was applied.

checking
boolean

true while the website check is still running and the verdict is provisional. Omitted when false.

result_id
integer

Stable ID of this verdict. It stays the same across repeat calls.