Email Validation - Standard API
The lookupemail endpoint validates a complete email address and reports its syntax, domain, and mailbox status, with an optional corrected suggestion.
When to use this endpoint - Call
lookupemail once the user has entered (or left)
a complete email address, to confirm it is valid and deliverable
before storing it. To suggest completions while the user
is still typing, see
Email API — Suggest an email address (REST) →
lookupemail
Request
Both GET and POST are supported.
{SERVER_ADDRESS} and
{LICENCE_CODE} are provided by DQE upon
account creation. Contact your DQE account manager to obtain
these credentials.
GEThttps://{SERVER_ADDRESS}/v1/lookupemail/?Email={EMAIL}&Licence={LICENCE_CODE}&Rectify={RECTIFY}&CheckUser={CHECK_USER}&TimeOut={TIME_OUT}
Code examples
Valid address, syntax and domain OK
curl "https://{SERVER_ADDRESS}/v1/lookupemail/?Email=toto%40gmail.com&Licence={LICENCE_CODE}"
fetch("https://{SERVER_ADDRESS}/v1/lookupemail/?"
+ new URLSearchParams({
Email: "toto@gmail.com",
Licence: "{LICENCE_CODE}"
}))
.then(r => r.json())
.then(data => console.log(data));
import requests
response = requests.get(
"https://{SERVER_ADDRESS}/v1/lookupemail/",
params={
"Email": "toto@gmail.com",
"Licence": "{LICENCE_CODE}",
},
)
print(response.json())
<?php
$params = http_build_query([
'Email' => 'toto@gmail.com',
'Licence' => '{LICENCE_CODE}',
]);
$ch = curl_init("https://{SERVER_ADDRESS}/v1/lookupemail/?{$params}");
curl_setopt($ch, CURLOPT_RETURNTRANSFER,
true);
$response = curl_exec($ch);
curl_close($ch);
$data = json_decode($response, true);
const axios = require('axios');
axios.get('https://{SERVER_ADDRESS}/v1/lookupemail/',
{
params: {
Email: 'toto@gmail.com',
Licence: '{LICENCE_CODE}'
}
})
.then(response => console.log(response.data));
HttpClient client = HttpClient.newHttpClient();
String url = "https://{SERVER_ADDRESS}/v1/lookupemail/"
+ "?Email=toto%40gmail.com&Licence={LICENCE_CODE}";
HttpRequest request = HttpRequest.newBuilder()
.uri(URI.create(url))
.GET()
.build();
HttpResponse<String> response = client.send(request,
HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());
using var client = new HttpClient();
var url = "https://{SERVER_ADDRESS}/v1/lookupemail/"
+
"?Email=toto%40gmail.com&Licence={LICENCE_CODE}";
var response = await client.GetAsync(url);
var body = await response.Content.ReadAsStringAsync();
Console.WriteLine(body);
package main
import (
"fmt"
"io"
"net/http"
)
func main() {
url := "https://{SERVER_ADDRESS}/v1/lookupemail/"
+
"?Email=toto%40gmail.com&Licence={LICENCE_CODE}"
resp, err := http.Get(url)
if err != nil {
panic(err)
}
defer resp.Body.Close()
body, _ := io.ReadAll(resp.Body)
fmt.Println(string(body))
}
POSThttps://{SERVER_ADDRESS}/v1/lookupemail/
Send all parameters in the request body using
Content-Type: application/x-www-form-urlencoded.
The server address remains in the URL.
Code examples
Valid address, syntax and domain OK
curl -X POST "https://{SERVER_ADDRESS}/v1/lookupemail/"
\
-H "Content-Type: application/x-www-form-urlencoded"
\
-d "Email=toto@gmail.com" \
-d "Licence={LICENCE_CODE}"
fetch("https://{SERVER_ADDRESS}/v1/lookupemail/",
{
method: "POST",
headers: { "Content-Type": "application/x-www-form-urlencoded"
},
body: new URLSearchParams({
Email: "toto@gmail.com",
Licence: "{LICENCE_CODE}"
})
})
.then(r => r.json())
.then(data => console.log(data));
import requests
response = requests.post(
"https://{SERVER_ADDRESS}/v1/lookupemail/",
data={
"Email": "toto@gmail.com",
"Licence": "{LICENCE_CODE}",
},
)
print(response.json())
<?php
$ch = curl_init("https://{SERVER_ADDRESS}/v1/lookupemail/");
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query([
'Email' => 'toto@gmail.com',
'Licence' => '{LICENCE_CODE}',
]));
curl_setopt($ch, CURLOPT_RETURNTRANSFER,
true);
$response = curl_exec($ch);
curl_close($ch);
$data = json_decode($response, true);
const axios = require('axios');
const qs = require('querystring');
axios.post('https://{SERVER_ADDRESS}/v1/lookupemail/',
qs.stringify({
Email: 'toto@gmail.com',
Licence: '{LICENCE_CODE}'
}))
.then(response => console.log(response.data));
HttpClient client = HttpClient.newHttpClient();
String form = "Email=toto%40gmail.com&Licence={LICENCE_CODE}";
HttpRequest request = HttpRequest.newBuilder()
.uri(URI.create("https://{SERVER_ADDRESS}/v1/lookupemail/"))
.header("Content-Type", "application/x-www-form-urlencoded")
.POST(HttpRequest.BodyPublishers.ofString(form))
.build();
HttpResponse<String> response = client.send(request,
HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());
using var client = new HttpClient();
var form = new Dictionary<string, string>
{
["Email"] = "toto@gmail.com",
["Licence"] = "{LICENCE_CODE}"
};
var response = await client.PostAsync(
"https://{SERVER_ADDRESS}/v1/lookupemail/",
new FormUrlEncodedContent(form));
var body = await response.Content.ReadAsStringAsync();
Console.WriteLine(body);
package main
import (
"fmt"
"io"
"net/http"
"net/url"
)
func main() {
form := url.Values{}
form.Set("Email", "toto@gmail.com")
form.Set("Licence", "{LICENCE_CODE}")
resp, err := http.PostForm("https://{SERVER_ADDRESS}/v1/lookupemail/",
form)
if err != nil {
panic(err)
}
defer resp.Body.Close()
body, _ := io.ReadAll(resp.Body)
fmt.Println(string(body))
}
Parameters
| Parameter | Description | Mand / Opt |
|---|---|---|
| The email address to validate. | Mandatory | |
| Licence | Your DQE licence key or OAuth2 token. Contact support if you do not yet have one. | Mandatory |
| Rectify |
Y to receive a suggested correction
when the syntax is invalid or the domain is unknown.
Default:
N (no correction suggested)
|
Optional |
| CheckUser |
N if you do not want to check the
part before the @ sign (username).
Default:
Y (username is checked)
|
Optional |
| TimeOut |
Maximum query time for verification, in seconds.
Example: 0.5 for 500 ms.
Default:
6
|
Optional |
Response
On success, the API returns a JSON object containing the number of results and an array of validated email addresses.
Business reading:
IdError and
ActivityCode carry the detailed validation outcome
- see the full list in the
API Response Codes reference.
SuggestedEmail is only populated when
Rectify=Y and a correction was found.
| Key | Description | Type |
|---|---|---|
| Found | Number of email addresses returned. | Integer |
| Emails | Array of validation results, one entry per email address submitted. | Array |
| ActivityCode | Activity status of the email address. See the API Response Codes reference. | String |
| IdError | Validation return code. See the API Response Codes reference. | String |
| Corrected |
1 if a correction was applied; 0
otherwise.
|
Integer |
| SuggestedEmail |
Corrected email address, returned when Rectify=Y
and a correction was found.
|
String |
| InputEmail | Email address as submitted in the request. | String |
Response example
Valid address, no correction applied
{
"Found": 1,
"Emails": [
{
"ActivityCode":
"",
"IdError":
"02",
"Corrected":
0,
"SuggestedEmail":
"toto@gmail.com",
"InputEmail":
"toto@gmail.com"
}
]
}
Response codes
IdError codes
| Code | Description | Suggested UI message |
|---|---|---|
00
|
Valid email. | Valid email |
01
|
Correct email but name could not be checked. | Valid email |
02
|
Email address not found for this domain. | Please check your email address |
03
|
Inbox is full (soft bounce). | Please check your email address |
04
|
Empty email. | Please check your email address |
91
|
Syntax error. | Please check your email address |
92
|
Unknown domain. | Please check your email address |
93
|
Blacklisted email or domain. | Please check your email address |
94
|
Unauthorized username. | Please check your email address |
95
|
Disposable temporary email address. | Please check your email address |
99
|
Service unavailable. | Valid email |
ActivityCode codes
Consider M as the current month.
| Code | Description |
|---|---|
100
|
The email was delivered once. |
200
|
The email is valid. |
201
|
Email was active last month. |
202
|
Email was active between M-1 and M-2. |
203
|
Email was active between M-2 and M-3. |
204
|
Email was active between M-3 and M-4. |
206
|
Email was active between M-4 and M-6. |
209
|
Email was active between M-6 and M-9. |
212
|
Email was active between M-9 and M-12. |
300
|
Inactive email. |
Errors
| HTTP | Error type | Response body |
|---|---|---|
| 400 |
Missing or empty mandatory parameter (e.g. Email)
|
{"status": 400, "message": "Missing parameters",
"details": "Email", "error": "bad request"}
|
| 401 | Invalid or unauthorized licence key |
{"status": 401, "message": "Your licence
is not allowed to cover this functionnality",
"details": "{WRONG LICENSE}", "error": "unauthorized_client"}
|
Test the API
Click the button below to test this endpoint live in your browser.
Open console
See also
Related to