Bulk Validation

Learn how to validate multiple email addresses in a single request using the Mails API.

Endpoint

POST https://api.mails.so/v1/batch

Request

Headers

• Content-Type: application/json
• x-mails-api-key: YOUR_API_KEY_HERE

Body

The request body should be a JSON object with an emails array containing the email addresses to validate:

{
  "emails": ["[email protected]", "[email protected]", "[email protected]"]
}

Request Example

Here's an example of how to make a bulk validation request using curl:

curl \
  -H "x-mails-api-key: YOUR_API_KEY_HERE" \
  -H "Content-Type: application/json" \
  -d '{"emails": [ "[email protected]", "[email protected]", "[email protected]" ]}' \
  "https://api.mails.so/v1/batch"

Replace YOUR_API_KEY_HERE with your actual Mails API key.

Response

The API can return different types of responses:

Successful Response (200 OK)

If the request is successful, you'll receive a JSON response with details about the batch job:

{
  "id": "ddb951fe-643d-4c20-bc2c-525593d86cb6",
  "name": null,
  "created_at": "2024-07-22T08:15:33.599428539Z",
  "updated_at": "2024-07-22T08:15:33.599428539Z",
  "deleted_at": null,
  "finished_at": null,
  "user": null,
  "user_id": "a143de55-5dc6-45c1-abb1-035dc86150b4",
  "size": 3
}

Bad Request Response (400 Bad Request)

If the request body is invalid, you'll receive an error response:

{
  "data": null,
  "error": "The body provided has an invalid format."
}

Unauthorized Response (401 Unauthorized)

If the API key is invalid or missing, you'll receive an unauthorized error:

{
  "data": null,
  "error": "Unauthorized."
}

If you don't have a paid subscription for list validations, you'll receive this error:

{
  "data": null,
  "error": "Paid subscription required to use list validations"
}

Response Fields

Field	Description
id	Unique identifier for the batch job
name	Name of the batch job (if provided)
created_at	Timestamp when the batch job was created
updated_at	Timestamp when the batch job was last updated
deleted_at	Timestamp when the batch job was deleted (if applicable)
finished_at	Timestamp when the batch job finished (if completed)
user	User information (if available)
user_id	ID of the user who initiated the batch job
size	Number of email addresses in the batch

Error Handling

• If you receive a 400 Bad Request error, check your request body to ensure it's properly formatted JSON with an emails array.
• If you receive a 401 Unauthorized error, make sure you're using a valid API key in your request header.
• Handle potential network errors and timeout scenarios in your implementation.

Retrieving Results

The batch validation is an asynchronous process. To retrieve the results of your batch job, follow these steps:

1. Use the id returned in the initial response to query the status and results of your batch job.

2. Make a GET request to the following endpoint:

   GET https://api.mails.so/v1/batch/{id}

   Replace {id} with the actual batch job ID.

3. Include your API key in the header:

   x-mails-api-key: YOUR_API_KEY_HERE

Results Format

The response will include the batch job details along with an emails array containing the validation results for each email address. Here's an example of the response format:

{
  "id": "920e0609-9207-4dbd-a5f9-273bc3d9d288",
  "name": null,
  "created_at": "2024-07-22T10:25:06.067124Z",
  "updated_at": "2024-07-22T10:25:07.254477Z",
  "deleted_at": null,
  "finished_at": "2024-07-22T10:25:07.232981Z",
  "user": null,
  "user_id": "a143de55-5dc6-45c1-abb1-035dc86150b4",
  "size": 3,
  "emails": [
    {
      "id": "9cdfdd2d-73cf-45b6-b82c-577f3e3d8872",
      "email": "[email protected]",
      "username": null,
      "domain": null,
      "mx_record": "gmail-smtp-in.l.google.com",
      "score": 60,
      "isv_format": true,
      "isv_domain": true,
      "isv_mx": null,
      "isv_noblock": true,
      "isv_nocatchall": true,
      "isv_nogeneric": true,
      "is_free": true,
      "result": "unknown",
      "reason": "timeout"
    },
    {
      "id": "a09ac01d-a94f-4661-8898-6712128ddb3f",
      "email": "[email protected]",
      "username": null,
      "domain": null,
      "mx_record": "gmail-smtp-in.l.google.com",
      "score": 60,
      "isv_format": true,
      "isv_domain": true,
      "isv_mx": null,
      "isv_noblock": true,
      "isv_nocatchall": true,
      "isv_nogeneric": true,
      "is_free": true,
      "result": "unknown",
      "reason": "timeout"
    },
    {
      "id": "a48fdb9b-8aeb-493d-90b1-41955eb905fa",
      "email": "[email protected]",
      "username": null,
      "domain": null,
      "mx_record": "gmail-smtp-in.l.google.com",
      "score": 100,
      "isv_format": true,
      "isv_domain": true,
      "isv_mx": true,
      "isv_noblock": true,
      "isv_nocatchall": true,
      "isv_nogeneric": true,
      "is_free": true,
      "result": "deliverable",
      "reason": "accepted_email"
    }
  ]
}

Result Fields

Each email in the emails array includes the following fields:

Field	Description
id	Unique identifier for the email validation result
email	The email address that was validated
username	The username part of the email address (if available)
domain	The domain part of the email address (if available)
mx_record	The MX record associated with the email domain
score	A score indicating the overall validity of the email (0-100)
isv_format	Whether the email format is valid
isv_domain	Whether the email domain is valid
isv_mx	Whether the MX record is valid (null if not checked)
isv_noblock	Whether the email is not in a block list
isv_nocatchall	Whether the email is not a catch-all address
isv_nogeneric	Whether the email is not a generic address
is_free	Whether the email is from a free email provider
result	The overall result of the validation (e.g., "deliverable")
reason	The reason for the validation result

Remember to implement appropriate error handling and respect rate limits when retrieving batch results. If the batch job is not yet complete, you may need to poll the endpoint at reasonable intervals until the finished_at field is populated.