Mailgun Inspect

Overview

Mailgun Inspect (by Sinch) is an email pre-send quality control API. Five capabilities:

Capability	Base Path	Input
Accessibility	`/v1/inspect/accessibility`	`html` + `encoded`
Link Validation	`/v1/inspect/links`	`links` URL array (or `/html-validate` for HTML)
Image Validation	`/v1/inspect/images`	`links` URL array (or `/html-validate` / `/upload` )
Code Analysis	`/v1/inspect/analyze`	`html` (no `encoded` field)
Email Previews	`/v1/preview/tests` (V1) / `/v2/preview/tests` (V2)	varies

For full endpoint tables and request schemas, see references/api-endpoints.md.

Agent Instructions

Determine scope: If user says "check my email" or "QC" → run all four HTML-based tests in parallel. If they name a specific capability (e.g., "check links") → run only that one.
Choose input method: Ask if they have raw HTML, a list of URLs, or an image file. Route to the correct endpoint per the capability table.
Always poll: Test-creation POST endpoints are typically async; poll GET until status is
```
"Complete"
```
or
```
"Completed"
```
; treat
```
"Failed"
```
as terminal error.
Region: Ask which region (US/EU) if not already known. Must match their Mailgun account.
V2 preview shortcut:
```
POST /v2/preview/tests
```
can trigger accessibility, link validation, image validation, and code analysis in a single call by adding content-checking fields to the body. Use this when the user wants previews + quality checks together.

Getting Started

Authentication

See the sinch-authentication skill. HTTP Basic Auth -- username

api

, password = Mailgun Private API key.

Base URLs

Region	Endpoint
US	`api.mailgun.net`
EU	`api.eu.mailgun.net`

Async Workflow -- Critical

Create responses may return

"status": "Processing"

"Completed"

depending on endpoint/workload. You must poll the GET endpoint until status is

"Complete"

"Completed"

(treat

"Failed"

as terminal error) to get actual results.

Canonical Example: Accessibility Test

bash

# 1. Create test (returns 201 + test ID)
curl --user 'api:YOUR_API_KEY' \
  -X POST https://api.mailgun.net/v1/inspect/accessibility \
  -H "Content-Type: application/json" \
  -d '{"html": "<html><body><h1>Hello</h1><img src=\"logo.png\"></body></html>", "encoded": false}'

# 2. Poll for results (repeat until status is "Complete" or "Completed"; "Failed" = error)
curl --user 'api:YOUR_API_KEY' \
  https://api.mailgun.net/v1/inspect/accessibility/TEST_ID

All other endpoints follow the same create-then-poll pattern. Adapt the path and request body per the capability table above.

Key Concepts

Choosing the Right Input Method

Each capability accepts different input types. Pick the right one:

Have raw HTML? Use the
```
html
```
field directly. For accessibility, set
```
encoded: false
```
. For links/images, use the
```
/html-validate
```
sub-endpoint. For code analysis, POST to
```
/v1/inspect/analyze
```
.
Have a list of URLs? Links and images accept a
```
links
```
array of URLs -- no HTML needed.
Have an image file? Use
```
/v1/inspect/images/upload
```
.
Using base64? Only accessibility supports
```
encoded: true
```
. Code analysis does not use an
```
encoded
```
boolean; use supported request fields (
```
html
```
/
```
url
```
/
```
mime
```
/
```
transfer_encoding
```
/
```
charset
```
).

Endpoint Path Gotchas

These paths are commonly confused:

Code analysis is
```
/v1/inspect/analyze
```
-- NOT
```
/v1/inspect/code
```

Email previews are at

/v1/preview/tests

and

/v2/preview/tests

-- NOT

/v1/inspect/preview

Link/image HTML input uses the
```
/html-validate
```
sub-endpoint -- the base POST takes a URL array

Response Lifecycle

POST returns

{"meta": {"status": "Processing"}, "items": {"id": "abc123", ...}}

GET poll until status is
```
"Complete"
```
or
```
"Completed"
```
(treat
```
"Failed"
```
as terminal error)
DELETE clean up when done

Accessibility POST returns 201. All other POSTs return 200.

Common Patterns

Full Pre-Send Check

For a complete email quality check, fire all four HTML-based tests in parallel, then poll each:

POST /v1/inspect/accessibility

-- body:

{"html": "...", "encoded": false}

POST /v1/inspect/links/html-validate

-- body:

{"html": "..."}

POST /v1/inspect/images/html-validate

-- body:

{"html": "..."}

```
POST /v1/inspect/analyze
```
-- body:
```
{"html": "..."}
```
Poll each
```
GET /v1/inspect/{category}/{test_id}
```
until complete

V2 shortcut: If also generating email previews,

POST /v2/preview/tests

can trigger all four content checks in one call by including content-checking fields in the request body. See references/api-endpoints.md § Email Previews.

CI/CD Gate

Create test, poll until complete, parse results, fail build on critical issues. See the canonical example above for the create-and-poll pattern. Use

jq

to extract status and results for scripting.

Image Optimization

After validating images, optimize them:

```
POST /v1/inspect/images/{id}/optimize
```
-- optimize all images in a test

POST /v1/inspect/images/{id}/optimize/{image_id}

-- optimize a single image

Code Analysis Filtering

Filter results by client support when retrieving code analysis:

GET /v1/inspect/analyze/{id}?support_type=n&application_type=web

Values:

support_type

= y/a/n/u (yes/anomaly/no/unknown),

application_type

= web/mobile/desktop.

Gotchas and Best Practices

Content-Type -- All requests use
```
application/json
```
(not form data like Mailgun Send).
Async results -- Creates may return
```
"Processing"
```
or
```
"Completed"
```
depending on endpoint/workload. Always check the status before assuming results are available.
Accessibility returns 201 -- All other creates return 200.
Input types differ -- Only accessibility uses
```
html
```
+
```
encoded
```
. Links and images take a
```
links
```
URL array. Code analysis takes
```
html
```
without
```
encoded
```
. Using the wrong body silently fails.
/html-validate
for HTML input -- If you have HTML (not URLs), use the
```
/html-validate
```
sub-endpoint for links and images.
Same auth as Mailgun Send -- No separate credentials. Same API key, same Basic Auth.
Region consistency -- Use the same region (US or EU) as your Mailgun Send account.
Pagination -- List endpoints support
```
limit
```
(max 1000, default 100) and
```
skip
```
(default 0).

sinch-mailgun-inspect

NPX Install

Tags

SKILL.md Content

Mailgun Inspect

Overview

Agent Instructions

Getting Started

Authentication

Base URLs

Async Workflow -- Critical

Canonical Example: Accessibility Test

Key Concepts

Choosing the Right Input Method

Endpoint Path Gotchas

Response Lifecycle

Common Patterns

Full Pre-Send Check

CI/CD Gate

Image Optimization

Code Analysis Filtering

Gotchas and Best Practices

Links