sinch-mailgun-inspect

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

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.

Mailgun Inspect（由Sinch提供）是一款邮件发送前的质量控制API。具备五项功能：

功能	基础路径	输入参数
可访问性检测	`/v1/inspect/accessibility`	`html` + `encoded`
链接验证	`/v1/inspect/links`	`links` URL数组（或使用 `/html-validate` 处理HTML）
图片验证	`/v1/inspect/images`	`links` URL数组（或使用 `/html-validate` / `/upload` ）
代码分析	`/v1/inspect/analyze`	`html` （无需 `encoded` 字段）
邮件预览	`/v1/preview/tests` （V1） / `/v2/preview/tests` （V2）	参数不固定

完整的端点表格和请求模式，请查看references/api-endpoints.md。

Agent Instructions

Agent操作说明

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.

确定检测范围：如果用户说“检查我的邮件”或“QC”，则并行运行所有四项基于HTML的测试。如果用户指定了具体功能（例如“检查链接”），则仅运行该功能对应的测试。
选择输入方式：询问用户是否有原始HTML、URL列表或图片文件，根据功能表格将请求路由到正确的端点。
必须轮询结果：测试创建的POST端点通常是异步的；需轮询GET端点，直到状态变为
```
"Complete"
```
或
```
"Completed"
```
；将
```
"Failed"
```
视为终端错误。
选择区域：如果用户未说明，询问使用哪个区域（美国/欧盟），必须与用户的Mailgun账户区域一致。
V2预览快捷方式：通过在请求体中添加内容检查字段，
```
POST /v2/preview/tests
```
可在单次调用中触发可访问性检测、链接验证、图片验证和代码分析。当用户同时需要预览和质量检查时使用此方式。

Getting Started

快速开始

Authentication

身份验证

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

api

, password = Mailgun Private API key.

请查看sinch-authentication技能。采用HTTP基础认证——用户名

api

，密码为Mailgun私有API密钥。

Base URLs

基础URL

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

区域	端点
美国	`api.mailgun.net`
欧盟	`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.

创建测试的POST响应可能根据端点或工作负载返回

"status": "Processing"

或

"Completed"

。你必须轮询GET端点，直到状态变为

"Complete"

或

"Completed"

（将

"Failed"

视为终端错误）才能获取实际结果。

Canonical Example: Accessibility Test

标准示例：可访问性测试

bash

undefined

bash

undefined

1. Create test (returns 201 + test ID)

1. 创建测试（返回201状态码 + 测试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)

2. 轮询获取结果（重复调用直到状态为"Complete"或"Completed"；"Failed"表示错误）

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.

curl --user 'api:YOUR_API_KEY'
https://api.mailgun.net/v1/inspect/accessibility/TEST_ID


所有其他端点均遵循相同的“创建-轮询”模式。根据上述功能表格调整路径和请求体。

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
```
).

每个功能接受不同的输入类型，请选择合适的方式：

拥有原始HTML？ 直接使用
```
html
```
字段。对于可访问性检测，设置
```
encoded: false
```
。对于链接/图片检测，使用
```
/html-validate
```
子端点。对于代码分析，向
```
/v1/inspect/analyze
```
发送POST请求。
拥有URL列表？ 链接和图片检测接受
```
links
```
URL数组——无需HTML。
拥有图片文件？ 使用
```
/v1/inspect/images/upload
```
。
使用base64编码？ 仅可访问性检测支持
```
encoded: true
```
。代码分析不使用
```
encoded
```
布尔值；请使用支持的请求字段（
```
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

以下路径常被混淆：

代码分析的端点是
```
/v1/inspect/analyze
```
——而非
```
/v1/inspect/code
```

邮件预览的端点是

/v1/preview/tests

和

/v2/preview/tests

——而非

/v1/inspect/preview

链接/图片的HTML输入需使用
```
/html-validate
```
子端点——基础POST端点仅接受URL数组

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.

POST请求返回

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

GET轮询直到状态变为
```
"Complete"
```
或
```
"Completed"
```
（将
```
"Failed"
```
视为终端错误）
DELETE测试完成后清理资源

可访问性检测的POST请求返回201状态码。所有其他POST请求返回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.

如需全面的邮件质量检查，并行触发所有四项基于HTML的测试，然后分别轮询结果：

POST /v1/inspect/accessibility

——请求体：

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

POST /v1/inspect/links/html-validate

——请求体：

{"html": "..."}

POST /v1/inspect/images/html-validate

——请求体：

{"html": "..."}

```
POST /v1/inspect/analyze
```
——请求体：
```
{"html": "..."}
```
轮询每个
```
GET /v1/inspect/{category}/{test_id}
```
直到完成

V2快捷方式：如果同时生成邮件预览，通过在请求体中包含内容检查字段，

POST /v2/preview/tests

可在单次调用中触发所有四项内容检测。详情请查看references/api-endpoints.md § Email Previews。

CI/CD Gate

CI/CD门禁

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.

创建测试、轮询直到完成、解析结果、若存在严重问题则终止构建。上述标准示例展示了“创建-轮询”模式。使用

jq

提取状态和结果以实现脚本化处理。

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

验证图片后可进行优化：

```
POST /v1/inspect/images/{id}/optimize
```
——优化测试中的所有图片

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

——优化单张图片

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.

获取代码分析结果时，可按客户端支持情况过滤：

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

参数值：

support_type

= y/a/n/u（是/异常/否/未知），

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).

Content-Type——所有请求使用
```
application/json
```
（不同于Mailgun Send使用的表单数据）。
异步结果——创建测试的响应可能根据端点或工作负载返回
```
"Processing"
```
或
```
"Completed"
```
。在假设结果可用前务必检查状态。
可访问性检测返回201——所有其他创建请求返回200。
输入类型差异——仅可访问性检测使用
```
html
```
+
```
encoded
```
。链接和图片检测接受
```
links
```
URL数组。代码分析接受
```
html
```
但无需
```
encoded
```
。使用错误的请求体将静默失败。
HTML输入使用
/html-validate
——如果拥有HTML（而非URL），链接和图片检测需使用
```
/html-validate
```
子端点。
与Mailgun Send使用相同认证——无需单独凭证。使用相同的API密钥和基础认证。
区域一致性——使用与Mailgun Send账户相同的区域（美国或欧盟）。
分页——列表端点支持
```
limit
```
（最大值1000，默认100）和
```
skip
```
（默认0）参数。

sinch-mailgun-inspect

Original

Translation

Mailgun Inspect

Mailgun Inspect

Overview

概述

Agent Instructions

Agent操作说明

Getting Started

快速开始

Authentication

身份验证

Base URLs

基础URL

Async Workflow -- Critical

异步工作流——关键注意事项

Canonical Example: Accessibility Test

标准示例：可访问性测试

1. Create test (returns 201 + test ID)

1. 创建测试（返回201状态码 + 测试ID）

2. Poll for results (repeat until status is "Complete" or "Completed"; "Failed" = error)

2. 轮询获取结果（重复调用直到状态为"Complete"或"Completed"；"Failed"表示错误）

Key Concepts

核心概念

Choosing the Right Input Method

选择正确的输入方式

Endpoint Path Gotchas

端点路径常见误区

Response Lifecycle

响应生命周期

Common Patterns

常见使用模式

Full Pre-Send Check

完整发送前检查

CI/CD Gate

CI/CD门禁

Image Optimization

图片优化

Code Analysis Filtering

代码分析过滤

Gotchas and Best Practices

常见误区与最佳实践

Links

相关链接