Email Lists

Email lists are a way to group emails together. They are useful for managing emails that are related to a specific purpose or topic. For example, you might have an email list for specific customers, or for an email campaign.

The Email List model

The email list model contains all the information about your email list, such as it's name, description, and the emails it contains.

Properties

Name
id
Type
string
Description
Unique identifier for the email list.
Name
name
Type
string
Description
The name of the email list.
Name
description
Type
string
Description
The description of the email list.
Name
email_count
Type
integer
Description
The number of emails in the email list.
Name
rejected_count
Type
integer
Description
The number of emails in the email list that were rejected.
Name
status
Type
string
Description
The processing status of the email list. Possible values are: pending, processing, completed, insufficient_credits, and error.

POST/api/v1/emailList

Create email list

This endpoint allows you to create email lists.

Email lists are marked as completed initially. Once emails are added to the email list, the status will change to processing and then completed once the emails have been processed.

Required attributes

Name
name
Type
string
Description
The name of the email list.

Optional attributes

Name
description
Type
string
Description
The description of the email list.

Request

POST

/api/v1/emailList

curl --request POST --location 'https://verifiable.co/api/v1/emailList' \
--header 'Authorization: Bearer {token}' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--data '{
    "name": "My List",
    "description": "Best email list in the world"
}'

Response

{
  "id": 16,
  "name": "My List",
  "description": "Best email list in the world",
  "status": "completed",
  "email_count": 0,
  "rejected_count": 0,
  "status": "completed"
}

GET/api/v1/emailList/:id

Get an email list

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

This endpoint only returns the email list object. To retrieve the emails in the email list, you must use the Get email list emails endpoint.

Request

GET

/api/v1/emailList/:id

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

Response

{
  "id": 16,
  "name": "My List",
  "description": "Best email list in the world",
  "status": "completed",
  "email_count": 0,
  "rejected_count": 0
}

GET/api/v1/emailLists

Get all email lists

This endpoint allows you to retrieve all your email lists. Email lists are paginated, with a maximum of 100 email lists per page.

Refer to the list at the top of this page to see which properties are included with email list objects.

Request

GET

/api/v1/emailLists

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

Response

{
  "emailLists": [
    {
          "id": 16,
          "name": "My List",
          "description": "Best email list in the world",
          "status": "completed",
          "email_count": 0,
          "rejected_count": 0
        },
        {
          "id": 17,
          "name": "Awesome List",
          "description": "Best email list in the world",
          "status": "pending",
          "email_count": 0,
          "rejected_count": 0
        }
  ],
  "page": 1,
  "totalPages": 2
}

GET/api/v1/emailList/:id/emails

Get email list emails

This endpoint allows you to retrieve a paginated list of all the emails in an email list.

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

/api/v1/emailList/:id/emails?page=2

Request

GET

/api/v1/emailList/:id/emails

curl --location 'https://verifiable.co/api/v1/emailList/:id/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,
        "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"
    },
    {
        "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
}

POST/api/v1/emailList/:id/emails

Add email list emails

This endpoint allows you to add emails to an email list. Only 100 emails can be added per request.

When adding emails to an email list, the status of the email list will change to processing and then completed once the emails have been processed.

Required attributes

Name
emails
Type
array
Description
The emails to add to the email list.

Request

POST

/api/v1/emailList/:id/emails

 curl --request POST --location 'https://verifiable.co/api/v1/emailList/:id/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

{
  "emailList": {
    "id": 16,
    "name": "My List",
    "description": "Best email list in the world",
    "status": "completed",
    "email_count": 0,
    "rejected_count": 0
  },
  "emails": [
    {
        "email": "help@verifiable.co",
        "id": 34,
        "email_list_id": 16,
        "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"
    },
    {
        "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"
    },
    {
        "email": "not an email",
        "error": "Invalid email"
    }
  ]
}

DELETE/api/v1/emailList/:id

Delete an email list

This endpoint allows you to delete an email list by providing it's ID. Deleting an email list will also delete all the emails in the list.

Request

DELETE

/api/v1/emailList/:id

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