Check email deliverability
/api/v2/email_ping
operationId: email_ping
Live: https://gdapi.globaldata.net.au/api/v2/email_ping · Sandbox: 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:
- The order of the returned email addresses may not be the same as the supplied order.
- 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
Content type application/json.
The details of the record to enhance
| Field | Description |
|---|---|
emails |
string One or more (comma separated) email addresses to be checked |
Responses
Result of email ping check
application/json
| Field | Description |
|---|---|
message |
string A message indicating the result of the request. This will be |
api_reference |
string (uuid) |
records |
array of objects The checked email addresses and their deliverability status |
records[]. |
string The checked email address |
records[]. |
string The result of the deliverability check for the email address
|
records[]. |
string Whether the email address is ok to send to
|
records[]. |
string Plain text description giving additional detail about the result |