POST /v1/check/ — Check an email address

Score an email address for signup risk. AuthFlame parses the address, normalizes it to a canonical form, evaluates syntax, entropy, and domain signals, and returns a recommended action.

Endpoint

POST https://api.authflame.com/v1/check/

Headers

string

required

Bearer token containing your AuthFlame API key. Example: Bearer af_live_....

string

required

Must be application/json.

Body

string

required

The email address to check. Submit the raw value the user entered; AuthFlame handles trimming, casing, and normalization.

Example request

curl -X POST https://api.authflame.com/v1/check/ \
  -H "Authorization: Bearer af_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"email": "test@example.com"}'

$headers = @{
  "Authorization" = "Bearer af_live_your_api_key"
  "Content-Type"  = "application/json"
}
$body = @{ email = "test@example.com" } | ConvertTo-Json

Invoke-RestMethod `
  -Uri "https://api.authflame.com/v1/check/" `
  -Method Post `
  -Headers $headers `
  -Body $body

const response = await fetch("https://api.authflame.com/v1/check/", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.AUTHFLAME_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ email: "test@example.com" }),
});

const result = await response.json();

import os
import requests

response = requests.post(
    "https://api.authflame.com/v1/check/",
    headers={
        "Authorization": f"Bearer {os.environ['AUTHFLAME_API_KEY']}",
        "Content-Type": "application/json",
    },
    json={"email": "test@example.com"},
)

result = response.json()

Response

string

Unique check identifier, prefixed with chk_. Log this for auditing and support.

string

ISO 8601 UTC timestamp for when the check was created.

object

Decision summary derived from the underlying signals.

Show summary

string

Recommended enforcement action. One of ALLOW or BLOCK.

integer

Integer risk score from 0 (safe) to 100 (highest risk).

object

Canonical parsed form of the input address.

Show normalized

string

The address as submitted, with any surrounding whitespace removed.

string

Deduplicated form after lowercasing, stripping sub-address tags, and applying provider-specific dot rules. Store this to detect duplicate signups.

string

Local part of the address with the +tag removed (the portion before the @). Original casing and dots are kept. Use canonical for deduplication.

string

Domain portion of the address, lowercased.

string | null

The +tag portion of the local part, or null if none.

boolean

true if provider-specific dot normalization (for example, Gmail) changed the local part.

object

Raw signals that produced the summary.

Show signals

object

Show syntax

boolean

true if the address parses cleanly.

object

Show entropy

number

Shannon entropy of the local part. Higher values indicate more random-looking characters.

object

Show domain

boolean

true if the domain matches AuthFlame’s disposable-domain list.

boolean

true if the domain is a public free provider (Gmail, Outlook, etc.).

boolean

true if a live DNS lookup returned MX records for the domain.

boolean

true if the local part looks like a shared inbox (info, support, etc.).

string

low or high, based on abuse patterns for the top-level domain.

Example response

200 OK

{
  "id": "chk_abf82b9e837b",
  "created_at": "2026-09-06T19:09:35Z",
  "summary": {
    "action": "ALLOW",
    "risk_score": 9
  },
  "normalized": {
    "raw": "test@example.com",
    "canonical": "test@example.com",
    "local_part": "test",
    "domain": "example.com",
    "subaddress": null,
    "has_dots_removed": false
  },
  "signals": {
    "syntax": { "valid_format": true },
    "entropy": { "score": 1.5 },
    "domain": {
      "is_known_disposable": false,
      "is_known_free_provider": false,
      "has_mx": true,
      "is_role_account": false,
      "tld_risk_level": "low"
    }
  }
}

Errors

See Errors for the shared error envelope and HTTP status codes. Errors for this endpoint:

Status	Code	Meaning
`400`	`invalid_json`	The request body is not valid JSON.
`400`	`missing_field`	The `email` field is missing or empty.
`401`	`missing_or_malformed_api_key`	The `Authorization` header is missing or not a valid Bearer API key.
`401`	`invalid_api_key`	The API key is invalid or has been revoked.
`402`	`subscription_inactive`	The team’s subscription is not active. Update your billing details.
`405`	`method_not_allowed`	This endpoint only accepts `POST`.
`422`	`invalid_email_format`	The submitted string cannot be parsed as an email address.
`429`	`rate_limited`	You exceeded your plan’s requests-per-second limit.
`429`	`quota_exceeded`	You used your monthly quota of checks.
`500`	`internal_error`	A temporary server error occurred. Retry shortly.

Handling `429` responses

A 429 can mean two different things, so check error.code before retrying.

rate_limited: wait for the number of seconds in the Retry-After header, then retry. Using exponential backoff is also fine.
quota_exceeded: do not retry. The quota will not recover until it resets on the first of the month, or until you upgrade your plan. The error message includes the reset date.

429 Too Many Requests

{
  "error": {
    "code": "quota_exceeded",
    "message": "Monthly quota of 10,000 checks reached. Quota resets on 2026-11-01 or upgrade your plan."
  }
}

Overview

Endpoints

POST /v1/check/ — Check an email address

Endpoint

Headers

Body

Example request

Response

Example response

Errors

Handling `429` responses

​Endpoint

​Headers

​Body

​Example request

​Response

​Example response

​Errors

​Handling 429 responses

Endpoint

Headers

Body

Example request

Response

Example response

Errors

Handling `429` responses