Truelist

https://truelist.io/docs
Admin
Truelist is an email verification platform that validates email addresses in real-time and batch to...
Tokens:9,923
Snippets:181
Trust Score:8.5
Update:6 months ago
Show doc for...
Tokens:
Raw
### Get User Information

Source: https://truelist.io/docs/api

Retrieve information about the currently logged-in user using their API key.

```APIDOC
## GET /me

### Description
Retrieves all information about the currently logged-in user.

### Method
GET

### Endpoint
https://api.truelist.io/me

### Authentication
Requires an `Authorization` header with a Bearer token.
```
Authorization: Bearer YOUR_API_KEY
```

### Responses
#### Success Response (200)
Returns user details including email, name, UUID, login information, and API keys.
```json
{
  "email": "hello@example.com",
  "name": "string",
  "uuid": "123e4567-e89b-12d3-a456-426614174000",
  "errors": [
    "string"
  ],
  "last_login_at": "2026-04-10T20:57:50.302Z",
  "time_zone": "string",
  "token": "string",
  "api_keys": [
    {
      "active": true,
      "name": "string",
      "last_used_at": "2026-04-10T20:57:50.302Z",
      "created_at": "2026-04-10T20:57:50.302Z"
    }
  ]
}
```

#### Error Response (401)
Returned if the user cannot be found via the provided token.

### Request Example
```bash
curl https://api.truelist.io/me \
  --header 'Authorization: YOUR_SECRET_TOKEN'
```
```

--------------------------------

### Form Submission Integration

Source: https://truelist.io/docs/form-validation

JavaScript example for validating an email address within a form's submit event handler.

```javascript
const form = document.querySelector('#signup-form');

form.addEventListener('submit', async (event) => {
  event.preventDefault();

  const email = form.querySelector('input[type="email"]').value;

  const response = await fetch('https://api.truelist.io/api/v1/form_verify', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': 'Bearer YOUR_FORM_API_KEY'
    },
    body: JSON.stringify({ email })
  });

  const data = await response.json();

  if (data.error) {
    console.error('Validation error:', data.error);
    return;
  }

  if (data.result === 'invalid') {
    if (data.suggestion) {
      alert('Did you mean ' + data.suggestion + '?');
    } else {
      alert('Please enter a valid email address.');
    }
    return;
  }

  // Email is valid or risky — continue with form submission
  form.submit();
});
```

--------------------------------

### Inline Blur Validation

Source: https://truelist.io/docs/form-validation

JavaScript example for triggering email validation when the user leaves the input field.

```javascript
const emailInput = document.querySelector('input[type="email"]');
const errorEl = document.querySelector('#email-error');

emailInput.addEventListener('blur', async () => {
  const email = emailInput.value;
  if (!email) return;

  const response = await fetch('https://api.truelist.io/api/v1/form_verify', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': 'Bearer YOUR_FORM_API_KEY'
    },
    body: JSON.stringify({ email })
  });

  const data = await response.json();

  if (data.result === 'invalid') {
    errorEl.textContent = data.suggestion
      ? 'Did you mean ' + data.suggestion + '?'
      : 'This email address appears to be invalid.';
    errorEl.classList.remove('hidden');
  } else {
    errorEl.classList.add('hidden');
  }
});
```

--------------------------------

### Retrieve User Information

Source: https://truelist.io/docs/api

Fetch details about the currently authenticated user.

```bash
curl https://api.truelist.io/me \
  --header 'Authorization: YOUR_SECRET_TOKEN'
```

--------------------------------

### Configure Clay.com HTTP API Request

Source: https://truelist.io/docs/integrations/clay.com

Settings for the HTTP API column in Clay.com to verify emails using the Truelist API.

```text
POST
```

```text
https://api.truelist.io/api/v1/verify_inline
```

```json
{ "email": "{{email}}" }
```

```text
Authorization: Bearer <your-api-key>
```

--------------------------------

### User Information Response Schema

Source: https://truelist.io/docs/api

The JSON structure returned by the /me endpoint.

```json
{
  "email": "hello@example.com",
  "name": "string",
  "uuid": "123e4567-e89b-12d3-a456-426614174000",
  "errors": [
    "string"
  ],
  "last_login_at": "2026-04-10T20:57:50.302Z",
  "time_zone": "string",
  "token": "string",
  "api_keys": [
    {
      "active": true,
      "name": "string",
      "last_used_at": "2026-04-10T20:57:50.302Z",
      "created_at": "2026-04-10T20:57:50.302Z"
    }
  ]
}
```

--------------------------------

### Set Base API URL

Source: https://truelist.io/docs/api

The base URL for all API requests.

```text
https://api.truelist.io
```

--------------------------------

### API Endpoint

Source: https://truelist.io/docs/form-validation

The base URL for the form verification service.

```text
POST https://api.truelist.io/api/v1/form_verify
```

--------------------------------

### Request Body

Source: https://truelist.io/docs/form-validation

The JSON structure required for the verification request.

```json
{
  "email": "user@example.com"
}
```

--------------------------------

### Authenticate API Requests

Source: https://truelist.io/docs/api

Include the API key as a Bearer token in the Authorization header for all requests.

```http
Authorization: Bearer YOUR_API_KEY
```

--------------------------------

### POST /api/v1/form_verify

Source: https://truelist.io/docs/form-validation

Validates an email address in real-time to determine if it is valid, invalid, risky, or unknown.

```APIDOC
## POST https://api.truelist.io/api/v1/form_verify

### Description
Validates an email address at the point of entry to prevent invalid addresses from entering your system.

### Method
POST

### Endpoint
https://api.truelist.io/api/v1/form_verify

### Parameters
#### Request Body
- **email** (string) - Required - The email address to validate.

### Request Example
{
  "email": "user@example.com"
}

### Response
#### Success Response (200)
- **result** (string) - The validation status: 'valid', 'invalid', 'risky', or 'unknown'.
- **suggestion** (string) - Optional - A suggested correction if the email is invalid.

#### Response Example
{
  "result": "invalid",
  "suggestion": "user@gmail.com"
}

### Error Responses
- **401** - invalid_api_key: The API key is missing or invalid.
- **403** - domain_not_allowed: The requesting domain is not in the key’s allowed domains list.
- **403** - https_required: The request must be made over HTTPS.
- **403** - origin_required: The Origin header is missing from the request.
- **422** - email_required: The email field is missing from the request body.
- **429** - rate_limited: Too many requests from this IP address.
```

--------------------------------

### Single Email Verification

Source: https://truelist.io/docs/api

Verify a single email address in real-time.

```APIDOC
## POST /api/v1/verify_inline

### Description
Verifies a single email address. The validation occurs within the request cycle.

### Method
POST

### Endpoint
https://api.truelist.io/api/v1/verify_inline

### Authentication
Requires an `Authorization` header with a Bearer token.
```
Authorization: Bearer YOUR_API_KEY
```

### Query Parameters
- **email** (string) - Required - The email address to verify. Multiple email addresses can be provided, separated by spaces.

### Request Example
```bash
curl -X POST "https://api.truelist.io/api/v1/verify_inline?email=bob@example.com,jon@example.com,test@example.com" \
  -H "Authorization: Bearer YOUR_API_KEY"
```
```

--------------------------------

### Batch Email Validation

Source: https://truelist.io/docs/api

Manage batch email validations, including creation and retrieval.

```APIDOC
## Batch Email Validation Endpoints

### POST /api/v1/batches

#### Description
Creates a new batch for email validation. Batches are processed in the background.

#### Method
POST

#### Endpoint
https://api.truelist.io/api/v1/batches

#### Authentication
Requires an `Authorization` header with a Bearer token.
```
Authorization: Bearer YOUR_API_KEY
```

#### Request Body
(Details for request body not provided in source text)

### GET /api/v1/batches

#### Description
Retrieves a list of all email validation batches.

#### Method
GET

#### Endpoint
https://api.truelist.io/api/v1/batches

#### Authentication
Requires an `Authorization` header with a Bearer token.
```
Authorization: Bearer YOUR_API_KEY
```

### GET /api/v1/batches/{uuid}

#### Description
Retrieves details for a specific email validation batch using its UUID.

#### Method
GET

#### Endpoint
https://api.truelist.io/api/v1/batches/{uuid}

#### Parameters
##### Path Parameters
- **uuid** (string) - Required - The unique identifier of the batch.

#### Authentication
Requires an `Authorization` header with a Bearer token.
```
Authorization: Bearer YOUR_API_KEY
```

### DELETE /api/v1/batches/{uuid}

#### Description
Deletes a specific email validation batch using its UUID.

#### Method
DELETE

#### Endpoint
https://api.truelist.io/api/v1/batches/{uuid}

#### Parameters
##### Path Parameters
- **uuid** (string) - Required - The unique identifier of the batch to delete.

#### Authentication
Requires an `Authorization` header with a Bearer token.
```
Authorization: Bearer YOUR_API_KEY
```
```

--------------------------------

### Error Response Format

Source: https://truelist.io/docs/form-validation

The standard JSON structure returned when an API request fails.

```json
{
  "error": "domain_not_allowed"
}
```

--------------------------------

### Retrieving Batch Validation Results

Source: https://truelist.io/docs/api

Endpoints for retrieving the results of batch email validations.

```APIDOC
## GET /api/v1/email_addresses

### Description
Retrieves the results of email validations, likely associated with batches.

### Method
GET

### Endpoint
https://api.truelist.io/api/v1/email_addresses

### Authentication
Requires an `Authorization` header with a Bearer token.
```
Authorization: Bearer YOUR_API_KEY
```

(Further details on query parameters or response structure for this endpoint were not provided in the source text.)
```
Tokens:
Raw