Emails

Emails are the core resource of Verifiable - the very reason Verifiable exists is to validate emails. On this page, we'll dive into the different email endpoints you can use to manage emails programmatically. We'll look at how to query, create, update, and delete emails.

The Email model

The email model contains all the information about your email, such as it's validity, connectability, mx record details and other attributes. Emails can be created, validated and managed individually or as a part of an Email List.

Properties

Name
id
Type
string
Description
Unique identifier for the email.
Name
email
Type
string
Description
The email address.
Name
email_list_id
Type
integer
Description
The ID of the email list the email belongs to.
Name
is_valid
Type
boolean
Description
Flag indicating if the email is valid.
Name
score
Type
integer
Description
The qualityscore of the email.
Name
can_connect
Type
boolean
Description
Flag indicating if able to connect to an SMTP server. This flag is set to true if any of the MX records are connectable.
Name
mx_record_count
Type
integer
Description
The number of MX records for the email.
Name
connectable_mx_record_count
Type
integecdr
Description
The number of MX records that are connectable.
Name
is_username_generic
Type
boolean
Description
Flag indicating if the email's username is generic (i.e., contact@example.com, sales@example.com, etc.)
Name
is_alias
Type
boolean
Description
Flag indicating if the email is an alias (i.e., contact+alias@example.com).
Name
is_gov
Type
boolean
Description
Flag indicating if the email is a government email (.gov).
Name
is_edu
Type
boolean
Description
Flag indicating if the email is an education email (.edu).
Name
is_mil
Type
boolean
Description
Flag indicating if the email is a military email (.mil).
Name
is_free
Type
boolean
Description
Flag indicating if the email uses a free email service (i.e., gmail.com, yahoo.com, etc.).
Name
is_subdomain
Type
boolean
Description
Flag indicating if the email is a subdomain (i.e., contact.example.com).
Name
canonical_email
Type
string
Description
The canonical email address for the email. For example, if the email is contact+alias@example.com, the canonical email address is contact@example.com.
Name
status
Type
string
Description
The processing status of the email. Possible values are: pending, processing, completed and error.

POST/api/v1/emails

Create emails

This endpoint allows you to create and validate emails.

By default emails are not added to an email list. To add an email to an email list, use the add email list emails endpoint.

Required attributes

Name
emails
Type
array
Description
The email addresses to create and validate. Limit 100 emails per request.

Request

POST

/api/v1/emails

curl --request POST --location 'https://verifiable.co/api/v1/emails' \
--header 'Authorization: Bearer {token}' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--data-raw '{
  "emails": [
    "help@verifiable.co",
    "support@verifiable.co",
    "not an email"
  ]
}'

Response

{
"emails": [
    {
        "email": "help@verifiable.co",
        "id": 34,
        "is_valid": true,
        "score": 100,
        "mx_record_count": 1,
        "connectable_mx_record_count": 1,
        "can_connect": true,
        "is_username_generic": true,
        "is_alias": false,
        "is_gov": false,
        "is_edu": false,
        "is_mil": false,
        "canonical_email": "help@verifiable.co",
        "is_free": false,
        "is_subdomain": false,
        "status": "pending"
    },
    {
        "email": "support@verifiable.co",
        "id": 41,
        "is_valid": true,
        "score": 100,
        "mx_record_count": 1,
        "connectable_mx_record_count": 1,
        "can_connect": true,
        "is_username_generic": true,
        "is_alias": false,
        "is_gov": false,
        "is_edu": false,
        "is_mil": false,
        "canonical_email": "support@verifiable.co",
        "is_free": false,
        "is_subdomain": false,
        "status": "completed"
    },
    {
        "email": "not an email",
        "error": "Invalid email"
    }
]
}

GET/api/v1/email/:id

Get an email

This endpoint allows you to retrieve an email by providing it's ID. Refer to the list at the top of this page to see which properties are included with email objects.

Request

GET

/api/v1/email/:id

curl --location 'https://verifiable.co/api/v1/email/:id' \
--header 'Authorization: Bearer {token}' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json'

Response

{
        "email": "help@verifiable.co",
        "id": 34,
        "is_valid": true,
        "score": 100,
        "mx_record_count": 1,
        "connectable_mx_record_count": 1,
        "can_connect": true,
        "is_username_generic": true,
        "is_alias": false,
        "is_gov": false,
        "is_edu": false,
        "is_mil": false,
        "canonical_email": "help@verifiable.co",
        "is_free": false,
        "is_subdomain": false,
        "status": "completed"
    }

GET/api/v1/emails

Get all emails

This endpoint allows you to retrieve a paginated list of all your emails.

By default, a maximum of 100 emails are shown per page. You can change this by providing the page url parameter:

/api/v1/emails?page=2

Request

GET

/api/v1/emails

curl --location 'https://verifiable.co/api/v1/emails' \
--header 'Authorization: Bearer {token}' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json'

Response

{
  "emails": [
    {
        "email": "help@verifiable.co",
        "id": 34,
        "email_list_id": 16,
        "is_valid": true,
        "mx_record_count": 1,
        "connectable_mx_record_count": 1,
        "can_connect": true,
        "is_username_generic": true,
        "is_alias": false,
        "is_gov": false,
        "is_edu": false,
        "is_mil": false,
        "canonical_email": "help@verifiable.co",
        "is_free": false,
        "is_subdomain": false,
        "status": "completed"
    },
    {
        "email": "support@verifiable.co",
        "email_list_id": 16,
        "id": 41,
        "is_valid": true,
        "score": 100,
        "mx_record_count": 1,
        "connectable_mx_record_count": 1,
        "can_connect": true,
        "is_username_generic": true,
        "is_alias": false,
        "is_gov": false,
        "is_edu": false,
        "is_mil": false,
        "canonical_email": "support@verifiable.co",
        "is_free": false,
        "is_subdomain": false,
        "status": "completed"
    }
  ],
  "page": 1,
  "totalPages": 2
}

DELETE/api/v1/email/:id

Delete an email

This endpoint allows you to delete an email by providing it's ID. If an email is part of an email list, it will also be removed from the list.

Request

DELETE

/api/v1/email/:id

curl --request DELETE --location 'https://verifiable.co/api/v1/email/:id' \
--header 'Authorization: Bearer {token}' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json'