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 5. 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."
}