Email Verification Overview

The email verification API provides several endpoints focused around providing data about the state and validity of an email.

There are 3 major endpoints on this API for a variety of delivery methods for email verification (single, batch polling, and batch webhooks). At its core, however, the API delivers verification data in a format like the example below:

{
   "status": 200,
   "requestId": "928fed42-2b58-4c6d-9b47-d5cbca6ba6bb",
   "unknownEmails": [],
   "failedEmails": [],
   "emails": {
       "matt@fullcontact.ocm": {
           "message": "Valid email address",
           "address": "matt@fullcontact.com",
           "username": "matt",
           "domain": "fullcontact.com",
           "corrected": true,
           "sendSafely": true,
           "attributes": {
               "validSyntax": true,
               "deliverable": true,
               "catchall": false,
               "risky": false,
               "disposable": false
           },
           "person": "https://api.fullcontact.com/v2/person.json?email=matt@fullcontact.com&apiKey=",
           "company": "https://api.fullcontact.com/v2/company/lookup.json?domain=fullcontact.com&apiKey="
       }
   }
}
Field Description
Status the request status. 200 if successful (see error responses below).
requestId an arbitrary request ID string for debugging
unknownEmails an array of emails that cannot be verified due to configuration on the email server, or because the email server took too long to respond. Retryable but not guaranteed to be successful if requested again.
failedEmails an array of emails that cannot be verified due to an unknown error. Retryable but not guaranteed to be successful if requested again.
Emails a JSON object with all successful results of this email verification call. Each key is the email queried, and the associated object is the associated data. Only one field will be present in the single-email endpoint. The batch endpoint will have multiple fields (one for each email successfully processed).
Message A displayable string describing the state of the email.
Address The email address that was processed. This is usually the queried email. However, if email auto-correct was able to detect an error, it will correct the email to this new format (e.g. “fullcontact.ocm” to “fullcontact.com” in the example response). If this occurs, the corrected field will be true.
Username the inbox/username of the email.
Domain the domain hosting the email address.
Corrected true if the email auto-correct feature has made a change to the email. See address.
sendSafely An aggregate of the attributes object. If true, to the best of our knowledge, an email sent to this email address will deliver to a real person and will not be used for malicious purposes.
Attributes a set of lower-level attributes for fine-grained understanding of the state of this email.
validSyntax the email address conforms to the most common interpretations of valid email address syntax (e.g. there is only one unescaped “@” symbol).
Deliverable emails sent to this email address will not be bounced by the mail server. They will get delivered to some inbox.
Catchall the email server is configured to accept all emails at this domain even if the email address it is addressed to does not exist. This can make it hard to determine if an email address is actually valid, since a fake email hosted at this domain looks the same as a real email hosted at this domain.
Risky this email address is registered as a spamtrap or is associated with behavior where we do not recommend emailing it. (https://en.wikipedia.org/wiki/Spamtrap)
Disposable this email address is disposable. It may be a real email, but the recipient does not own it for long. (e.g. 10minutemail.com)
Person a link to the person API profile for this email.
Company a link to the company API profile for this email domain. Not present for email addresses provided by free email services (e.g. yahoo, google...)

Endpoints

Response Codes:

200 if the request ran without issue.

404 if the requested batch ID or resource does not exist (relevant to the GET batch state endpoint only)

403 if no api key was supplied, or the api key has exceeded its rate limits.

400 if some part of the request was malformed or missing parameters.

500 if an unknown error occurs (but not if there is an error processing an email; those results will get a 200 response but have emails in the “failedEmails” field)

Single Email GET: http://api.fullcontact.com/v2/verification/email

Parameters: email: string. The email.

curl 'http://api.fullcontact.com/v2/verification/email?email=bart@fullcontact.com&apiKey=your_key_here'

{
    "status": 200,
    "requestId": "b782bfd2-ddc9-4e78-bf9a-ea05a6b8af97",
    "emails": {
        "bart@fullcontact.com": {
            "message": "Valid email address",
            "address": "bart@fullcontact.com",
            "username": "bart",
            "domain": "fullcontact.com",
            "corrected": false,
            "attributes": {
                "validSyntax": true,
                "deliverable": true,
                "catchall": false,
                "risky": false,
                "disposable": false
            },
            "person": "https://api.fullcontact.com/v2/person.json?email=bart@fullcontact.com&apiKey=",
            "company": "https://api.fullcontact.com/v2/company/lookup.json?domain=fullcontact.com&apiKey=",
            "sendSafely": true
        }
    }
}

curl 'http://api.fullcontact.com/v2/verification/email?email=bad-email@fullcontact.com&apiKey=your_key_here'

{
    "status": 200,
    "requestId": "b782bfd2-ddc9-4e78-bf9a-ea05a6b8af97",
    "unknownEmails": [ "bad-email@fullcontact.com" ]
}

Submit Batch Request: POST http://api.fullcontact.com/v2/verification/emails

Submits multiple emails at once for processing. This is the preferred method for processing multiple emails. It can accept and process up to 300 emails in a single request (if you need more capacity than that, please let us know). Once submitted, the result of this batch request can be supplied either via webhooks or via our batch status polling endpoint (see below).

POST Body

The endpoint expects a request body with content type application/json. The JSON object may contain the following fields:

{
   "emails":
       [
           "travis@fullcontact.com",
           "bart@fullcontact.com"
       ],
   "webhookUrl": "http://webhook.url/whr"
}

emails: an array of the emails to be submitted. Max 300 (if you need more than that please let us know).

webhookUrl: If you want to make use of webhooks, you can specify your webhook callback URL here and we will deliver the information associated with this batch when it is complete.

Example And Response

curl -XPOST 'http://api.fullcontact.com/v2/verification/emails.json?apiKey=key_here -H'Content-Type: application/json' --data '{ "emails": ["travis@fullcontact.com", "bart@fullcontact.com"] }'

{
   "batchId":"afacdb51-7ea8-46bf-846f-f60cf387d8a2-vs",
   "webhookUrl":null,
   "completed":false
}

batchId: The identifier for this batch of emails. This identifier is how you may access the results of this batch of emails later.

webhookUrl: If you supplied a webhookUrl, this will be present in the response.

completed: always false upon submitting a batch.

GET Email Batch Status http://api.fullcontact.com/v2/verification/emails/{id}

GET the state and result of a previous batch request, where {id} represents the “batchId” field that was present in the result of the batch submit request above. You can also receive these results by webhook.

If the batch ID does not exist (or has been removed from our system), the status code will be 404.

There is no guaranteed amount of time it will take for a batch request to be completed, but 1 - 10 minutes is the average depending on the type and amount of emails.

Response:

If the batch is not yet complete: curl ‘http://api.fullcontact.com/v2/verification/emails/afacdb51-7ea8-46bf-846f-f60cf387d8a2-vs?apiKey=key_here’

{
   "batchId":"afacdb51-7ea8-46bf-846f-f60cf387d8a2-vs",
   "webhookUrl":null,
   "completed":false
}

If the batch is complete, the “response” object will be present:

{
   "batchId":"afacdb51-7ea8-46bf-846f-f60cf387d8a2-vs",
   "webhookUrl":null,
   "completed":true,
   "response": {
        "status": 200,
        "emails": {
            "travis@fullcontact.com": {
                "message": "Valid email address",
                "address": "travis@fullcontact.com",
                "username": "travis",
                "domain": "fullcontact.com",
                "corrected": false,
                "attributes": {
                    "validSyntax": true,
                    "deliverable": true,
                    "catchall": false,
                    "risky": false,
                    "disposable": false
                },
                "person": "https://api.fullcontact.com/v2/person.json?email=travis@fullcontact.com&apiKey=",
                "company": "https://api.fullcontact.com/v2/company/lookup.json?domain=fullcontact.com&apiKey=",
                "sendSafely": true
            },
            "bad-email@fullcontact.com": {
                "message": "Invalid email address",
                "address": "bad-email@fullcontact.com",
                "username": "bad-email",
                "domain": "fullcontact.com",
                "corrected": false,
                "attributes": {
                    "validSyntax": true,
                    "deliverable": false,
                    "catchall": false,
                    "risky": false,
                    "disposable": false
                },
                "person": "https://api.fullcontact.com/v2/person.json?email=bad-email@fullcontact.com&apiKey=",
                "company": "https://api.fullcontact.com/v2/company/lookup.json?domain=fullcontact.com&apiKey=",
                "sendSafely": false
            }
        }
    }
}