Bulk Validations

This API provides functionality to upload and manage bulk validation lists and previews.

Get Job V4

Gets a selected job by list ID.

SecuritybasicAuth

Request

path Parameters

list_id

required

string

The list ID being verified

header Parameters

X-Mailgun-Account-Id

required

string

Mailgun Account ID

Responses

200

A 200 response

Response Schema: application/json

created_at required	integer <int32>
id required	string
quantity required	integer <int32>
records_processed required	integer <int32>
is_preview	boolean
	object
status	string
	object
reason	string

404

A 404 response

500

A 500 response

get/v4/address/validate/bulk/{list_id}

Request samples

Response samples

200
404
500

application/json

{"quantity": 10000,
"id": "some-job-name",
"summary": {"risk": {"high": 30,
"low": 8000,
"medium": 1010,
"unknown": 460
},
"result": {"donotsend": 30,
"undeliverable": 500,
"unknown": 460,
"catchall": 10,
"deliverable": 9000
}
},
"download_url": {"csv": "https://some-aws-or-gcp-host/file.csv.zip",
"json": "https://some-aws-or-gcp-host/file.json.zip"
},
"status": "uploaded",
"created_at": 160000000
}

Delete Job V4

Cancels a selected job by list ID.

SecuritybasicAuth

Request

path Parameters

list_id

required

string

The list ID being verified

header Parameters

X-Mailgun-Account-Id

required

string

Mailgun Account ID

Responses

200

A 200 response

Response Schema: application/json

property name*

additional property

object

404

A 404 response

409

A 409 response

500

A 500 response

delete/v4/address/validate/bulk/{list_id}

Request samples

Response samples

200
404
409
500

application/json

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

Get Preview Job

A single preview job by ID.

SecuritybasicAuth

Request

path Parameters

list_id

required

string

The preview list id

Responses

200

A 200 response

Response Schema: application/json

id required	string
valid required	boolean
status required	string
quantity required	integer <int32>
created_at required	integer <int64>
- required	integer <int32>
	object
reason	string

default

A default response

get/v4/address/validate/preview/{list_id}

Request samples

Response samples

200
default

application/json

{"valid": true,
"status": "preview_complete",
"summary": {"risk": {"medium": 0,
"high": 0,
"unknown": 0,
"low": 100
},
"result": {"undeliverable": 0,
"unknown": 0,
"do_not_send": 0,
"deliverable": 100
}
},
"id": "SampleList",
"quantity": 1,
"created_at": 1234567890
}

Promote Preview Job

A currently running preview job can be promoted to a full bulkvalidations job, which will validate all addresses in the list.

SecuritybasicAuth

Request

path Parameters

list_id

required

string

The bulk job list id

Responses

202

A 202 response

default

A default response

put/v4/address/validate/preview/{list_id}

Request samples

Response samples

202
default

application/json

{"Status": 202,
"Response": {"id": "example_list_id",
"message": "The bulk preview job was promoted to a bulk validation job."
}
}

Create Preview Job

Start a preview job from a list of addresses. We will sample the list and run validations on a small percentage.

SecuritybasicAuth

Request

path Parameters

list_id

required

string

The bulk job list id

Responses

202

A 202 response

default

A default response

post/v4/address/validate/preview/{list_id}

Request samples

Response samples

202
default

application/json

{"id": "example_list_id",
"message": "The validation preview was submitted."
}

Delete Preview Job

Deletes a single preview job by ID.

SecuritybasicAuth

Request

path Parameters

list_id

required

string

The bulk job list id

Responses

202

A 202 response

default

A default response

delete/v4/address/validate/preview/{list_id}

Request samples

Response samples

202
default

application/json

{"message": "The bulk preview was deleted.",
"id": "example_list_id"
}

List Preview Jobs

All preview jobs you have started.

SecuritybasicAuth

Responses

200

A 200 response

Response Schema: application/json

required

Array of objects

Array

id required	string
valid required	boolean
status required	string
quantity required	integer <int32>
created_at required	integer <int64>
- required	integer <int32>
	object
reason	string

default

A default response

get/v4/address/validate/preview

Request samples

Response samples

200
default

application/json

{"previews": [{"created_at": 1234567890,
"id": "SampleList",
"quantity": 1,
"status": "preview_complete",
"summary": {"result": {"deliverable": 100,
"do_not_send": 0,
"undeliverable": 0,
"unknown": 0
},
"risk": {"high": 0,
"low": 100,
"medium": 0,
"unknown": 0
}
},
"valid": true
}
]
}

List Jobs V4

Returns all jobs.

SecuritybasicAuth

Request

header Parameters

X-Mailgun-Account-Id

required

string

Mailgun Account ID

Responses

200

A 200 response

Response Schema: application/json

created_at required	integer <int32>
id required	string
quantity required	integer <int32>
records_processed required	integer <int32>
is_preview	boolean
	object
status	string
	object
reason	string

404

A 404 response

500

A 500 response

get/v4/address/validate/bulk

Request samples

Response samples

200
404
500

application/json

{"total": 2,
"jobs": [{"created_at": 160000001,
"id": "some-job-name",
"quantity": 10000,
"records_processed": 3202,
"status": "processing"
},
{"created_at": 160000000,
"download_url": {"csv": "https://some-aws-or-gcp-host/file.csv.zip",
"json": "https://some-aws-or-gcp-host/file.json.zip"
},
"id": "some-job-name",
"quantity": 10000,
"status": "uploaded",
"summary": {"engagement": null,
"result": {"catchall": 10,
"deliverable": 9000,
"donotsend": 30,
"undeliverable": 500,
"unknown": 460
},
"risk": {"high": 30,
"low": 8000,
"medium": 1010,
"unknown": 460
}
}
}
],
"paging": {"prev": "http://localhost/v4/address/validate/bulk?limit=10&page=prev&pivot=",
"first": "http://localhost/v4/address/validate/bulk?limit=10&page=first&pivot=",
"last": "http://localhost/v4/address/validate/bulk?limit=10&page=last&pivot=",
"next": "http://localhost/v4/address/validate/bulk?limit=10&page=next&pivot="
}
}

Get Job V3

Gets a selected job by list ID.

SecuritybasicAuth

Request

path Parameters

list_id

required

string

The list ID being verified

header Parameters

X-Mailgun-Account-Id

required

string

Mailgun Account ID

Responses

200

A 200 response

Response Schema: application/json

created_at required	integer <int32>
id required	string
quantity required	integer <int32>
records_processed required	integer <int32>
is_preview	boolean
	object
status	string
	object
reason	string

404

A 404 response

500

A 500 response

get/v3/lists/{list_id}/validate

Request samples

Response samples

200
404
500

application/json

{"created_at": 160000000,
"id": "some-list@ninomail.com",
"download_url": {"csv": "https://some-aws-or-gcp-host/file.csv.zip",
"json": "https://some-aws-or-gcp-host/file.json.zip"
},
"quantity": 10000,
"status": "uploaded",
"summary": {"result": {"catchall": 10,
"deliverable": 9000,
"donotsend": 30,
"undeliverable": 500,
"unknown": 460
},
"risk": {"high": 30,
"low": 8000,
"medium": 1010,
"unknown": 460
}
}
}

Create Job V3

Starts a V3 list validation job.

SecuritybasicAuth

Request

path Parameters

list_id

required

string

The list ID being verified

header Parameters

X-Mailgun-Account-Id

required

string

Mailgun Account ID

Responses

200

A 200 response

Response Schema: application/json

property name*

additional property

object

400

A 400 response

post/v3/lists/{list_id}/validate

Request samples

Response samples

200
400

application/json

{"message": "The validation job was submitted."
}

Delete Job V3

Cancels a selected job by list ID.

SecuritybasicAuth

Request

path Parameters

list_id

required

string

The list ID being verified

header Parameters

X-Mailgun-Account-Id

required

string

Mailgun Account ID

Responses

200

A 200 response

Response Schema: application/json

property name*

additional property

object

404

A 404 response

409

A 409 response

500

A 500 response

delete/v3/lists/{list_id}/validate

Request samples

Response samples

200
404
409
500

application/json

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