Email Suggestion - Standard API
The emailsuggest endpoint suggests likely email addresses as a user types, combining their first name, last name, and the characters already entered to return ranked completions.
When to use this endpoint - Call
emailsuggest while the user is still typing their email address, to offer autocomplete suggestions based on their name. To validate a complete email address instead, see Email API — Validate an email address (REST) →
emailsuggest
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/emailsuggest/?FirstName={FIRST_NAME}&LastName={LAST_NAME}&Email={EMAIL}&Country={COUNTRY_CODE}&Licence={LICENCE_CODE}
Code examples
France - John Lim, partial "jlim@gma"
curl "https://{SERVER_ADDRESS}/v1/emailsuggest/?FirstName=John&LastName=Lim&Email=jlim%40gma&Country=FRA&Licence={LICENCE_CODE}"
fetch("https://{SERVER_ADDRESS}/v1/emailsuggest/?" + new URLSearchParams({
FirstName: "John",
LastName: "Lim",
Email: "jlim@gma",
Country: "FRA",
Licence: "{LICENCE_CODE}"
}))
.then(r => r.json())
.then(data => console.log(data));
import requests
response = requests.get(
"https://{SERVER_ADDRESS}/v1/emailsuggest/",
params={
"FirstName": "John",
"LastName": "Lim",
"Email": "jlim@gma",
"Country": "FRA",
"Licence": "{LICENCE_CODE}",
},
)
print(response.json())
<?php
$params = http_build_query([
'FirstName' => 'John',
'LastName' => 'Lim',
'Email' => 'jlim@gma',
'Country' => 'FRA',
'Licence' => '{LICENCE_CODE}',
]);
$ch = curl_init("https://{SERVER_ADDRESS}/v1/emailsuggest/?{$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/emailsuggest/', {
params: {
FirstName: 'John',
LastName: 'Lim',
Email: 'jlim@gma',
Country: 'FRA',
Licence: '{LICENCE_CODE}'
}
})
.then(response => console.log(response.data));
HttpClient client = HttpClient.newHttpClient();
String url = "https://{SERVER_ADDRESS}/v1/emailsuggest/"
+ "?FirstName=John&LastName=Lim&Email=jlim%40gma&Country=FRA&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/emailsuggest/" +
"?FirstName=John&LastName=Lim&Email=jlim%40gma&Country=FRA&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/emailsuggest/" +
"?FirstName=John&LastName=Lim&Email=jlim%40gma&Country=FRA&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/emailsuggest/
Send all parameters in the request body using Content-Type: application/x-www-form-urlencoded. The server address remains in the URL.
Code examples
France - John Lim, partial "jlim@gma"
curl -X POST "https://{SERVER_ADDRESS}/v1/emailsuggest/" \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "FirstName=John" \
-d "LastName=Lim" \
-d "Email=jlim@gma" \
-d "Country=FRA" \
-d "Licence={LICENCE_CODE}"
fetch("https://{SERVER_ADDRESS}/v1/emailsuggest/", {
method: "POST",
headers: { "Content-Type": "application/x-www-form-urlencoded" },
body: new URLSearchParams({
FirstName: "John",
LastName: "Lim",
Email: "jlim@gma",
Country: "FRA",
Licence: "{LICENCE_CODE}"
})
})
.then(r => r.json())
.then(data => console.log(data));
import requests
response = requests.post(
"https://{SERVER_ADDRESS}/v1/emailsuggest/",
data={
"FirstName": "John",
"LastName": "Lim",
"Email": "jlim@gma",
"Country": "FRA",
"Licence": "{LICENCE_CODE}",
},
)
print(response.json())
<?php
$ch = curl_init("https://{SERVER_ADDRESS}/v1/emailsuggest/");
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query([
'FirstName' => 'John',
'LastName' => 'Lim',
'Email' => 'jlim@gma',
'Country' => 'FRA',
'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/emailsuggest/', qs.stringify({
FirstName: 'John',
LastName: 'Lim',
Email: 'jlim@gma',
Country: 'FRA',
Licence: '{LICENCE_CODE}'
}))
.then(response => console.log(response.data));
HttpClient client = HttpClient.newHttpClient();
String form = "FirstName=John&LastName=Lim&Email=jlim%40gma&Country=FRA&Licence={LICENCE_CODE}";
HttpRequest request = HttpRequest.newBuilder()
.uri(URI.create("https://{SERVER_ADDRESS}/v1/emailsuggest/"))
.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> {
["FirstName"] = "John",
["LastName"] = "Lim",
["Email"] = "jlim@gma",
["Country"] = "FRA",
["Licence"] = "{LICENCE_CODE}"
};
var response = await client.PostAsync(
"https://{SERVER_ADDRESS}/v1/emailsuggest/",
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("FirstName", "John")
form.Set("LastName", "Lim")
form.Set("Email", "jlim@gma")
form.Set("Country", "FRA")
form.Set("Licence", "{LICENCE_CODE}")
resp, err := http.PostForm("https://{SERVER_ADDRESS}/v1/emailsuggest/", form)
if err != nil {
panic(err)
}
defer resp.Body.Close()
body, _ := io.ReadAll(resp.Body)
fmt.Println(string(body))
}
Parameters
| Parameter | Description | Mand / Opt |
|---|---|---|
| FirstName | First name entered by the user. | Mandatory |
| LastName | Last name entered by the user. | Mandatory |
| Part of the email address already entered by the user. | Mandatory | |
| Country | ISO 3166-1 alpha-3 country code. Default:
FRA
|
Optional |
| Licence | Your DQE licence key or OAuth2 token. Contact support if you do not yet have one. | Mandatory |
Response
On success, the API returns a JSON object containing the number of results and an array of email suggestions.
Business reading:
List holds the ready-to-display suggestions for your autocomplete dropdown, ranked most-likely first. Syntaxe tells you whether the part of the address already typed is itself well-formed.| Key | Description | Type |
|---|---|---|
| Found | Number of suggestion results returned. | Integer |
| Suggestion | Array of suggestion results, one entry per input combination submitted. | Array |
| Instance | Custom value returned as-is in the response. | String |
| InputEmail | Email value as submitted in the request. | String |
| Syntaxe |
ok or ko, depending on the syntax of the email already entered. |
String |
| List | List of suggested email addresses. | Array |
| ListCount | Number of suggested email addresses in List. |
Integer |
Response example
France - John Lim, partial "jlim@gma"
{
"Found": 1,
"Suggestion": [
{
"Instance": "0",
"InputEmail": "jlim@gma",
"Syntaxe": "ok",
"List": [
"jlim@gmail.com",
"jlim@gmx.fr"
],
"ListCount": 2
}
]
}
Errors
| HTTP | Error type | Response body |
|---|---|---|
| 400 | Missing or empty mandatory parameter (e.g. FirstName) |
{"status": 400, "message": "Missing parameters", "details": "FirstName", "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.