Skip to content
Mailgun Validate
/
Mailgun Validate API Reference
/
List Health Preview

Validations Service (1.0.0)

Mailgun Email Validation service with RESTful JSON HTTP API for performing email validation. This service also manages list and CSV ingestion used in bulk validation processing.

Download OpenAPI description
openapi-validate-final.json
openapi-validate-final.yaml
Languages
Servers
US Mailgun

https://api.mailgun.net/

EU Mailgun

https://api.eu.mailgun.net/

Validations

This API provides functionality to validate single addresses, and managing thresholds.

Operations

Bulk Validations

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

Operations

List Health Preview

Operations

Get List Health Preview Job

Request

A single list health preview job by ID.

Security
basicAuth
Path
list_idstringrequired

The list health preview id

curl -i -X GET \
  -u <username>:<password> \
  'https://api.mailgun.net/v4/address/validate/preview/{list_id}'

Responses

A 200 response

Bodyapplication/json
idstringrequired
validbooleanrequired
statusstringrequired
quantityinteger(int32)required
created_atinteger(int64)required
summaryobject
reasonstring
Response
application/json
{
  "id": "SampleList",
  "valid": true,
  "status": "preview_complete",
  "quantity": 1,
  "created_at": 1234567890,
  "summary": {
    "result": { … },
    "risk": { … }
  }
}

Promote List Health Preview Job

Request

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

Security
basicAuth
Path
list_idstringrequired

The list health preview job id

curl -i -X PUT \
  -u <username>:<password> \
  'https://api.mailgun.net/v4/address/validate/preview/{list_id}'

Responses

A 202 response

Bodyapplication/json
idstringrequired
messagestringrequired
Response
application/json
{
  "Response": {
    "id": "example_list_id",
    "message": "The bulk preview job was promoted to a bulk validation job."
  },
  "Status": 202
}

Create a List Health Preview Job

Request

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

Security
basicAuth
Path
list_idstringrequired

The list health preview job id

curl -i -X POST \
  -u <username>:<password> \
  'https://api.mailgun.net/v4/address/validate/preview/{list_id}'

Responses

A 202 response

Bodyapplication/json
idstringrequired
messagestringrequired
Response
application/json
{
  "id": "example_list_id",
  "message": "The validation preview was submitted."
}