# Check email deliverability

`GET /email_ping`

- Live: `GET https://gdapi.globaldata.net.au/api/v2/email_ping`
- Sandbox: `GET https://sandbox-gdapi.globaldata.net.au/api/v2/email_ping`

Tests the deliverability of one or more supplied email addresses. This deliverability check will return a
code indicating if the email address is deliverable or not.

> **Note:**
> 1. The order of the returned email addresses may not be the same as the supplied order.
> 2. Email addresses will be converted to lower case before being returned by the API.

## Interpreting the results

The returned field ping_result gives the actual deliverability result. This indicates if the email address is
valid and the mail server has indicated that it will accept delivery for that email account. The ping_result
can be undetermined as is the case for greylisting, catch-all or other anti-spam measures.

The returned field info contains a plain test description of the check result. Examples include:

- Deliverable
- Undeliverable: Mailbox not found
- Undeliverable: No DNS entry
- Unknown: Greylisted
- Catch all
- Abuse
- Spam trap

The info field is designed to provide a human readable explanation of the result. The contents of the field can
vary for different error scenarios and as such the field should not be matched programmatically.

A further ok_to_send field indicates if the emails should be sent. This differs from the ping_result field which
shows if the email can be sent. An example which shows this difference is where the email address is a known spam
trap or serial abuse reporter. In this case ping_result will be 'Y' (indicating that the email address is capable
of receiving messages) but ok_to_send will be 'N' showing that an email should not be sent to the address.

Whether ping_result or ok_to_send is used to determine deliverability will be dependent on the intent of the API consumer.

## Sandbox environment

When simulating queries in the sandbox environment, each email address will return a specific
result depending on the email address tld:

| Email Type                   | Response | Description                                                             |
|:-----------------------------|:--------:|:------------------------------------------------------------------------|
| Any email ending in .asn.au  |          | Simulate a timeout, will never return a result                          |
| Any email ending in .com.au: | Y        | Simulate a slow result, takes 20 seconds but returns as deliverable     |
| Any email ending in .org.au: | N        | Simulate a slow result, takes 20 seconds but returns as not deliverable |
| Any email ending in .net.au: | U        | Simulate a slow result, takes 20 seconds but returns as undetermined    |
| Any email ending in .edu     | I        | Email is invalid                                                        |
| Any email ending in .org     | N        | Email is not deliverable                                                |
| Any email ending in .net     | U        | Email is undetermined                                                   |
| Any other email (eg .com)    | Y        | Email is deliverable                                                    |

## Request body

The details of the record to enhance

| Field | Type | Description |
|-------|------|-------------|
| `emails` | string | One or more (comma separated) email addresses to be checked Example: `test@example.com` |

**Sample request**

```json
{
    "emails": "test@example.com"
}
```

## Responses

### 200 Result of email ping check

Content type: `application/json`

| Field | Type | Description |
|-------|------|-------------|
| `message` | string | A message indicating the result of the request. This will be `Ok` if the request was successful. Example: `Ok` |
| `api_reference` | string (uuid) | Example: `738d9a89-b6fe-4fc1-96be-1389b2a506a2` |
| `records` | array of objects | The checked email addresses and their deliverability status |
| `records[].email` | string | The checked email address Example: `test@example.com` |
| `records[].ping_result` | string | The result of the deliverability check for the email address * `Y` - The email is deliverable * `N` - The email is not deliverable * `U` - The state of the email address cannot be detected * `I` - The email address is invalid Enum: `Y`, `N`, `U`, `I` Example: `Y` |
| `records[].ok_to_send` | string | Whether the email address is ok to send to * `Y` - Ok to send * `N` - Not ok to send * `U` - Unable to determine Enum: `Y`, `N`, `U` Example: `Y` |
| `records[].info` | string | Plain text description giving additional detail about the result Example: `Deliverable` |

**Sample response**

```json
{
    "message": "Ok",
    "api_reference": "738d9a89-b6fe-4fc1-96be-1389b2a506a2",
    "records": [
        {
            "email": "test@example.com",
            "ping_result": "Y",
            "ok_to_send": "Y",
            "info": "Deliverable"
        }
    ]
}
```

Standard error responses: 400, 401, 402, 403, 429, 5XX (see [Common error responses](/docs/reference/general/common-error-responses.md))