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

# Email Scoring

> This method provides an additional layer of validation for your system. While validating email syntax is important, it is not sufficient.

This method goes beyond syntax validation by checking the domain's validity, the availability of the Mail Service, detecting Disposable Email (Temporary Emails), etc. By utilising this method, you can ensure a more thorough validation process for email addresses.

export const MCPCallout = () => {
  return <div class="callout my-4 px-5 py-4 overflow-hidden rounded-2xl flex gap-3 border border-[rgba(192, 132, 252, 0.2)] bg-[rgba(192, 132, 252, 0.1)] dark:border-[#c084fc4d] dark:bg-[#c084fc1a] text-[#6005BB] dark:text-[#FFFFFF]" data-callout-type="callout">
      <div class="mt-0.5 w-4" data-component-part="callout-icon">
        <svg class="h-4 w-4 !m-0 shrink-0 bg-[#c084fc] [mask-image:url('https://d3gk2c5xim1je2.cloudfront.net/v7.1.0/duotone/fire.svg')] [-webkit-mask-image:url('https://d3gk2c5xim1je2.cloudfront.net/v7.1.0/duotone/fire.svg')] [mask-repeat:no-repeat] [-webkit-mask-repeat:no-repeat] [mask-position:center] [-webkit-mask-position:center]"></svg>
      </div>
      <div class="text-sm prose dark:prose-invert min-w-0 w-full [&_kbd]:bg-background-light dark:[&_kbd]:bg-background-dark text-[#6005BB] dark:text-[#FFFFFF]" data-component-part="callout-content">
        <span data-as="p">
          Want to skip the docs? Use the{" "}
          <a class="link mint-text-xs border-[#C792FC]" href="/docs-mcp-server">
            <b>MCP Server</b>
          </a>
        </span>
      </div>
    </div>;
};

export const Availability = ({plan, color}) => {
  const colorMap = {
    green: "text-green-700 dark:text-green-400",
    blue: "text-blue-700 dark:text-blue-400",
    purple: "text-purple-700 dark:text-purple-400"
  };
  return <div dir="ltr" data-orientation="horizontal" class="p-4 px-5 mt-0 md:mt-4 flex flex-col sm:flex-row flex-wrap gap-2 relative overflow-hidden rounded-2xl border border-gray-950/10 dark:border-white/10 my-0 bg-gray-50 dark:bg-white/5 dark:codeblock-dark text-gray-950 dark:text-gray-50 codeblock-light text-sm prose prose-gray dark:prose-invert font-semibold no-wrap-words">
      Endpoint availability:{" "}
      <span class={` ${colorMap[color]} flex-1`}>{plan}</span>
      <a class="custom-link text-xs" href="https://greip.io/detailed-pricing">
        Learn more
      </a>
    </div>;
};

## Authentication

Include your API key in the `Authorization` header:

```http theme={null}
Authorization: Bearer <api_key>
```

API v2 accepts the key only in this header, not in query parameters or request bodies. See [Authentication](/authentication).

### Path parameters

<ParamField path="email" type="string" required placeholder="Email address">
  The email you want to validate.

  Expected values: an email address

  Sample value: `name@domain.com`
</ParamField>

### Query parameters

<ParamField query="format" type="string" default="JSON" placeholder="Response format">
  The format command is used to get a response in a specific format.

  Expected values: `JSON`, `XML`, `CSV`, or `Newline`

  For more information please refer to [Response format](/options/response-format).
</ParamField>

<ParamField query="mode" type="string" default="live" placeholder="Environment">
  The mode command is used in the development stage to simulate the integration process before releasing it to the production environment.

  Expected values: `live`, or `test`.

  For more information please refer to [Development environment](/options/development-environment).
</ParamField>

<ParamField query="source" type="string" placeholder="Integration label">
  Optional label for your own analytics or support correlation (for example a product or channel name).
</ParamField>

<ParamField query="user_id" type="string" placeholder="User identifier">
  The user\_id command can be used to identify requests sent by specific users to monitor in the [Events page](/knowledge-base/events-and-alerts/overview).

  Expected values: email address, phone number, user id, name, etc.

  For more information please refer to [User identifier](/options/user-identifier).
</ParamField>

<Panel>
  <MCPCallout />

  <Availability plan="Premium and above" color="purple" />

  <ResponseExample>
    ```json Success theme={null}

    {
      "success": true,
      "data": {
        "is_valid": false,
        "is_free": false,
        "is_role_based": true,
        "is_educational": false,
        "is_disposable": false,
        "is_blacklisted": false,
        "email": "test@dangerous-domain.com",
        "domain": {
          "name": "dangerous-domain.com",
          "is_dangerous": true,
          "is_spf": false,
          "is_dmarc": false,
          "is_dkim": false,
          "is_mx": false,
          "is_bimi": false,
          "created_at": "2025-02-05",
          "is_new": true,
          "domain_age_days": 45,
          "has_website": true,
          "mx_provider_class": "custom"
        },
        "custom_rules_applied": {
          "total": 0,
          "rules": []
        },
        "risk_level": "high",
        "recommendation": "reject",
        "reasons": [
          "Email domain is considered dangerous."
        ],
        "rules": [
          {
            "id": "EMAIL_DANGEROUS_DOMAIN",
            "description": "Email domain is considered dangerous."
          }
        ]
      },
      "execution_ms": 1
    }

    ```

    ```json Error theme={null}
    {
      "success": false,
      "code": 101,
      "type": "invalid_key",
      "description": "The API Key is missing or invalid."
    }
    ```
  </ResponseExample>
</Panel>

### Response properties

<ResponseField name="success" type="boolean" required>
  `true` when the request succeeded; `false` on error.
</ResponseField>

<ResponseField name="data" type="object" required>
  <Expandable title="properties" defaultOpen={true}>
    <ResponseField name="email" type="string" required>
      The email address that was scored.
    </ResponseField>

    <ResponseField name="risk_level" type="string" required>
      Overall risk band for the address (`low`, `medium`, or `high`). Use this with `recommendation` and `reasons` for fraud decisions, not `is_valid`.
    </ResponseField>

    <ResponseField name="recommendation" type="string" required>
      Suggested action (`accept`, `review`, or `reject`) derived from the risk assessment.
    </ResponseField>

    <ResponseField name="reasons" type="array" required>
      Human-readable strings explaining elevated risk. Empty when risk is low. Populated when `risk_level` is not `low`.
    </ResponseField>

    <ResponseField name="rules" type="array" required>
      Each object has `id` and `description`. The array lists only signals that fired for this request (empty when risk is low).

      <Expandable title="Rule ids">
        | Id | Description |
        | - | - |
        | `EMAIL_INVALID_STRUCTURE` | Email address failed syntax validation. |
        | `EMAIL_CUSTOM_BLACKLIST` | Email address or domain is on your blocklist. |
        | `EMAIL_DANGEROUS_DOMAIN` | Email domain is considered dangerous. |
        | `EMAIL_DISPOSABLE` | Email address or domain is flagged as disposable or spam. |
        | `DOMAIN_NO_MX` | Domain has no usable MX records for receiving mail. |
        | `DOMAIN_NEW` | Domain registration is newer than one year. |
        | `DOMAIN_NO_SPF` | Domain does not publish a valid SPF record. |
        | `DOMAIN_NO_DMARC` | Domain does not publish a DMARC policy. |
      </Expandable>
    </ResponseField>

    <ResponseField name="is_free" type="boolean" required>
      Indicates whether the email address is from a free email service provider.
    </ResponseField>

    <ResponseField name="is_role_based" type="boolean" required>
      Indicates whether the email address is a role-based email address. Role-based email addresses are those that are associated with a particular role or group, such as `admin`, `support`, `info`, etc.
    </ResponseField>

    <ResponseField name="is_educational" type="boolean" required>
      Indicates whether the email address is an educational email address.
    </ResponseField>

    <ResponseField name="is_valid" type="boolean" required>
      Whether the address passes syntax and structure checks only. It does not indicate overall safety or fraud risk. Use `risk_level`, `recommendation`, and `reasons` for risk outcomes.
    </ResponseField>

    <ResponseField name="is_disposable" type="boolean" required>
      Indicates whether the email address is a disposable email address (also known as Temporary Email Addresses).
    </ResponseField>

    <ResponseField name="is_blacklisted" type="boolean" required>
      Indicates if the email/domain is blacklisted due to applying [custom
      rules](/knowledge-base/custom-rules/overview) or were found in one of your
      blacklists.
    </ResponseField>

    <ResponseField name="domain" type="object">
      The information associated with the domain name of the email address.

      <Expandable title="properties" defaultOpen={true}>
        <ResponseField name="name" type="string" required>
          The full domain name associated with the email address (for example, `gmail.com`).
        </ResponseField>

        <ResponseField name="is_disposable" type="boolean|null">
          Indicates whether the domain is used for disposable or temporary email services.
        </ResponseField>

        <ResponseField name="is_forwarding" type="boolean|null">
          Indicates whether the domain appears to be an email forwarding service.
        </ResponseField>

        <ResponseField name="is_dangerous" type="boolean|null" required>
          Indicates whether the domain is flagged as dangerous or suspicious, which may suggest a higher risk of fraud or abuse.

          <Warning>
            If this property is set to `true`, the domain is considered high-risk or potentially malicious. As a result, the `isValid` property will also be `false`, indicating that the email address should not be trusted for critical communications or user registrations. It is strongly recommended to block or flag such email addresses in your application workflow.
          </Warning>
        </ResponseField>

        <ResponseField name="is_spf" type="boolean|null" required>
          Indicates whether the domain has a valid SPF (Sender Policy Framework) record, which helps prevent email spoofing.
        </ResponseField>

        <ResponseField name="is_dmarc" type="boolean|null" required>
          Indicates whether the domain has a valid DMARC (Domain-based Message Authentication, Reporting, and Conformance) record, which helps protect against email phishing and spoofing.
        </ResponseField>

        <ResponseField name="is_dkim" type="boolean|null" required>
          Indicates whether the domain has a valid DKIM (DomainKeys Identified Mail) record, which verifies the authenticity of the sender's domain.
        </ResponseField>

        <ResponseField name="is_mx" type="boolean|null" required>
          Indicates whether the domain has valid MX (Mail Exchange) records, confirming that it is capable of receiving emails.
        </ResponseField>

        <ResponseField name="is_bimi" type="boolean|null" required>
          Indicates whether the domain has a valid BIMI (Brand Indicators for Message Identification) record, which allows brand logos to be displayed in supported email clients.
        </ResponseField>

        <ResponseField name="created_at" type="string|null" required>
          The date when the domain was first registered or created, if available.
        </ResponseField>

        <ResponseField name="is_new" type="boolean|null" required>
          Indicates whether the domain is new or recently registered (registered within 1 year), which may affect its reputation and trustworthiness.
        </ResponseField>

        <ResponseField name="domain_age_days" type="integer|null">
          Days since domain registration when `created_at` is known; otherwise `null`.
        </ResponseField>

        <ResponseField name="has_website" type="boolean|null">
          Whether the domain resolves to a public host (DNS A/AAAA lookup). `null` when lookup did not complete in time.
        </ResponseField>

        <ResponseField name="mx_provider_class" type="string">
          Inferred mail host category when MX is present: `none`, `google_workspace`, `microsoft_365`, `yahoo`, `zoho`, `proton`, or `custom`.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="custom_rules_applied" type="object">
      The custom rules applied to this request, [learn
      more](/knowledge-base/custom-rules/overview).

      <Expandable title="properties" defaultOpen={true}>
        <ResponseField name="total" type="integer" required>
          The total number of custom rules applied to this request.
        </ResponseField>

        <ResponseField name="rules" type="object" required>
          The custom rules applied to this request, [learn
          more](/knowledge-base/custom-rules/overview).

          <Expandable title="properties" defaultOpen={true}>
            <ResponseField name="id" type="string" required>
              The rule ID as shown in the dashboard (e.g: `CR104`).
            </ResponseField>

            <ResponseField name="title" type="string" required>
              The rule title you set when creating the rule.
            </ResponseField>
          </Expandable>
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="execution_ms" type="integer" required>
  Time taken to process the request (milliseconds).
</ResponseField>


## OpenAPI

````yaml openapi/v2.json GET /score/email/{email}
openapi: 3.0.3
info:
  title: Greip API v2 (docs playground)
  version: 2.0.0
servers:
  - url: https://v2.greipapi.com
security: []
paths:
  /score/email/{email}:
    get:
      summary: Email scoring
      operationId: scoreEmail
      parameters:
        - name: email
          in: path
          required: true
          schema:
            type: string
        - name: format
          in: query
          schema:
            type: string
            default: JSON
        - name: mode
          in: query
          schema:
            type: string
            default: live
        - name: source
          in: query
          schema:
            type: string
        - name: user_id
          in: query
          schema:
            type: string
      responses:
        '200':
          description: OK
      security:
        - bearerAuth: []
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.