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

# POST /v1/ - Check an email address

> Score an email address with AuthFlame. Returns a recommended action, a risk score, canonical normalization, and the underlying signals.

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

```http theme={null}
POST https://api.authflame.com/v1/
```

## Headers

<ParamField header="Authorization" type="string" required>
  Bearer token containing your AuthFlame API key. Example: `Bearer af_live_...`.
</ParamField>

<ParamField header="Content-Type" type="string" required>
  Must be `application/json`.
</ParamField>

## Body

<ParamField body="email" type="string" required>
  The email address to check. Submit the raw value the user entered; AuthFlame handles trimming, casing, and normalization.
</ParamField>

## Example request

<CodeGroup>
  ```bash curl theme={null}
  curl -X POST https://api.authflame.com/v1/ \
    -H "Authorization: Bearer af_live_your_api_key" \
    -H "Content-Type: application/json" \
    -d '{"email": "test@example.com"}'
  ```

  ```powershell PowerShell theme={null}
  $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/" `
    -Method Post `
    -Headers $headers `
    -Body $body
  ```

  ```javascript Node.js theme={null}
  const response = await fetch("https://api.authflame.com/v1/", {
    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();
  ```

  ```python Python theme={null}
  import os
  import requests

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

  result = response.json()
  ```
</CodeGroup>

## Response

<ResponseField name="id" type="string">
  Unique check identifier, prefixed with `chk_`. Log this for auditing and support.
</ResponseField>

<ResponseField name="created_at" type="string">
  ISO 8601 UTC timestamp for when the check was created.
</ResponseField>

<ResponseField name="summary" type="object">
  Decision summary derived from the underlying signals.

  <Expandable title="summary">
    <ResponseField name="action" type="string">
      Recommended enforcement action.`ALLOW` or `BLOCK`.
    </ResponseField>

    <ResponseField name="risk_score" type="integer">
      Integer risk score from `0` (safe) to `100` (highest risk).
    </ResponseField>

    <ResponseField name="risk_level" type="string">
      Coarse bucket derived from the score. One of `low`, `medium`, or `high`.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="normalized" type="object">
  Canonical parsed form of the input address.

  <Expandable title="normalized">
    <ResponseField name="raw" type="string">
      The address as submitted.
    </ResponseField>

    <ResponseField name="canonical" type="string">
      Deduplicated form after stripping sub-address tags and provider-specific dot rules. Store this to detect duplicate signups.
    </ResponseField>

    <ResponseField name="local_part" type="string">
      Local part of the canonical address (the portion before `@`).
    </ResponseField>

    <ResponseField name="domain" type="string">
      Domain portion of the canonical address.
    </ResponseField>

    <ResponseField name="subaddress" type="string | null">
      The `+tag` portion of the local part, or `null` if none.
    </ResponseField>

    <ResponseField name="has_dots_removed" type="boolean">
      `true` if provider-specific dot normalization (for example, Gmail) changed the local part.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="signals" type="object">
  Raw signals that produced the summary.

  <Expandable title="signals">
    <ResponseField name="syntax" type="object">
      <Expandable title="syntax">
        <ResponseField name="valid_format" type="boolean">
          `true` if the address parses cleanly.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="entropy" type="object">
      <Expandable title="entropy">
        <ResponseField name="score" type="number">
          Shannon entropy of the local part.
        </ResponseField>

        <ResponseField name="suspicious" type="boolean">
          `true` when the score crosses AuthFlame's threshold for auto-generated addresses.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="domain" type="object">
      <Expandable title="domain">
        <ResponseField name="is_known_disposable" type="boolean">
          `true` if the domain matches AuthFlame's disposable-domain list.
        </ResponseField>

        <ResponseField name="is_known_free_provider" type="boolean">
          `true` if the domain is a public free provider (Gmail, Outlook, etc.).
        </ResponseField>

        <ResponseField name="has_mx" type="boolean">
          `true` if a live DNS lookup returned MX records for the domain.
        </ResponseField>

        <ResponseField name="is_catch_all" type="boolean">
          `true` if the domain accepts mail for any local part.
        </ResponseField>

        <ResponseField name="is_role_account" type="boolean">
          `true` if the local part looks like a shared inbox (`info`, `support`, etc.).
        </ResponseField>

        <ResponseField name="tld_risk_level" type="string">
          `low`, `medium`, or `high`, based on abuse patterns for the top-level domain.
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

## Example response

```json 200 OK theme={null}
{
  "summary": {
    "action": "ALLOW",
    "risk_score": 3,
    "risk_level": "low"
  },
  "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, "suspicious": false },
    "domain": {
      "is_known_disposable": false,
      "is_known_free_provider": false,
      "has_mx": true,
      "is_catch_all": false,
      "is_role_account": false,
      "tld_risk_level": "low"
    }
  }
}
```

## Errors

See [Errors](/api-reference/errors) for the shared error envelope and HTTP status codes. Common errors for this endpoint:

* `400` — request body is missing `email` or is not valid JSON.
* `401` — API key is missing, malformed, or revoked.
* `422` — the submitted string cannot be parsed as an email address.
* `429` — rate limit exceeded. Retry with exponential backoff.