Truelist API Usage Guide

Truelist has a comprehensive API that allows you to integrate email verification into your own applications. This API is perfect for developers who want to build email verification into their own applications, or for businesses that want to automate their email verification process.

Quick links

API documentation

API key management (in-app)

Examples for common use cases

For all examples, replace TOKEN with your api token.
UUIDs seen are examples. replace uuids with your own.

Get all batches (lists) in your account

    curl "https://api.truelist.io/api/v1/batches" \
        -H "Authorization: Bearer TOKEN" \
        -H "Content-Type: application/json"

Get a single batch:

curl "https://api.truelist.io/api/v1/batches/a76d8ca3-c17f-40a6-b5ed-4ef33b55b7a1" \
     -H "Authorization: Bearer TOKEN" \
     -H "Content-Type: application/json"

Upload a file to verify

curl -X POST "http://localhost:3000/api/v1/batches" \
     -H "Authorization: Bearer TOKEN" \
     -H "Content-Type: multipart/form-data" \
     -F "file=@./scripts/list_150.csv"

Response:

You’ll get the JSON representation of the batch you uploaded.

{
  "id": "9b8b256a-1b50-442a-b45d-77c02ec372a4",
  "batch_state": "pending_processing",
  "batch_type": "user_import",
  "email_count": 150,
  "processed_count": 0,
  "disposable_count": null,
  "role_count": null,
  "failed_syntax_check_count": null,
  "failed_mx_check_count": null,
  "failed_no_mailbox_count": null,
  "ok_for_all_count": null,
  "ok_count": null,
  "name": "list_150.csv",
  "duplicateCount": null,
  "safest_bet_csv_url": null,
  "highest_reach_csv_url": null,
  "only_invalid_csv_url": null,
  "annotated_csv_url": null
}

Or you might get an error if the file has errors.

Upload a comma-separated list of emails to verify:

curl -X POST "https://api.truelist.io/api/v1/batches" \
     -H "Authorization: Bearer TOKEN" \
     -H "Content-Type: application/json" \
     -G --data-urlencode "emails=email1@example.com,email2@example.com,email3@example.com"

Verify a few emails during an api request

curl -X POST "https://api.truelist.io/api/v1/verify_inline" \
     -H "Authorization: Bearer TOKEN" \
     -H "Content-Type: application/json" \
     -G --data-urlencode "email=gammons+5@gmail.com gammons+6@gmail.com gammons+7@gmail.com"

Response

{
  "emails": [
    {
      "email": {
        "address": "gammons+5@gmail.com",
        "domain": "gmail.com",
        "first_name": null,
        "last_name": null,
        "canonical": "gammons",
        "mx_record": "gmail-smtp-in.l.google.com",
        "email_state": "ok",
        "email_sub_state": "email_ok",
        "verified_at": "2024-11-04T11:31:34.105Z",
        "credit_used": null
      }
    },
    {
      "email": {
        "address": "gammons+6@gmail.com",
        "domain": "gmail.com",
        "first_name": null,
        "last_name": null,
        "canonical": "gammons",
        "mx_record": "gmail-smtp-in.l.google.com",
        "email_state": "ok",
        "email_sub_state": "email_ok",
        "verified_at": "2024-11-04T11:31:37.457Z",
        "credit_used": null
      }
    },
    {
      "email": {
        "address": "gammons+7@gmail.com",
        "domain": "gmail.com",
        "first_name": null,
        "last_name": null,
        "canonical": "gammons",
        "mx_record": "gmail-smtp-in.l.google.com",
        "email_state": "risky",
        "email_sub_state": "accept_all",
        "verified_at": "2024-11-04T11:31:37.553Z",
        "credit_used": null
      }
    }
  ]
}

Delete a batch

curl -X DELETE "https://api.truelist.io/api/v1/batches/b7198477-c0a6-496e-a7cc-731744a74a78" \
     -H "Authorization: Bearer TOKEN" \
     -H "Content-Type: application/json"