Skip to content
Mailgun Inspect/API Documentation/
/
List Spam Tests (V1)

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

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

Code Analysis

The Code Analysis API analyzes HTML email content to detect CSS features and provides comprehensive compatibility reports across major email clients, including support statistics, version-specific compatibility data, and detailed feature breakdowns to ensure optimal email rendering.

Operations

Email Preview

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

Operations

Spam Testing

The Spam Testing API scores inbox placement by submitting email content to seed accounts across major providers, reporting deliverability, spam filter verdicts, and authentication results to help maximize inbox reach.

Operations

List Spam Tests (V1)

Request

Returns a paginated list of all spam tests for the account, ordered by created_at desc. Supports filtering by status and region.

Security
basicAuth
Query
statusstring

Filter by spam test lifecycle status

Enum ValueDescription
pending

Test created.

processing

Test accepted; seeds still delivering

completed

Results fully mapped and persisted

failed

Unrecoverable error during test execution

regionstring

Filter by sending region

Enum ValueDescription
us1

United States region

eu1

European Union region

sort_bystring

Field to sort by

Enum ValueDescription
created_at

Sort by creation time (default)

updated_at

Sort by last update time

sort_orderstring

Sort direction

Enum ValueDescription
desc

Descending (default)

asc

Ascending

limitintegerrequired

Limits the number of items returned in a request

curl -i -X GET \
  -u <username>:<password> \
  'https://api.mailgun.net/v1/inspect/spam?status=pending&region=us1&sort_by=created_at&sort_order=desc&limit=0'

Responses

A 200 response

Bodyapplication/json
metaobject(github.com-mailgun-inspect-internal-spam-ResponseMeta)required
meta.​request_idstringrequired
meta.​timestampstringrequired
meta.​countinteger or null(int32)
paginggithub.com-mailgun-scaffold-httpapi-paging-PagingResponse (object) or null
Any of:
itemsArray of objects(github.com-mailgun-inspect-internal-spam-SpamTestResource)required
items[].​idstringrequired
items[].​statusstringrequired
items[].​subjectstringrequired
items[].​sending_ipstring or null
items[].​regionstringrequired
items[].​resultsgithub.com-mailgun-inspect-internal-spam-SpamTestResults (object) or null
Any of:
items[].​failure_reasonstring or null
items[].​created_atstringrequired
items[].​updated_atstringrequired
linksobject(github.com-mailgun-inspect-internal-spam-ResponseLinks)required
links.​selfstringrequired
Response
application/json
{
  "meta": {},
  "items": [
    { … },
    { … }
  ],
  "links": {}
}

Create Spam Test (V1)

Request

Initiates an inbox placement test with subject and HTML provided directly in the request body. Returns immediately with status=processing; poll GET using the Retry-After interval.

Security
basicAuth
Bodyapplication/jsonrequired
subjectstringrequired
htmlstringrequired
from_namestring or null
sending_ipstring or null
regionstring or null
curl -i -X POST \
  -u <username>:<password> \
  https://api.mailgun.net/v1/inspect/spam \
  -H 'Content-Type: application/json' \
  -d '{
    "subject": "string",
    "html": "string",
    "from_name": "string",
    "sending_ip": "string",
    "region": "string"
  }'

Responses

A 201 response

Bodyapplication/json
metaobject(github.com-mailgun-inspect-internal-spam-ResponseMeta)required
meta.​request_idstringrequired
meta.​timestampstringrequired
meta.​countinteger or null(int32)
itemobject(github.com-mailgun-inspect-internal-spam-SpamTestResource)required
item.​idstringrequired
item.​statusstringrequired
item.​subjectstringrequired
item.​sending_ipstring or null
item.​regionstringrequired
item.​resultsgithub.com-mailgun-inspect-internal-spam-SpamTestResults (object) or null
Any of:
item.​failure_reasonstring or null
item.​created_atstringrequired
item.​updated_atstringrequired
linksobject(github.com-mailgun-inspect-internal-spam-ResponseLinks)required
links.​selfstringrequired
Response
application/json
{
  "meta": {},
  "item": {
    "id": "67a654ba0f53254b9fdca3e2",
    "status": "processing",
    "subject": "Welcome to Mailgun",
    "region": "us1",
    "created_at": "2026-03-11T10:00:00Z",
    "updated_at": "2026-03-11T10:00:05Z"
  },
  "links": {}
}

Get Spam Test (V1)

Request

Returns the current state of a spam test. A Retry-After: 10 header is set when the test is still processing.

Security
basicAuth
Path
spam_test_idstringrequired

ID of the spam test

curl -i -X GET \
  -u <username>:<password> \
  'https://api.mailgun.net/v1/inspect/spam/{spam_test_id}'

Responses

A 200 response

Bodyapplication/json
metaobject(github.com-mailgun-inspect-internal-spam-ResponseMeta)required
meta.​request_idstringrequired
meta.​timestampstringrequired
meta.​countinteger or null(int32)
itemobject(github.com-mailgun-inspect-internal-spam-SpamTestResource)required
item.​idstringrequired
item.​statusstringrequired
item.​subjectstringrequired
item.​sending_ipstring or null
item.​regionstringrequired
item.​resultsgithub.com-mailgun-inspect-internal-spam-SpamTestResults (object) or null
Any of:
item.​failure_reasonstring or null
item.​created_atstringrequired
item.​updated_atstringrequired
linksobject(github.com-mailgun-inspect-internal-spam-ResponseLinks)required
links.​selfstringrequired
Response
application/json
{
  "meta": {},
  "item": {
    "id": "67a654ba0f53254b9fdca3e2",
    "status": "completed",
    "subject": "Welcome to Mailgun",
    "region": "us1",
    "results": { … },
    "created_at": "2026-03-11T10:00:00Z",
    "updated_at": "2026-03-11T10:01:30Z"
  },
  "links": {}
}