Skip to content

docs(api): drop dry_run from member notify, document html validation 400 #415

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
ysyneu merged 1 commit into from
Sep 21, 2026
Merged

docs(api): drop dry_run from member notify, document html validation 400 #415

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
35 changes: 20 additions & 15 deletions api-reference/openapi.en.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -29251,12 +29251,7 @@
"html": {
"type": "string",
"maxLength": 102400,
"description": "Email body as an HTML fragment (no `<html>`/`<head>`/`<body>` wrapper needed); recipients receive it as the whole email body. Required, up to 102,400 bytes of raw UTF-8 input (larger messages are clipped by common email clients), and must be non-empty after sanitization. Sanitized server-side: `<script>`, `<style>`, `<iframe>`, `<object>`, `<embed>`, `<form>`, `<input>`, `<button>`, `<svg>`, `<meta>`, `<link>`, and `<base>` tags and all `on*` event handlers are removed; images are kept only when their `src` is `https` — images with any other or no `src`, including `data:`, are removed; links are restricted to `http`, `https`, and `mailto`. Inline `style` attributes are kept as written."
},
"dry_run": {
"type": "boolean",
"default": false,
"description": "Check without sending. When `true`, every check runs and the response returns the exact email in `html`, but nothing is queued and neither the hourly limit nor the per-turn duplicate check is consumed. Defaults to `false`."
"description": "Email body as an HTML fragment (no `<html>`/`<head>`/`<body>` wrapper needed); recipients receive it as the whole email body. Required, up to 102,400 bytes of raw UTF-8 input (larger messages are clipped by common email clients), and must be non-empty after sanitization. `<script>`, `<meta>`, `<link>`, and `<base>` tags and all `on*` event handlers are silently removed before sending, since email clients never execute them; inline `style` attributes are kept as written. `<style>`, `<svg>`, `<iframe>`, `<object>`, `<embed>`, `<form>`, `<input>`, and `<button>` tags, an `<img>` with a missing or non-`https` `src` (including `data:`), or an `<a>` whose href scheme is not `http`, `https`, or `mailto` are rejected instead of stripped: the request fails with `400` rather than silently changing what recipients see."
}
}
},
Expand All @@ -29269,15 +29264,11 @@
"items": {
"$ref": "#/components/schemas/MemberNotifyResultItem"
},
"description": "One result per resolved recipient, in the same order as the resolved recipient list. With `dry_run`, each result is what a real send would return."
},
"html": {
"type": "string",
"description": "Only present when `dry_run` is `true`: the complete email HTML exactly as recipients would receive it, after sanitization."
"description": "One result per resolved recipient, in the same order as the resolved recipient list."
},
"agent_instructions": {
"type": "string",
"description": "Present when the submitted HTML body does not follow the default email layout (no `max-width:600px` wrapper table): guidance telling the calling AI SRE agent how to conform. Advisory only — a format the caller deliberately chose needs no change. Returned on dry runs and real sends alike."
"description": "Present when the submitted HTML body does not follow the default email layout (no `max-width:600px` wrapper table): guidance telling the calling AI SRE agent how to conform. Advisory only — a format the caller deliberately chose needs no change."
}
}
},
Expand Down Expand Up @@ -60269,12 +60260,12 @@
"post": {
"operationId": "memberNotify",
"summary": "Notify members",
"description": "Send an email to account members on behalf of the caller, with content the caller supplies. Only callable with a credential minted for an AI SRE session; any other credential is rejected with `AccessDenied`. Delivery is asynchronous — `accepted` means the email was queued, not that it was delivered. Call it with `dry_run` set to `true` before sending: `html` in the response is the email exactly as recipients will get it, so you can confirm the sanitizer kept everything the message depends on.",
"description": "Send an email to account members on behalf of the caller, with content the caller supplies. Only callable with a credential minted for an AI SRE session; any other credential is rejected with `AccessDenied`. Delivery is asynchronous — `accepted` means the email was queued, not that it was delivered.",
"tags": [
"Platform/Members"
],
"x-mint": {
"content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **200 requests/minute**; **10 requests/second** per account |\n| Permissions | None — callable only with an AI SRE session credential; any other credential is rejected with `AccessDenied` |\n\n## Usage\n\n- Recipients that are not active members of the caller's account, or that have no email address on file, are skipped rather than failing the whole request.\n- Whether email is included follows each recipient's own notification preferences for this kind of message; a recipient with no preference set defaults to receiving it.\n- Recipients receive exactly the sanitized `html` as the email body, with nothing added around it. The sender name shows the caller's name followed by \"(via AI SRE)\".\n- Set `dry_run` to `true` to run every check and get the exact email back in `html` without sending: nothing is queued, and neither the hourly limit nor the per-turn duplicate check is consumed.\n- At most 20 emails are delivered to the same recipient through this endpoint per hour; further deliveries to that recipient in the same window are skipped with `rate_limited`.\n- Retrying the same call within the same AI SRE session turn does not send a duplicate email to a recipient who already received one; the repeat is skipped with `duplicate`.",
"content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **200 requests/minute**; **10 requests/second** per account |\n| Permissions | None — callable only with an AI SRE session credential; any other credential is rejected with `AccessDenied` |\n\n## Usage\n\n- Recipients that are not active members of the caller's account, or that have no email address on file, are skipped rather than failing the whole request.\n- Whether email is included follows each recipient's own notification preferences for this kind of message; a recipient with no preference set defaults to receiving it.\n- Recipients receive exactly the sanitized `html` as the email body, with nothing added around it. The sender name shows the caller's name followed by \"(via AI SRE)\".\n- Before sending, the server inspects the submitted `html` and rejects the request with `400` / `InvalidParameter` when it contains constructs whose removal would change what recipients see (`<style>`, `<svg>`, `<iframe>`, `<object>`, `<embed>`, `<form>`, `<input>`, `<button>`, an `<img>` with a missing or non-`https` `src`, or an `<a>` whose href scheme is not `http`, `https`, or `mailto`); the error message names each construct and what to change, and nothing is queued — neither the hourly limit nor the per-turn duplicate check is consumed. Tags whose removal does not change rendering (`<script>`, `<meta>`, `<link>`, `<base>`, `on*` handlers) are still sanitized silently and never trigger a rejection.\n- At most 20 emails are delivered to the same recipient through this endpoint per hour; further deliveries to that recipient in the same window are skipped with `rate_limited`.\n- Retrying the same call within the same AI SRE session turn does not send a duplicate email to a recipient who already received one; the repeat is skipped with `duplicate`.",
"href": "/en/api-reference/platform/members/member-notify",
"metadata": {
"sidebarTitle": "Notify members"
Expand Down Expand Up @@ -60320,7 +60311,21 @@
}
},
"400": {
"$ref": "#/components/responses/BadRequest"
"description": "The submitted `html` contains a construct that the sanitizer would otherwise remove and that would change what recipients see (see the `html` field description for the full list); the request is rejected instead, and nothing is queued.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
},
"example": {
"request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
"error": {
"code": "InvalidParameter",
"message": "email html contains 2 construct(s) the sanitizer removes, which would change what recipients see. Fix and send again: <style> x2 - move these rules into inline style=\"...\" attributes; <img> without an https src x3 - host the image over https, or drop it"
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
Expand Down
35 changes: 20 additions & 15 deletions api-reference/openapi.zh.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -29251,12 +29251,7 @@
"html": {
"type": "string",
"maxLength": 102400,
"description": "邮件正文，HTML 片段（无需 `<html>`/`<head>`/`<body>` 包裹），即收件人看到的完整邮件正文。必填，原始 UTF-8 内容不超过 102,400 字节（更大的正文会被常见邮件客户端截断），且清洗后不能为空。服务端会进行清洗：`<script>`、`<style>`、`<iframe>`、`<object>`、`<embed>`、`<form>`、`<input>`、`<button>`、`<svg>`、`<meta>`、`<link>`、`<base>` 标签及所有 `on*` 事件处理属性会被移除；图片仅在 `src` 为 `https` 时保留，其他来源或没有 `src` 的图片（包括 `data:`）会被移除；链接仅允许 `http`、`https`、`mailto`。内联 `style` 属性按原样保留。"
},
"dry_run": {
"type": "boolean",
"default": false,
"description": "仅检查不发送。为 `true` 时执行全部检查，并在响应的 `html` 中返回将要发送的完整邮件，但不会入队，也不占用每小时限额和同轮次去重。默认 `false`。"
"description": "邮件正文，HTML 片段（无需 `<html>`/`<head>`/`<body>` 包裹），即收件人看到的完整邮件正文。必填，原始 UTF-8 内容不超过 102,400 字节（更大的正文会被常见邮件客户端截断），且清洗后不能为空。`<script>`、`<meta>`、`<link>`、`<base>` 标签及所有 `on*` 事件处理属性会在发送前被静默移除——邮件客户端本就不会执行它们；内联 `style` 属性按原样保留。`<style>`、`<svg>`、`<iframe>`、`<object>`、`<embed>`、`<form>`、`<input>`、`<button>` 标签，`src` 缺失或不是 `https`（包括 `data:`）的 `<img>`，以及 href 不属于 `http`、`https`、`mailto` 的 `<a>`，会被直接拒绝而非静默清洗：请求会返回 `400`，而不是悄悄改变收件人看到的内容。"
}
}
},
Expand All @@ -29269,15 +29264,11 @@
"items": {
"$ref": "#/components/schemas/MemberNotifyResultItem"
},
"description": "每个已解析收件人对应一条结果，顺序与解析后的收件人列表一致。`dry_run` 时为实际发送将得到的结果。"
},
"html": {
"type": "string",
"description": "仅当 `dry_run` 为 `true` 时返回：清洗后、收件人将收到的完整邮件 HTML。"
"description": "每个已解析收件人对应一条结果，顺序与解析后的收件人列表一致。"
},
"agent_instructions": {
"type": "string",
"description": "当提交的 HTML 正文不符合默认邮件版式（缺少 `max-width:600px` 外层包裹表格）时返回：告知调用的 AI SRE agent 如何对齐的指引。仅为建议——调用方有意选择的格式无需改动。dry run 与真实发送均会返回。"
"description": "当提交的 HTML 正文不符合默认邮件版式（缺少 `max-width:600px` 外层包裹表格）时返回：告知调用的 AI SRE agent 如何对齐的指引。仅为建议——调用方有意选择的格式无需改动。"
}
}
},
Expand Down Expand Up @@ -60269,12 +60260,12 @@
"post": {
"operationId": "memberNotify",
"summary": "通知成员",
"description": "以调用方身份向账户成员发送邮件，邮件内容由调用方提供。仅可使用 AI SRE 会话凭据调用；使用其他凭据调用会返回 AccessDenied 错误。邮件投递是异步的——`accepted` 表示邮件已入队，并不代表已送达。发送前先将 `dry_run` 设为 `true` 调用一次：响应中的 `html` 就是收件人将收到的邮件，可据此确认清洗后正文依赖的内容都还在。",
"description": "以调用方身份向账户成员发送邮件，邮件内容由调用方提供。仅可使用 AI SRE 会话凭据调用；使用其他凭据调用会返回 AccessDenied 错误。邮件投递是异步的——`accepted` 表示邮件已入队，并不代表已送达。",
"tags": [
"平台/成员管理"
],
"x-mint": {
"content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ----- |\n| 速率限制 | 每个账户 **200 次/分钟**；**10 次/秒** |\n| 权限要求 | 无——仅可使用 AI SRE 会话凭据调用；使用其他凭据调用会返回 AccessDenied |\n\n## 使用说明\n\n- 不是调用方账户内活跃成员、或没有邮箱地址的收件人会被跳过，不会导致整个请求失败。\n- 是否发送邮件取决于每个收件人针对此类消息的通知偏好设置；未设置偏好的收件人默认会收到邮件。\n- 收件人收到的邮件正文就是清洗后的 `html`，平台不会在其前后添加任何内容；发件人名称显示为调用方姓名加“(via AI SRE)”。\n- 将 `dry_run` 设为 `true` 可执行全部检查并在 `html` 中返回将要发送的完整邮件，但不会发送：不会入队，也不占用每小时限额和同轮次去重。\n- 同一收件人通过该接口每小时最多收到 20 封邮件；超出后同一窗口内该收件人的后续投递会被跳过并返回 `rate_limited`。\n- 在同一个 AI SRE 会话轮次内重复调用，不会向已收到邮件的收件人重复发送；重复的收件人会被跳过并返回 `duplicate`。",
"content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ----- |\n| 速率限制 | 每个账户 **200 次/分钟**；**10 次/秒** |\n| 权限要求 | 无——仅可使用 AI SRE 会话凭据调用；使用其他凭据调用会返回 AccessDenied |\n\n## 使用说明\n\n- 不是调用方账户内活跃成员、或没有邮箱地址的收件人会被跳过，不会导致整个请求失败。\n- 是否发送邮件取决于每个收件人针对此类消息的通知偏好设置；未设置偏好的收件人默认会收到邮件。\n- 收件人收到的邮件正文就是清洗后的 `html`，平台不会在其前后添加任何内容；发件人名称显示为调用方姓名加“(via AI SRE)”。\n- 发送前，服务端会检查提交的 `html`，如果其中包含移除后会改变收件人所见内容的构造（`<style>`、`<svg>`、`<iframe>`、`<object>`、`<embed>`、`<form>`、`<input>`、`<button>`、`src` 缺失或不是 `https` 的 `<img>`，或 href 不属于 `http`/`https`/`mailto` 的 `<a>`），会返回 `400` / `InvalidParameter` 并拒绝请求；错误消息会逐一列出触发的构造及需要如何修改，且不会入队——不占用每小时限额，也不占用同轮次去重。不影响渲染效果的标签（`<script>`、`<meta>`、`<link>`、`<base>`、`on*` 事件属性）仍会被静默清洗，不会触发拒绝。\n- 同一收件人通过该接口每小时最多收到 20 封邮件；超出后同一窗口内该收件人的后续投递会被跳过并返回 `rate_limited`。\n- 在同一个 AI SRE 会话轮次内重复调用，不会向已收到邮件的收件人重复发送；重复的收件人会被跳过并返回 `duplicate`。",
"href": "/zh/api-reference/platform/members/member-notify",
"metadata": {
"sidebarTitle": "通知成员"
Expand Down Expand Up @@ -60320,7 +60311,21 @@
}
},
"400": {
"$ref": "#/components/responses/BadRequest"
"description": "提交的 `html` 中包含移除后会改变收件人所见内容的构造（完整列表见 `html` 字段的描述），请求会被拒绝而不是静默移除，且不会入队。",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
},
"example": {
"request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
"error": {
"code": "InvalidParameter",
"message": "email html contains 2 construct(s) the sanitizer removes, which would change what recipients see. Fix and send again: <style> x2 - move these rules into inline style=\"...\" attributes; <img> without an https src x3 - host the image over https, or drop it"
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
Expand Down
Loading
Loading