Email Risk
==========

Validate email addresses and assess fraud risk with syntax checks, MX records,
disposable domain detection, domain age analysis, and abuse list matching.

.. contents:: Tools on this page
   :local:
   :depth: 1


apicrate-check-email-risk
-------------------------

Validate an email address and compute a risk score. Checks syntax, MX records,
disposable domain, domain age, free provider, and abuse list. Returns a score
from 0 to 100 and a risk tier.

**Credit cost:** 4 credits per call.

Parameters
^^^^^^^^^^

.. list-table::
   :header-rows: 1
   :widths: 20 10 10 60

   * - Parameter
     - Type
     - Required
     - Description
   * - ``email``
     - str
     - yes
     - Email address to analyse (max 254 characters).

Example
^^^^^^^

Request:

.. code-block:: json

   {
     "name": "apicrate-check-email-risk",
     "arguments": {
       "email": "user@example.com"
     }
   }

Response:

.. code-block:: json

   {
     "email": "user@example.com",
     "score": 25,
     "risk_tier": "low",
     "checks": {
       "syntax_valid": true,
       "mx_found": true,
       "is_disposable": false,
       "is_free_provider": false,
       "domain_age_days": 9432,
       "abuse_listed": false
     }
   }

Errors
^^^^^^

- **Email required** -- the ``email`` parameter was not provided.
- **Email too long** -- the address exceeds the 254-character limit.


apicrate-check-email-risk-bulk
------------------------------

Validate multiple email addresses and compute risk scores in a single call.
Each email is assessed independently -- if one email fails a check (e.g. WHOIS
timeout), the others are unaffected.

**Credit cost:** 4 credits per email.

Parameters
^^^^^^^^^^

.. list-table::
   :header-rows: 1
   :widths: 20 10 10 60

   * - Parameter
     - Type
     - Required
     - Description
   * - ``emails``
     - list[str]
     - yes
     - List of email addresses to analyse (1--10 items, each max 254 characters).

Example
^^^^^^^

Request:

.. code-block:: json

   {
     "name": "apicrate-check-email-risk-bulk",
     "arguments": {
       "emails": ["alice@example.com", "bob@tempmail.xyz"]
     }
   }

Response:

.. code-block:: json

   {
     "total": 2,
     "results": [
       {
         "email": "alice@example.com",
         "score": 15,
         "risk_tier": "low"
       },
       {
         "email": "bob@tempmail.xyz",
         "score": 85,
         "risk_tier": "critical"
       }
     ]
   }

Errors
^^^^^^

- **Empty list** -- the ``emails`` list contains no items.
- **Too many emails** -- more than 10 emails were provided.
- **Email too long** -- an individual address exceeds the 254-character limit.