API docs by Redocly

Truelist.io API documentation (0.2.2)

Download OpenAPI specification:Download

API Support: hello@truelist.io

Welcome to Truelist's api!
To get started, generate an api key. You'll use the API key in an Authorization header in every request.
A note about rate limits: Each endpoint has a rate limit. If you exceed the rate limit, you'll get a 429 error. The rate limit is 10 requests per second. This rate limit is specifically for API calls. The email validation rate limit is different and is based on your plan.

Me

Everything about the user that is using the api

Get information about the logged in user

Shows all information about the currently logged in user.

Authorizations:
truelist_auth

Responses

Response samples

Content type
application/json
{
  • "email": "user@example.com",
  • "name": "string",
  • "uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f",
  • "errors": [
    ],
  • "last_login_at": "2019-08-24T14:15:22Z",
  • "time_zone": "string",
  • "token": "string",
  • "api_keys": [
    ]
}

Single email validation

Endpoints used to validate a single email address. Validation occurs within the request cycle.

Verify a single email address

Verify up to 3 email addresses. Verification will happen inline during the api request.

Note: If email validation takes over 30 seconds, this request will time out.

Authorizations:
truelist_auth
query Parameters
email
required
string <email>
Examples:
  • email=bob@example.com jon@example.com test@example.com - A space-separated list of emails

A space-separated list of emails

Responses

Response samples

Content type
application/json
{
  • "emails": [
    ]
}

Batch email validation

A Batch is a collection of email addresses that are uploaded to be validated. Batches are processed in the background and can be checked on later.

Verify a list of emails

Upload a list of emails to verify. You can either of the following (but not both):

  • A data parameter that represents a json array of email data. Should be in the format of [['email@email.com'], ['email2@email.com']]. Each row can also contain arbitrary data, which is useful for supplying external ids or other identifying information. This data will be returned in the annotated csv result files. However, one element in the row array must be an email address. Needs at least 2 rows of data to be valid.
  • A binary file upload via the file parameter documented below.

Note that batches are processed in the background. To check on the status of a list, you have a couple of options:

  • Poll the status of your batch's progress by GETing the batch you created by its uuid.
  • Supply a webhook_url when creating the batch. Truelist will makd a POST request to the url you supplied when the batch is completed. When we call your url, we'll supply the batch_id in the body of the request. Also note that counts are not updated until the batch is completed.
Authorizations:
truelist_auth
Request Body schema:
required

this is the description

file
string <binary>

The CSV / XLSX file to upload

uuid
string <uuid>

Supply a UUID if you want the batch to have this UUID. Otherwise, a random UUID will be generated.

webhook_url
string

Supply a webhook_url when creating a batch. Truelist will call the url when the batch has completed.

validation_strategy
string
Enum: "accurate" "fast"

The validation strategy to use for the batch. Defaults to accurate. Using fast will skip our internal backoff/retry logic and deeper validation strategy checks. This is useful for when you want to validate a large number of emails quickly, but it may result in more false positives.

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "batch_state": "pending",
  • "batch_type": "user_import api_import integration",
  • "email_count": 0,
  • "processed_count": 0,
  • "disposable_count": 0,
  • "role_count": 0,
  • "failed_syntax_check_count": 0,
  • "failed_mx_check_count": 0,
  • "failed_no_mailbox_count": 0,
  • "ok_for_all_count": 0,
  • "unknown_count": 0,
  • "ok_count": 0,
  • "name": "string",
  • "webhook_url": "string",
  • "safest_bet_csv_url": "string",
  • "highest_reach_csv_url": "string",
  • "only_invalid_csv_url": "string",
  • "annotated_csv_url": "string"
}

Retrieve all batches for your account.

Authorizations:
truelist_auth

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Retrieve a single batch by its UUID.

Authorizations:
truelist_auth
path Parameters
uuid
required
string <uuid>

The UUID of the batch to get

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "batch_state": "pending",
  • "batch_type": "user_import api_import integration",
  • "email_count": 0,
  • "processed_count": 0,
  • "disposable_count": 0,
  • "role_count": 0,
  • "failed_syntax_check_count": 0,
  • "failed_mx_check_count": 0,
  • "failed_no_mailbox_count": 0,
  • "ok_for_all_count": 0,
  • "unknown_count": 0,
  • "ok_count": 0,
  • "name": "string",
  • "webhook_url": "string",
  • "safest_bet_csv_url": "string",
  • "highest_reach_csv_url": "string",
  • "only_invalid_csv_url": "string",
  • "annotated_csv_url": "string"
}

Delete a batch by its UUID.

Authorizations:
truelist_auth
path Parameters
uuid
required
string <uuid>

The UUID of the batch to get

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "batch_state": "pending",
  • "batch_type": "user_import api_import integration",
  • "email_count": 0,
  • "processed_count": 0,
  • "disposable_count": 0,
  • "role_count": 0,
  • "failed_syntax_check_count": 0,
  • "failed_mx_check_count": 0,
  • "failed_no_mailbox_count": 0,
  • "ok_for_all_count": 0,
  • "unknown_count": 0,
  • "ok_count": 0,
  • "name": "string",
  • "webhook_url": "string",
  • "safest_bet_csv_url": "string",
  • "highest_reach_csv_url": "string",
  • "only_invalid_csv_url": "string",
  • "annotated_csv_url": "string"
}

Retrieving results

Endpoints used to retrieve the results of a batch validation.

Retrieve email validation results

Authorizations:
truelist_auth
path Parameters
batch_uuid
string <uuid>

The UUID of the batch to get emails from

email_state
string
Enum: "ok" "risky" "invalid" "unknown"

Get emails with a particular email_state

email_sub_state
string
Enum: "email_ok" "accept_all" "is_disposable" "is_role" "failed_mx_check" "failed_smtp_check" "failed_no_mailbox" "failed_greylisted" "failed_syntax_check"

Get emails with a particular email_sub_state

email_address
string <email>

Search for a particular email address

page
integer

The page number to retrieve. If not specified, the first page will be returned.

per_page
integer

The number of emails to return per page. If not specified, 25 will be returned. The maximum is 100.

Responses

Response samples

Content type
application/json
{
  • "email_addresses": [
    ]
}