Validate email deliverability
curl --request POST \
--url https://brew.new/api/v1/contacts/validate \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"emails": [
"ada@gmail.com",
"temp@mailinator.com",
"admin@stripe.com"
]
}
'import requests
url = "https://brew.new/api/v1/contacts/validate"
payload = { "emails": ["ada@gmail.com", "temp@mailinator.com", "admin@stripe.com"] }
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({emails: ['ada@gmail.com', 'temp@mailinator.com', 'admin@stripe.com']})
};
fetch('https://brew.new/api/v1/contacts/validate', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://brew.new/api/v1/contacts/validate",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'emails' => [
'ada@gmail.com',
'temp@mailinator.com',
'admin@stripe.com'
]
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://brew.new/api/v1/contacts/validate"
payload := strings.NewReader("{\n \"emails\": [\n \"ada@gmail.com\",\n \"temp@mailinator.com\",\n \"admin@stripe.com\"\n ]\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://brew.new/api/v1/contacts/validate")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"emails\": [\n \"ada@gmail.com\",\n \"temp@mailinator.com\",\n \"admin@stripe.com\"\n ]\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://brew.new/api/v1/contacts/validate")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"emails\": [\n \"ada@gmail.com\",\n \"temp@mailinator.com\",\n \"admin@stripe.com\"\n ]\n}"
response = http.request(request)
puts response.read_body{
"data": [
{
"email": "ada@gmail.com",
"valid": true,
"status": "valid"
},
{
"email": "temp@mailinator.com",
"valid": false,
"status": "invalid",
"reason": "undeliverable"
},
{
"email": "ada@gmial.com",
"valid": false,
"status": "risky",
"reason": "unknown",
"didYouMean": "ada@gmail.com"
},
{
"email": "admin@stripe.com",
"valid": false,
"status": "risky",
"reason": "role_address"
}
]
}{
"error": {
"code": "INVALID_REQUEST",
"type": "invalid_request",
"message": "Request validation failed.",
"suggestion": "Fix the field reported in `param` and retry.",
"docs": "https://docs.brew.new/api-reference/api/errors",
"param": "emails"
}
}{
"error": {
"code": "INVALID_API_KEY",
"type": "authentication_error",
"message": "The provided API key is invalid.",
"suggestion": "Check the API key format and retry with a valid active key.",
"docs": "https://docs.brew.new/api-reference/api/authentication"
}
}{
"error": {
"code": "INSUFFICIENT_CREDITS",
"type": "payment_required",
"message": "This operation required more credits than the 0 remaining on the 'free' plan. See the per-operation cost in GET /v1/help.",
"suggestion": "Upgrade your plan or wait for the next billing period to reset. Check your balance up front with GET /v1/usage.",
"docs": "https://docs.brew.new/api-reference/api/credits",
"details": {
"cost": 2,
"remaining": 0,
"planKey": "free"
}
}
}{
"error": {
"code": "INSUFFICIENT_PERMISSIONS",
"type": "authorization_error",
"message": "The caller does not have the required permission.",
"suggestion": "Use an API key or session with the required permission.",
"docs": "https://docs.brew.new/api-reference/api/authentication",
"param": "contacts"
}
}{
"error": {
"code": "RATE_LIMITED",
"type": "rate_limit",
"message": "Too many requests.",
"suggestion": "Wait for the retry window before sending another request.",
"docs": "https://docs.brew.new/api-reference/api/rate-limits",
"retryAfter": 42
}
}{
"error": {
"code": "INTERNAL_ERROR",
"type": "internal_error",
"message": "An unexpected error occurred.",
"suggestion": "Retry the request. If it keeps failing, contact support.",
"docs": "https://docs.brew.new/api-reference/api/errors"
}
}{
"error": {
"code": "SERVICE_UNAVAILABLE",
"type": "service_unavailable",
"message": "Your credit balance could not be verified because a billing dependency is temporarily unavailable.",
"suggestion": "Retry the request after a short delay.",
"docs": "https://docs.brew.new/api-reference/api/credits",
"retryAfter": 2
}
}Contacts
Validate email deliverability
Batch deliverability check (up to 100 addresses). Run BEFORE importing or sending. Each address is classified valid (safe), risky (deliverable but flagged, e.g. role account, disposable, catch-all), or invalid (undeliverable / do-not-send), with a machine-readable reason and a didYouMean typo correction when applicable. Cost: 2 credits PER ADDRESS (X-Credit-Cost = 2 × the number of addresses), charged ONLY on success, if the check cannot complete for the whole batch, the call returns a retryable 503 and is NOT billed.
POST
/
v1
/
contacts
/
validate
Validate email deliverability
curl --request POST \
--url https://brew.new/api/v1/contacts/validate \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"emails": [
"ada@gmail.com",
"temp@mailinator.com",
"admin@stripe.com"
]
}
'import requests
url = "https://brew.new/api/v1/contacts/validate"
payload = { "emails": ["ada@gmail.com", "temp@mailinator.com", "admin@stripe.com"] }
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({emails: ['ada@gmail.com', 'temp@mailinator.com', 'admin@stripe.com']})
};
fetch('https://brew.new/api/v1/contacts/validate', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://brew.new/api/v1/contacts/validate",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'emails' => [
'ada@gmail.com',
'temp@mailinator.com',
'admin@stripe.com'
]
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://brew.new/api/v1/contacts/validate"
payload := strings.NewReader("{\n \"emails\": [\n \"ada@gmail.com\",\n \"temp@mailinator.com\",\n \"admin@stripe.com\"\n ]\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://brew.new/api/v1/contacts/validate")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"emails\": [\n \"ada@gmail.com\",\n \"temp@mailinator.com\",\n \"admin@stripe.com\"\n ]\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://brew.new/api/v1/contacts/validate")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"emails\": [\n \"ada@gmail.com\",\n \"temp@mailinator.com\",\n \"admin@stripe.com\"\n ]\n}"
response = http.request(request)
puts response.read_body{
"data": [
{
"email": "ada@gmail.com",
"valid": true,
"status": "valid"
},
{
"email": "temp@mailinator.com",
"valid": false,
"status": "invalid",
"reason": "undeliverable"
},
{
"email": "ada@gmial.com",
"valid": false,
"status": "risky",
"reason": "unknown",
"didYouMean": "ada@gmail.com"
},
{
"email": "admin@stripe.com",
"valid": false,
"status": "risky",
"reason": "role_address"
}
]
}{
"error": {
"code": "INVALID_REQUEST",
"type": "invalid_request",
"message": "Request validation failed.",
"suggestion": "Fix the field reported in `param` and retry.",
"docs": "https://docs.brew.new/api-reference/api/errors",
"param": "emails"
}
}{
"error": {
"code": "INVALID_API_KEY",
"type": "authentication_error",
"message": "The provided API key is invalid.",
"suggestion": "Check the API key format and retry with a valid active key.",
"docs": "https://docs.brew.new/api-reference/api/authentication"
}
}{
"error": {
"code": "INSUFFICIENT_CREDITS",
"type": "payment_required",
"message": "This operation required more credits than the 0 remaining on the 'free' plan. See the per-operation cost in GET /v1/help.",
"suggestion": "Upgrade your plan or wait for the next billing period to reset. Check your balance up front with GET /v1/usage.",
"docs": "https://docs.brew.new/api-reference/api/credits",
"details": {
"cost": 2,
"remaining": 0,
"planKey": "free"
}
}
}{
"error": {
"code": "INSUFFICIENT_PERMISSIONS",
"type": "authorization_error",
"message": "The caller does not have the required permission.",
"suggestion": "Use an API key or session with the required permission.",
"docs": "https://docs.brew.new/api-reference/api/authentication",
"param": "contacts"
}
}{
"error": {
"code": "RATE_LIMITED",
"type": "rate_limit",
"message": "Too many requests.",
"suggestion": "Wait for the retry window before sending another request.",
"docs": "https://docs.brew.new/api-reference/api/rate-limits",
"retryAfter": 42
}
}{
"error": {
"code": "INTERNAL_ERROR",
"type": "internal_error",
"message": "An unexpected error occurred.",
"suggestion": "Retry the request. If it keeps failing, contact support.",
"docs": "https://docs.brew.new/api-reference/api/errors"
}
}{
"error": {
"code": "SERVICE_UNAVAILABLE",
"type": "service_unavailable",
"message": "Your credit balance could not be verified because a billing dependency is temporarily unavailable.",
"suggestion": "Retry the request after a short delay.",
"docs": "https://docs.brew.new/api-reference/api/credits",
"retryAfter": 2
}
}Authorizations
bearerAuthapiKeyAuth
Send your Brew API key as Authorization: Bearer brew_xxx.
Body
application/json
Required array length:
1 - 100 elementsMinimum string length:
1Response
One classification row per input address.
Show child attributes
Show child attributes
Was this page helpful?
⌘I