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/json

Array [

idstring

dateinteger, (int32)

typestring

subjectstring

headersobject

]

Response

[
  {
    "id": "DdbNga1MdL3N7sO19v5MAmpOKIqFrLg9cgpCIgS4othXJ",
    "date": 1739876826,
    "type": "email-test",
    "subject": "subject",
    "headers": {}
  },
  {
    "id": "pDdLWjbj3ZbAnHkTbg3QG27mFyoc62OAH1WJXgmb0uNT4",
    "date": 1739874606,
    "type": "email-test",
    "subject": "",
    "headers": {}
  }
]