Email verification

Check that an email address exists before you send to it. Costs 0.1 credit per verification.

How to use it:

1. Send the email. You get back a search _id.
2. A few seconds later, read the verdict with /bulk-single-searchs/read, or receive it on a webhook.
3. Look at items[0].results.emails[0].certainty: ultra_sure / very_sure / probable mean the address exists, undeliverable means it doesn't. See Email certainty.

Verifying a list?

Use the bulk search with the email-verification task: up to 5,000 addresses per call.

POSThttps://app.icypeas.com/api/email-verification

Headers

• Authorizationstringrequired

  Your API key, as is (no Bearer prefix).

• Content-Typestringrequired

  Always application/json.

Body parameters

• emailstringrequired

  The email address you want to verify.

• customobjectoptional

  Optional settings for this search: a webhook URL and/or your own id.

  Show properties (2)

  • webhookUrlurloptional

    A URL Icypeas calls with the result as soon as this search is done. See the 'Search item processed' webhook.

  • externalIdstringoptional

    Your own id for this search (for example a CRM id). It comes back with the result and in webhooks. Icypeas doesn't check that it's unique.

Request example

cURL

curl -X POST "https://app.icypeas.com/api/email-verification" \
  -H "Content-Type: application/json" \
  -H "Authorization: YOUR_API_KEY" \
  -d '{
  "email": "example-email@icypeas.com"
}'

JavaScript

const response = await fetch("https://app.icypeas.com/api/email-verification", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    Authorization: "YOUR_API_KEY",
  },
  body: JSON.stringify({
    "email": "example-email@icypeas.com"
  }),
});

const data = await response.json();
console.log(data);

Python

import requests

response = requests.post(
    "https://app.icypeas.com/api/email-verification",
    headers={"Authorization": "YOUR_API_KEY"},
    json={
        "email": "example-email@icypeas.com",
    },
)
print(response.json())

PHP

<?php
$body = <<<'JSON'
{
    "email": "example-email@icypeas.com"
}
JSON;

$ch = curl_init("https://app.icypeas.com/api/email-verification");
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST => "POST",
    CURLOPT_POSTFIELDS => $body,
    CURLOPT_HTTPHEADER => [
        "Content-Type: application/json",
        "Authorization: YOUR_API_KEY",
    ],
]);

$response = json_decode(curl_exec($ch), true);
curl_close($ch);
print_r($response);

PowerShell

$headers = @{
  "Authorization" = "YOUR_API_KEY"
  "Content-Type"  = "application/json"
}

$body = @'
{
  "email": "example-email@icypeas.com"
}
'@

$response = Invoke-RestMethod -Method POST -Uri "https://app.icypeas.com/api/email-verification" -Headers $headers -Body $body
$response | ConvertTo-Json -Depth 10

JSON body

Paste this in the Body field of Make, Zapier, n8n or Postman.

{
  "email": "example-email@icypeas.com"
}

Responses

200SuccessResponse when your input is good.

Example response · 200

{
  "success": true,
  "item": {
    "_id": "#YOUR_SEARCH_ID#",
    "status": "NONE"
  }
}

Response fields

• successboolean

  true means that your search has been taken into account

• itemobject

  Information about your search

  Show properties (2)

  • _idstring

    Search id to follow its progression

  • statusstring

    Status of this search (NONE right after creation). See the Result statuses page.

200Validation errorResponse when there are validation errors

The request reached Icypeas but some fields are wrong. The response lists every problem in validationErrors. See how to read and fix errors.

Example response · 200

{
  "validationErrors": [
    {
      "expected": "email",
      "type": "required",
      "field": "email",
      "message": "validation_required"
    }
  ],
  "success": false
}

Type	Fields	When it happens
required validation_required	email	Error sent when the field is missing
stringEmpty validation_string_empty	email	Error sent when the field is empty
email validation_email	email	Error sent when the field is not an email address
string validation_string	custom.externalId	Error sent when the field is not a string
url validation_url	custom.webhookUrl	Error sent when the field is not a valid URL
UnpaidSubscriptionError unpaid_subscription_error	user	Error sent when you have a pending payment and your subscription is therefore not paid

401UnauthorizedResponse when we could not authenticate you.

Example response · 401

{
  "message": "Unauthorized access.",
  "error": "UnauthorizedAccessError",
  "status": 401,
  "code": "unauthorized_access_error"
}

Response fields

• messagestring

  Human-readable message.

• errorstring

  Error name

• statusnumber

  HTTP error code

• codestring

  Error code

429Too many requestsError received when rate limit is exceeded

Example response · 429

{
  "message": "You have exceeded the max number of requests per minute.",
  "error": "RateLimitExceededError",
  "status": 429,
  "code": "rate_limit_exceeded_error"
}

Response fields

• messagestring

  Human-readable message.

• errorstring

  Error name

• statusnumber

  HTTP error code

• codestring

  Error code

New to the API? Follow the verification quickstart.