rate.email
Get an API key

API reference

Every endpoint rate.email exposes, generated straight from the OpenAPI spec that also backs the SDKs and the Magento extension.

Authentication

Send your API key as a bearer token, Authorization: Bearer <api_key>, or as X-Api-Key: <api_key>. Both forms work on every endpoint except GET /v1/reasons and GET /v1/health, which are public. A missing or invalid key returns 401 with a recovery hint in the response body, not a bare status code.

Verdict rule

verdict comes only from the severities present in reasons, never from the numeric score:

  1. Any high severity reason present: reject.
  2. Else any medium severity reason present: review.
  3. Otherwise: accept.

low and info reasons never change the verdict. They only move the score and add context.

Reason codes

Every reason includes a code, a severity, a source and a plain-language message. Codes are stable identifiers, always printed in upper case, never translated. See the fullreason code catalogue for every code, its penalty and an example trigger.

Try it

Real calls against https://api.rate.email. sk_live_REPLACE_WITH_YOUR_KEY is a placeholder and will never authenticate; use your own secret key from thedashboard.

Rating call

curl -s -X POST https://api.rate.email/v1/rate \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk_live_REPLACE_WITH_YOUR_KEY" \
  -d '{"email":"throwaway@mailinator.com"}'
{
  "email": "throwaway@mailinator.com",
  "verdict": "reject",
  "score": 40,
  "reasons": [
    {
      "code": "DISPOSABLE_DOMAIN",
      "severity": "high",
      "message": "mailinator.com is a known disposable email domain."
    }
  ]
}

Run here with a placeholder key, so the API returns 401 instead of this result. Put in your own secret key from the dashboard and this is what you get back.

No key

curl -s -X POST https://api.rate.email/v1/rate \
  -H "Content-Type: application/json" \
  -d '{"email":"throwaway@mailinator.com"}'
{
  "type": "https://rate.email/problems/unauthorized",
  "title": "Unauthorized",
  "status": 401,
  "detail": "No valid API key found in 'Authorization' or 'X-Api-Key' headers."
}

Rating and domain lookups require a key on every call; only the reason catalogue and the health check are open.

Domain rating

curl -s https://api.rate.email/v1/domain/mailinator.com \
  -H "Authorization: Bearer sk_live_REPLACE_WITH_YOUR_KEY"
{
  "domain": "mailinator.com",
  "verdict": "reject",
  "score": 40,
  "reasons": [
    {
      "code": "DISPOSABLE_DOMAIN",
      "severity": "high",
      "message": "mailinator.com is a known disposable email domain."
    }
  ]
}

Reason code catalogue

curl -s https://api.rate.email/v1/reasons
{
  "reasons": [
    {
      "code": "SYNTAX_INVALID",
      "severity": "high",
      "source": "syntax",
      "trigger": "Address fails RFC 5322 parsing."
    },
    {
      "code": "DISPOSABLE_DOMAIN",
      "severity": "high",
      "source": "allowlist:disposable",
      "trigger": "Domain itself is on the maintained disposable-domain list."
    }
  ]
}

Trimmed to two entries here. See the full reason code catalogue for every code.

Missing key

curl -s https://api.rate.email/v1/usage
{
  "type": "https://rate.email/problems/unauthorized",
  "title": "Unauthorized",
  "status": 401,
  "detail": "No valid API key found in 'Authorization' or 'X-Api-Key' headers."
}

GET /v1/usage reports your own account, so it needs a key regardless of tier.

Full reference