Skip to content
Mailgun Inspect
/
API Reference
/
Email Preview
/
List/Search Tests V2

Email Preview API (1.0.0)

Mailgun Email Preview service with RESTful JSON HTTP API for providing email previews.

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

https://api.mailgun.net/

EU Mailgun

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

Email Preview

This API provides functionality to create and manage email preview tests, as well as create shareable links.

Operations

Generate Preview Address

Request

Returns or generates an account's email preview address.

Security
basicAuth
curl -i -X POST \
  -u <username>:<password> \
  https://api.mailgun.net/v1/preview/address

Responses

A 200 response

Bodyapplication/json
preview_addressstringrequired
Response
application/json
{
  "preview_address": "string"
}

List/Search Tests V2

Request

This call returns a list of Email Tests along with metadata about each test. Email Tests are stored for 90 days. When query parameters are provided, only the tests matching the specified criteria will be returned; otherwise, all available tests are returned. The response structure remains identical in both cases.

Security
basicAuth
Query
customer_idstring

Filter tests by the provided customer ID.

fromstring

The starting point of your test date range. Accepts formats like '2025-03-10 17:52:07', Unix timestamp, or 'yesterday'.

tostring

The ending point of your test date range. Accepts formats like '2025-03-10 17:52:07', Unix timestamp, or 'yesterday'.

subjectstring

The "subject" field of returned tests must contain the exact string. This search is case-insensitive.

headersstring

Enterprise users can use this field in a KV array of x-headers submitted with the test. This is an AND match, meaning all headers must be present to return.

resultsinteger

The number of results to return. Must be between 1 and 200. The default value is 50.

pageinteger

The page number. If you submit a number higher than the number of pages in the data, an empty array will be returned. The default value is 1.

curl -i -X GET \
  -u <username>:<password> \
  'https://api.mailgun.net/v2/preview/tests?customer_id=string&from=string&to=string&subject=string&headers=string&results=0&page=0'

Responses

A 200 response

Bodyapplication/jsonArray [
idstring
dateinteger(int32)
typestring
subjectstring
headersobject
]
Response
application/json
[
  {
    "id": "DdbNga1MdL3N7sO19v5MAmpOKIqFrLg9cgpCIgS4othXJ",
    "date": 1739876826,
    "type": "email-test",
    "subject": "subject",
    "headers": {}
  },
  {
    "id": "pDdLWjbj3ZbAnHkTbg3QG27mFyoc62OAH1WJXgmb0uNT4",
    "date": 1739874606,
    "type": "email-test",
    "subject": "",
    "headers": {}
  }
]

Create Email Preview Test V2

Request

This call creates a new email test and submits it to our system for processing.
All requests must contain a subject property and one source property (either html or url). All other properties are optional. In the following table, each property and its default value is shown.
If content-checking variables (such as those for link validation, image validation, or accessibility) are set in the body of the request, the endpoint will run content-checking on the email content.
The response will include an id property that should be used to request the results or trigger further processes on the email content.
For enterprise customers, the response will also include the customer_id and reference_id that were submitted with the test.

Security
basicAuth
Bodyapplication/jsonrequired
subjectstringrequired
htmlstring
mimestring
urlstring
transfer_encodingstring
charsetstring
reference_idstring
customer_idstring
clientsArray of strings
image_blockingboolean
headersobject
spamobject
content_checkingobject(github.com-mailgun-emailpreview-clients-preview-TestRequestContentChecking)
curl -i -X POST \
  -u <username>:<password> \
  https://api.mailgun.net/v2/preview/tests \
  -H 'Content-Type: application/json' \
  -d '{
    "subject": "Example subject",
    "html": "<html>...</html>",
    "transfer_encoding": "base64",
    "charset": "utf-8",
    "customer_id": "1",
    "clients": [
      "client1",
      "client2"
    ],
    "content_checking": {
      "link_validation": true,
      "image_validation": true,
      "accessibility": true
    }
  }'

Responses

A 200 response

Bodyapplication/json
idstring
reference_idstring
customer_idstring
spamobject
warningsArray of objects(github.com-mailgun-emailpreview-clients-preview-Warning)
content_checkingobject(github.com-mailgun-emailpreview-clients-preview-ContentCheckingResult)
Response
application/json
{
  "id": "exampleTestID",
  "customer_id": "1",
  "warnings": [
    { … }
  ],
  "content_checking": {
    "link_validation": { … },
    "image_validation": { … },
    "accessibility": { … }
  }
}

Image Validation

The Image Validation API processes image URLs or uploads to provide comprehensive details such as dimensions, type, file size, and format, reports frame count, animation duration, color depth, and transparency for GIFs, and include image optimization capabilities.

Operations

Accessibility

The Accessibility API evaluates HTML emails against WCAG standards, providing a clear pass/fail assessment to ensure compliance with accessibility guidelines.

Operations