Email Country Identification

Throttle (Free Tier): 50/Hour
Throttle (Paid Tier): Pricing

Examples:

Objects and Endpoints:

Object: Email

This Object DOES NOT do a DNS lookup! The Email is validated and the CCTLD or IP Address is checked.
You should always get consent before sending any emails!
email
String
This is the normalized RFC representation of an email address. Hostnames are normalized to IDNA and IP addresses are normalized to literals.

Example

"email": "queen.elizabeth.ii@royal.uk"
hostname
Object: Hostname
Validated Email Hostname

ip
Object: IP
Validated Email IP Address
This is NOT the result of a DNS lookup! Nearly ALL email addresses use Hostnames and not IP Addresses!

gdpr
Boolean
Is this Email Subject to the GDPR?
This value is the result of checking either the Hostname CCTLD or taken from the submitted IP Address.
If an IP Address exists, it is NOT the result of a DNS lookup!
You should always get consent before sending any emails!

Example

"gdpr": true
extended
Object: Email
This is the optionally fully detailed Validated Email

extended=true must be past on Request for this Object to exist.


Object: Request

email
String
Email to Geographically lookup.

Example

"email": "royal.uk"
emails
[]String
Used for Bulk lookups only! This is for paid endpoints only!

Example

"emails": [
	"queen.elizabeth.ii@royal.uk",
	"sales@gdpr-identity.com",
	"admin@[193.0.6.139]"
]
date
String
YYYYMMDD - This is for History endpoints only!

Example

"date": "20180525"
validator
Number
Optional
Method of Validation to use.
STRICT Validation will not allow Incorrect Spec Validation to occur! It's recommended to use LOOSE!
The Default/Invalid Validator is LOOSE

Constants

Key Value
STRICT 1
LOOSE 2


Example

"validator": 0
extended
Object: Email
Optional
This is the optionally fully detailed Validated Email

extended=true must be past on Request for this Object to exist.

options
Object: Extended Email Options
Optional
Extended Options, extended=true must be set to use!
Default Options will be used when nil

pd
Boolean
Optional
Percent Decode before validating? Only avaliable for GET endpoints!

Example

"pd": false
jsonp
String
Optional
Return a JSONP Object? Only avaliable for GET endpoints!

Example

"json": "myfunc"

Object: Result

Bulk Results are only avaliable for paid plans. To upgrade contact sales@gdpr-identity.com
email
Object: Email
Geolocation Result

emails
key[string]Email
Key contains the original validated Email, Value points to the Result.

Used for Bulk lookups only! This is for paid endpoints only!

throttled-until
String
Throttle Expiration Timestamp RFC 3339

Only exists when throttled!

Example

"throttled-until": "2006-01-02T15:04:05Z07:00"
throttle-acquired
Number
The number of actions you acquired from the throttle.
This is always 1 unless bulk endpoints are used.
Bulk will either acquire the amount of bulk actions you requested or the remaining amount of actions available in the throttle.

Example

"throttle-acquired": 1
throttle-available
Number
The number of actions remaining in the throttle.

Example

"throttle-available": 99
suspended
Boolean
This only exists for paid plans. The most likely reason for this is a billing issue. Please contact sales@gdpr-identity.com to resolve this.

Example

"suspended": false
error
Number
Returns non 0 on Error.

API_ERROR_INVALID will be returned when using Bulk if 1 or more IPs, Emails, Hostnames or Geolocations are Invalid. Valid Results will still be returned AS WELL!

Constants

Key Value
UNKNOWN 1
THROTTLED 2
INVALID 3
INVALID_TIMESTAMP 4
INVALID_BODY 5
INVALID_BULK_MAX 6


Example

"error": 1
errors
[]String
Debug Errors - Do not rely on these values, use Error to determine the reason.

Example

"errors": [
	"internal server error"
]

GET /api;v=1/email/current

To authenticate use /api;v=1;key=APIKEY/email/current?email=

Request

Request Example

curl 'https://gdpr-identity.com/api/email/current?email=queen.elizabeth.ii@royal.uk'

Response

Response Example

{
  "email": {
    "email": "queen.elizabeth.ii@royal.uk",
    "hostname": {
      "hostname": "royal.uk",
      "gdpr": true,
      "location": "UK",
      "location-full": "United Kingdom"
    },
    "gdpr": true
  },
  "throttle-acquired": 1,
  "throttle-available": 987
}

GET /api;v=1/email/current/after?

To authenticate use /api;v=1;key=APIKEY/email/current/after?

Request

Request Example

curl 'https://gdpr-identity.com/api/email/current/after?hello@gdpr-identity.com'

Response

Response Example

{
  "email": {
    "email": "hello@gdpr-identity.com",
    "hostname": {
      "hostname": "gdpr-identity.com",
      "location": "ZZ",
      "location-full": "Unknown or Invalid Territory"
    }
  },
  "throttle-acquired": 1,
  "throttle-available": 985
}

POST /api;v=1/email/current

To authenticate use /api;v=1;key=APIKEY/email/current/

Request

Request Example

curl -H "Content-Type: application/json" --request POST --data '{"email":"admin@[193.0.6.139]"}' 'https://gdpr-identity.com/api/email/current'

Response

Response Example

{
  "email": {
    "email": "admin@[193.0.6.139]",
    "ip": {
      "ip": "193.0.6.139",
      "gdpr": true,
      "date": "20180525",
      "location": "NL",
      "location-full": "Netherlands"
    },
    "gdpr": true
  },
  "throttle-acquired": 1,
  "throttle-available": 984
}

POST /api;v=1;key=APIKEY/bulk/email/current

This is a paid only endpoint!

To authenticate use /api;v=1;key=APIKEY/bulk/email/current/

Request

Request Example

curl -H "Content-Type: application/json" --request POST --data '{"emails":["queen.elizabeth.ii@royal.uk","hello@gdpr-identity.com","admin@193.0.6.139"]}' 'https://gdpr-identity.com/api;key=APIKEY/bulk/email/current'

Response

Response Example

{
  "emails": {
    "queen.elizabeth.ii@royal.uk": {
      "email": "queen.elizabeth.ii@royal.uk",
      "hostname": {
        "hostname": "royal.uk",
        "gdpr": true,
        "location": "UK",
        "location-full": "United Kingdom"
      },
      "gdpr": true
    },
    "hello@gdpr-identity.com": {
      "email": "hello@gdpr-identity.com",
      "hostname": {
        "hostname": "gdpr-identity.com",
        "location": "ZZ",
        "location-full": "Unknown or Invalid Territory"
      }
    },
    "admin@193.0.6.139": {
      "email": "admin@[193.0.6.139]",
      "ip": {
        "ip": "193.0.6.139",
        "gdpr": true,
        "date": "20180525",
        "location": "NL",
        "location-full": "Netherlands"
      },
      "gdpr": true
    }
  },
  "throttle-acquired": 3,
  "throttle-available": 994
}

GET /api;v=1/email/history?date=YYYYMMDD&email=

To authenticate use /api;v=1;key=APIKEY/history?date=YYYYMMDD

Request

Request Example

curl 'https://gdpr-identity.com/api/email/history?date=19960823&email=queen.elizabeth.ii@royal.uk'

Response

Response Example

{
  "email": {
    "email": "queen.elizabeth.ii@royal.uk",
    "hostname": {
      "hostname": "royal.uk",
      "gdpr": true,
      "location": "UK",
      "location-full": "United Kingdom"
    },
    "gdpr": true
  },
  "throttle-acquired": 1,
  "throttle-available": 981
}

GET /api;v=1/email/history/after;date=YYYYMMDD?

To authenticate use /api;v=1;key=APIKEY/history/after;date=YYYYMMDD?

Request

Request Example

curl 'https://gdpr-identity.com/api/email/history/after;date=19960823?admin@192.5.11.0'

Response

Response Example

{
  "email": {
    "email": "admin@[192.5.11.0]",
    "ip": {
      "ip": "192.5.11.0",
      "date": "19960823",
      "location": "US",
      "location-full": "United States of America"
    }
  },
  "throttle-acquired": 1,
  "throttle-available": 983
}

POST /api;v=1/email/history

To authenticate use /api;v=1;key=APIKEY/history/

Request

Request Example

curl -H "Content-Type: application/json" --request POST --data '{"date":"19960823","email":"hello@juandefu.ca"}' 'https://gdpr-identity.com/api/email/history'

Response

Response Example

{
  "email": {
    "email": "hello@juandefu.ca",
    "hostname": {
      "hostname": "juandefu.ca",
      "location": "CA",
      "location-full": "Canada"
    }
  },
  "throttle-acquired": 1,
  "throttle-available": 982
}

POST /api;v=1;key=APIKEY/bulk/email/history

This is a paid only endpoint!

To authenticate use /api;v=1;key=APIKEY/bulk/email/history/

Request

Request Example

curl -H "Content-Type: application/json" --request POST --data '{"date":"19960823","emails":["queen.elizabeth.ii@royal.uk","admin@192.5.11.0","hello@juandefu.ca"]}' 'https://gdpr-identity.com/api;key=APIKEY/bulk/email/history'

Response

Response Example

{
  "emails": {
    "queen.elizabeth.ii@royal.uk": {
      "email": "queen.elizabeth.ii@royal.uk",
      "hostname": {
        "hostname": "royal.uk",
        "gdpr": true,
        "location": "UK",
        "location-full": "United Kingdom"
      },
      "gdpr": true
    },
    "admin@192.5.11.0": {
      "email": "admin@[192.5.11.0]",
      "ip": {
        "ip": "192.5.11.0",
        "date": "19960823",
        "location": "US",
        "location-full": "United States of America"
      }
    },
    "hello@juandefu.ca": {
      "email": "hello@juandefu.ca",
      "hostname": {
        "hostname": "juandefu.ca",
        "location": "CA",
        "location-full": "Canada"
      }
    }
  },
  "throttle-acquired": 3,
  "throttle-available": 988
}