Email Verification API

Implementation Guide

Introduction

Please see the Overview Page to review account setup, authentication instructions, and other common API features.

Searchbug® Verify Email Address API allows you validate email address by contacting MX (mail) server for the email domain in the real time. The MX response typically indicates if messages sent to the provided address can be accepted or not. INVALID status is a reliable indicator that email will not be delivered.

However, you may get some false-positives from the “Catch-All” domains. Some corporate email servers will always return a VALID response, whether the email address is actually valid or invalid. They do this to prevent people from harvesting real email addresses from their mail server. In other cases, mail operators collect all emails sent to invalid accounts (e.g., misspelledname@domain.com). These are then sent to the mail administrator, who forwards that email to a "catch-all" address, such as review@domain.com, to review all the emails sent to their mail server to see if anything important was sent to an invalid recipient.

The response time for our API is between one second and 60 seconds. If we encounter a slow mail server, you will get an UNKNOWN result. You can try to resubmit your request again later.

Are your emails not making it to your prospects' inboxes? Do you want to reduce your bounce rate, increase your sender reputation, and improve deliverability? Searchbug offers a robust Email Verification API that helps you identify and remove invalid, spam-trap, and toxic email addresses from your list that affect your email campaign performance.

Are you curious how to easily integrate this API into your existing systems? This API Documentation is here to guide you!

This guide includes:

  1. Sending Request
  2. Receiving Results
  3. Field Definitions in API Response

Sending Request

The request should be sent to Searchbug using the following URL using the POST method:

https://data.searchbug.com/api/search.aspx

Search Parameters

You can submit your request via:

  • POST Header: Parameters sent as custom headers
  • POST Body: Parameters sent as form-data
Parameter Value Example Description
CO_CODE 3453167 Required. Your account number
PASS H4z865i3$1 API Key or account password (not needed if using Bearer Token)
TYPE api_emver Required. Use api_emver for this API
EMAIL sam@aol.com Email Address in a valid format
FORMAT JSON Optional. The default is XML. To get results in JSON format, pass FORMAT=JSON
REF CUST001 Optional. Used for API usage tracking per application or customer (100 char max).

Receiving Results

XML results examples:


<?xml version="1.0" encoding="ISO-8859-1" standalone="true"?>
<RESULTS>
    <ADDRESS>rsmith@gmail.com</ADDRESS>
    <STATUS>Valid</STATUS>
    <SUB_STATUS/>
    <ACCOUNT>rsmith</ACCOUNT>
    <DOMAIN>gmail.com</DOMAIN>
    <DISPOSABLE>false</DISPOSABLE>
    <TOXIC>false</TOXIC>
    <FIRSTNAME>Randall</FIRSTNAME>
    <LASTNAME>Smith</LASTNAME> 
    <GENDER>male</GENDER>
    <LOCATION/>
</RESULTS>

<?xml version="1.0" encoding="ISO-8859-1" standalone="true"?> <RESULTS>
    <ADDRESS>rsmith@gmail.com</ADDRESS>
    <STATUS>VALID</STATUS>
    <SUB_STATUS/>
    <ACCOUNT>rsmith</ACCOUNT>
    <DOMAIN>gmail.com</DOMAIN>
    <DISPOSABLE>false</DISPOSABLE>
    <TOXIC>false</TOXIC>
    <FIRSTNAME>Randall</FIRSTNAME>
    <LASTNAME>Smith</LASTNAME>
    <GENDER>male</GENDER>
    <LOCATION/>
</RESULTS>

<?xml version="1.0" encoding="ISO-8859-1" standalone="true"?>
<RESULTS>
    <ADDRESS>test@searchbug.com</ADDRESS>
    <STATUS>INVALID</STATUS>
    <SUB_STATUS>mailbox_not_found</SUB_STATUS>
    <ACCOUNT>test</ACCOUNT>
    <DOMAIN>searchbug.com</DOMAIN>
    <DISPOSABLE>false</DISPOSABLE>
    <TOXIC>false</TOXIC>
    <FIRSTNAME/>
    <LASTNAME/>
    <GENDER/>
    <LOCATION/>
</RESULTS>


{
    Status: "Success",
    - Data: {
        ADDRESS: "rsmith@gmail.com",
        STATUS: "VALID",
        SUB_STATUS: null,
        ACCOUNT: "rsmith", 
        DOMAIN: "gmail.com", 
        DISPOSABLE: "false", 
        TOXIC: "false",
        FIRSTNAME: "Randall",
        LASTNAME: "Smith",
        GENDER: "male",
        LOCATION: null
    },
    Error: null
}

{
    Status: "Success",
    - Data: {
        ADDRESS: "test@searchbug.com", 
        STATUS: "INVALID",
        SUB_STATUS: "mailbox_not_found",
        ACCOUNT: "test",
        DOMAIN: "searchbug.com",
        DISPOSABLE: "false",
        TOXIC: "false",
        FIRSTNAME: null,
        LASTNAME: null,
        GENDER: null,
        LOCATION: null
    },
    Error: null
}

Field Definitions in API Response

<ADDRESS>

The email address you are validating.

<STATUS>
  • VALID
  • INVALID
  • CATCH-ALL (see a Overview above)
  • SPAMTRAP (An email address not used by a person, but actively monitored. If a spam trap receives an email, it will consider it as spam because that email address never opted in to receive emails)
  • ABUSE (high risk emails, where recipient clicks the "Spam" link often)
  • DONOTMAIL
  • UNKNOWN (mail server response timed out)
<SUB-STATUS>
  • alias_address - forwards to a valid real address (e.g. webmaster@mysite.com to joe@mysite.com)
  • antispam_system - unknown email status due to anti-spam systems deployed at the server.
  • does_not_accept_mail - domain can send, but not receive email
  • exception_occurred - mail server error
  • failed_smtp_connection - connection to mail server failed (likely invalid)
  • failed_syntax_check - email format is invalid (e.g. name$mysite.com)
  • forcible_disconnect - connection to mail server dropped (likely invalid)
  • global_suppression - email is found in a global suppression list (GSL). Do not email.
  • greylisted - temporarily unable to validate. You can try again later.
  • leading_period_removed - valid gmail.com email address can start with a period '.' We will remove it, to make it compatible with all mailing systems
  • mail_server_did_not_respond - server not responding to mail requests (likely invalid)
  • mail_server_temporary_error - mail server reports a temporary error (likely invalid)
  • mailbox_not_found - email account does not exist on the mail server
  • mailbox_quota_exceeded - account exceeded their space quota and are not accepting emails
  • no_dns_entries - domain is not valid or mail server does not exist
  • possible_traps - do not send emails to this address
  • role_based - a group email like support@mysite.com
  • timeout_exceeded - no response from the server in 60 seconds. You can try again.
  • unroutable_ip_address - emails domains point to an un-routable IP address
<ACCOUNT> The portion of the email address before the "@" symbol.
<DOMAIN> The portion of the email address after the "@" symbol.
<DISPOSABLE> (a temporary email addresses):
  • true
  • false
<TOXIC> (known for abuse, spam, and bot created)
  • true
  • false
<LOCATION> The location of the owner of the email when available

Do not expect Name, Gender and Location results in many results. Getting account owner details is not primary purpose of this API. Use API – Find Name and Address (api_na) to obtain name from email.

For further technical details and customer support, please chat with us, email us, or call us (800) 990-2939.

For sales and pricing information please contact sales@searchbug.com.