Bulk Validation

Note:

Note Bulk Validation allows for the validation of a list of email addresses. Given a list name and an uploaded file of email addresses, a backend processing job will be run to verify the list. Once the validations have all been completed, the results will be provided with download links.

Note:

Note It’s important to upload as multi-part/form-data where the file is defined by file. Currently only raw csv and gzip are supported. While there is no limit on the number of email addresses that can be provided, the file size cannot exceed 25MB. The column header for emails needs to be either email or email_address

Warning!

Warning Lists must comply to either UTF-8 or ASCII encoding and not have a ‘@’ in the name.

Copy
Copied
GET /v4/address/validate/bulk

Get list of all bulk validation jobs.

Copy
Copied
POST /v4/address/validate/bulk/<list_id>

Create a bulk validation job. The list_id is an arbitrary unique identifier provided by the API caller.

Please note that the max number of validation jobs that can be processed in parallel is 10. If this number is exceeded, a 400 response will be returned.

Copy
Copied
GET /v4/address/validate/bulk/<list_id>

Check the current status of a bulk validation job.

Copy
Copied
DELETE /v4/address/validate/bulk/<list_id>

This endpoint can be used to cancel an in-progress bulk validation job or delete results for a completed bulk validation job. When this endpoint is called for an “uploaded” job, associated result files will be deleted and the job’s status will be set to “deleted”.

Get the status of a bulk validation job:

Copy
Copied
curl -s --user 'api:YOUR_API_KEY' -G \
    https://api.mailgun.net/v4/address/validate/bulk/LIST_NAME

Sample Response:

Copy
Copied
{
  "created_at": "Tue, 26 Feb 2019 21:30:03 GMT",
  "download_url": {
    "csv": "<download_link>",
    "json": "<download_link>"
  },
  "id": "bulk_validations_sandbox_mailgun_org",
  "quantity": 207665,
  "records_processed": 207665,
  "status": "uploaded",
  "summary": {
    "result": {
      "deliverable": 181854,
      "do_not_send": 5647,
      "undeliverable": 12116,
      "catch_all" : 2345,
      "unknown": 5613
    },
    "risk": {
      "high": 17763,
      "low": 142547,
      "medium": 41652,
      "unknown": 5613
    }
  }
}

Field Explanation:

Parameter Type Description
created_at string Date/Time that the request was initiated
download_url array csv and json representation of the download link for the results of the bulk validation
id string list_id name given when the list was initially created}
quantity integer number of total items in the list to be verified
records_processed integer de-duplicated total of verified email addresses
status string current state of the list validation request. (created, processing, completed, uploading, uploaded, and failed)
summary collection summary of the validations in the list provided
result array nested results count. (catchall, deliverable, donot_send, undeliverable, and unknown)
risk array nested risk assessment count (high, low, medium or unknown)

Get a list of bulk validation jobs: This request will return a list of validation jobs in descending order by time created.

Copy
Copied
curl -s --user 'api:YOUR_API_KEY' -G \
    https://api.mailgun.net/v4/address/validate/bulk
Parameter Type Description
limit integer Number of entries to return. Default: 500.

Sample Response:

Copy
Copied
    {
        "jobs":[
        {
            "created_at": "Tue, 26 Feb 2019 21:30:03 GMT",
            "download_url": {
                "csv": "<download_link>",
                "json": "<download_link>"
            }
            "id": "bulk_validations_sandbox2_mailgun_org",
            "quantity": 207665,
            "records_processed": 207665,
            "status": "uploaded",
            "summary": {
                "result": {
                    "deliverable": 181854,
                    "do_not_send": 5647,
                    "undeliverable": 12116,
                    "catch_all" : 2345,
                    "unknown": 5613},
                "risk": {
                    "high": 17763,
                    "low": 142547,
                    "medium": 41652,
                    "unknown": 5613}
            }
        },
        {
            "created_at": "Tue, 23 Feb 2019 21:30:03 GMT",
            "download_url": {
                "csv": "<download_link>",
                "json": "<download_link>"
            }
            "id": "bulk_validations_sandbox_mailgun_org",
            "quantity": 207,
            "records_processed": 207,
            "status": "uploaded",
            "summary": {
                "result": {
                    "deliverable": 181854,
                    "do_not_send": 5647,
                    "undeliverable": 12116,
                    "catch_all" : 2345,
                    "unknown": 5613},
                "risk": {
                    "high": 17763,
                    "low": 142547,
                    "medium": 41652,
                    "unknown": 5613}
            }
        }],
    "total":3,
    "paging": {
      "next":
          "https://url_to_next_page",
      "previous":
          "https://url_to_previous_page",
      "first":
          "https://url_to_first_page",
      "last":
          "https://url_to_last_page"
    },
}

Results Fields Explanation:

Field Description
Deliverable The collection of validation jobs requested for.
Undeliverable The total number of validation jobs.
Do Not Send A collection of pagination links for traversing the validation jobs.
Catch All The total number of domain associated with result is considered a catch_all domain

Create a bulk validation job:

Copy
Copied
curl -s --user 'api:YOUR_API_KEY' \
    https://api.mailgun.net/v4/address/validate/bulk/LIST_NAME \
    -F 'file=@/path/to/file' \

Sample Response:

Copy
Copied
{
 "id": "myemails",
 "message": "The validation job was submitted."
}

Cancel a bulk validation job:

Copy
Copied
curl -s --user 'api:YOUR_API_KEY' -X DELETE \
    https://api.mailgun.net/v4/address/validate/bulk/LIST_NAME

Sample Response:

Copy
Copied
{
 "message": "Validation job canceled."
}