> ## Documentation Index > Fetch the complete documentation index at: https://docs.flashduty.com/llms.txt > Use this file to discover all available pages before exploring further. # 预览邮件转告警效果 > 用未保存的邮件集成配置，按接入的方式处理一封邮件，返回判定结果与生成的事件。 ## 限制说明 | 项目 | 说明 | | - | - | | 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** | | 权限要求 | **协作空间管理**（`on-call`）或 **集成中心查看**（`on-call`）或 **集成中心管理**（`on-call`） | ## 使用说明 * 不会写入任何数据：不创建也不修改集成、告警或事件。 * `integration_id` 只用于带入该集成已存的地址前缀；地址本身不参与处理，因此在新建页面同样可用。 * `settings` 会走保存接口同一套校验：不支持的 `mode`、规则 `type`、`extract_from` 或非法的 `extract_pattern` 会在解析邮件之前就返回 `InvalidParameter`。 * 提供 `eml` 时按邮件文件解析，并受 SMTP 邮件大小上限约束；响应中的 `email` 展示解析器实际读到的内容。 * 配置丢弃该邮件时 `event` 为 `null`；邮件无法解析时 `email` 为 `null`。 * `alwaysTrigger` 模式下每封邮件都是独立告警，`alert_key` 与 `key_source` 返回空。 ## OpenAPI ````yaml /api-reference/on-call.openapi.zh.json post /alert/email/preview openapi: 3.1.0 info: title: Flashduty 开放 API description: >- Flashduty 事件管理平台的公开 HTTP API —— 覆盖故障、通知模板、协作空间、值班排班、监控、RUM、以及平台管理。每次调用都需在 query 中携带 `app_key`，该 key 在 Flashduty 控制台 我的 → APP Key 中创建（也可放在请求头 `Fd-App-Key` 中）。所有响应使用统一结构：成功时为 `{ request_id, data }`，失败时为 `{ request_id, error }`。 version: 1.0.0 servers: - url: https://api.flashcat.cloud description: Flashduty Open API security: - AppKeyAuth: [] tags: - name: On-call/故障管理 description: '' - name: On-call/协作空间 description: '' - name: On-call/告警管理 description: 查询、查看和处理告警，管理卡片视图与告警处理规则。 - name: On-call/集成中心 description: '' - name: On-call/IM 集成 description: IM 集成相关查询，例如查看哪些集成开启了作战室。 - name: On-call/值班排班 description: '' - name: On-call/许可管理 description: '' - name: On-call/日历管理 description: '' - name: On-call/通知模板 description: '' - name: On-call/标签增强 description: 自定义字段、富化规则及数据映射（映射规则、映射数据、映射 API）管理。 - name: On-call/分析看板 description: '' - name: On-call/状态页 description: '' - name: On-call/变更管理 description: '' paths: /alert/email/preview: post: tags: - On-call/集成中心 summary: 预览邮件转告警效果 description: 用未保存的邮件集成配置，按接入的方式处理一封邮件，返回判定结果与生成的事件。 operationId: alert-read-email-preview requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/AlertEmailPreviewRequest' example: integration_id: 6113996590131 settings: mode: triggerOrCloseByRule rules: - type: trigger extract_from: title extract_pattern: ^\[ALERT\]\s*(?P.*)$ filters: - key: title oper: IN vals: - /[ALERT]/ - type: close extract_from: title extract_pattern: ^\[OK\]\s*(?P.*)$ filters: - key: title oper: IN vals: - /[OK]/ default: discard email: subject: '[ALERT] checkout 5xx rate above 2%' body: The checkout service 5xx rate is 3.4% over the last 5 minutes. from: alerts@acme.example.com responses: '200': description: Success content: application/json: schema: allOf: - $ref: '#/components/schemas/SuccessEnvelope' - type: object properties: data: $ref: '#/components/schemas/AlertEmailPreviewResponse' example: request_id: 01HK8XQE3Z7JM2NTFQ5YJ8P9R4 data: result: trigger matched_rule: 0 key_source: checkout 5xx rate above 2% key_fallback: false alert_key: 8f14e45fceea167a5a36dedd4bea2543 event: title: '[ALERT] checkout 5xx rate above 2%' description: >- The checkout service 5xx rate is 3.4% over the last 5 minutes. event_status: Critical event_severity: Critical labels: from: alerts@acme.example.com subject: '[ALERT] checkout 5xx rate above 2%' email: subject: '[ALERT] checkout 5xx rate above 2%' from: alerts@acme.example.com body: >- The checkout service 5xx rate is 3.4% over the last 5 minutes. body_text: >- The checkout service 5xx rate is 3.4% over the last 5 minutes. '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '429': $ref: '#/components/responses/TooManyRequests' '500': $ref: '#/components/responses/ServerError' components: schemas: AlertEmailPreviewRequest: type: object description: '`POST /alert/email/preview` 的请求体。' required: - settings - email properties: integration_id: type: integer format: int64 description: 提供初始配置的邮件集成 ID。传 `0` 或不传等价于控制台在新建页面、集成尚不存在时的场景。 settings: $ref: '#/components/schemas/AlertEmailPreviewSettings' description: 要预览的配置，按保存接口的规则校验。 email: $ref: '#/components/schemas/AlertEmailPreviewEmail' description: 要转换的邮件。 SuccessEnvelope: type: object description: >- 成功响应结构。2xx 响应中 `request_id` 标识本次调用（同时出现在 `Flashcat-Request-Id` 响应头中），`data` 为接口业务 payload。失败响应使用不同结构，参见 `ErrorResponse`。 properties: request_id: type: string description: 本次请求的唯一 ID，也会在 Flashcat-Request-Id 响应头中返回。反馈问题时请一并附上。 example: 01HK8XQE3Z7JM2NTFQ5YJ8P9R4 data: description: 接口返回的数据，格式见各接口的 200 响应。没有返回数据的接口会返回 `{}` 或完全不带 `data`。 required: - request_id AlertEmailPreviewResponse: type: object description: 配置对这封邮件的判定，以及转换实际读到的内容。 required: - result - matched_rule - key_source - key_fallback - alert_key - event - email properties: result: type: string enum: - trigger - close - discard description: 配置对这封邮件的判定：`trigger`（触发事件）、`close`（恢复事件）、`discard`（丢弃）。 matched_rule: type: - integer - 'null' description: >- 命中的规则下标，从 0 开始；没有规则命中时为 `null`，`alwaysTrigger` 与 `triggerByTitle` 模式下始终为 `null`。 key_source: type: string description: 告警键的哈希来源。`alwaysTrigger` 模式下每封邮件各自成为告警，或被丢弃时为空。 key_fallback: type: boolean description: 规则的正则没有捕获到内容、改用邮件主题作为键来源时为 `true`。 alert_key: type: string description: '`key_source` 的哈希值。`alwaysTrigger` 模式下每封邮件使用随机键，此字段为空。' event: oneOf: - $ref: '#/components/schemas/AlertEmailPreviewEvent' - type: 'null' description: 这封邮件产生的事件；邮件被丢弃时为 `null`。 email: oneOf: - $ref: '#/components/schemas/AlertEmailPreviewParsed' - type: 'null' description: 转换实际读到的邮件内容；无法解析邮件时为 `null`。 AlertEmailPreviewSettings: type: object description: 要预览的邮件集成配置，与保存接口接受的形状一致。 properties: mode: type: string enum: - alwaysTrigger - triggerByTitle - triggerOrCloseByRule description: >- 集成判定一封邮件归属的方式；省略时默认 `alwaysTrigger`。 - `alwaysTrigger`：每封邮件都是独立告警，键随机生成。 - `triggerByTitle`：每封邮件都是触发事件，告警键由邮件主题哈希得到。 - `triggerOrCloseByRule`：由 `rules` 决定邮件是触发、关闭还是丢弃，未命中的由 `default` 处理。 rules: type: array maxItems: 50 items: $ref: '#/components/schemas/AlertEmailRule' description: '`mode` 为 `triggerOrCloseByRule` 时按顺序匹配的规则，每条都必须是非空对象，最多 50 条。' default: type: string enum: - trigger - discard description: >- `mode` 为 `triggerOrCloseByRule` 且没有规则命中时的处理方式：`trigger` 转为触发事件，`discard` 丢弃。 AlertEmailPreviewEmail: type: object description: 要预览的邮件内容。 properties: subject: type: string description: 邮件主题。 body: type: string description: 邮件正文：以 `<` 开头按 HTML 处理，否则按纯文本处理。 from: type: string description: 发件人地址。 eml: type: string description: >- 整封邮件文件（`.eml`）的 base64 内容。提供后它会替代 `subject`、`body` 和 `from`，并按 SMTP 服务端的解析方式解析。 AlertEmailPreviewEvent: type: object description: 这封邮件会产生的告警事件。 required: - title - description - event_status - event_severity - labels properties: title: type: string description: 事件标题。 description: type: string description: 事件描述。 event_status: type: string enum: - Critical - Warning - Info - Ok description: 这封邮件产生的事件状态。 event_severity: type: string enum: - Critical - Warning - Info description: 触发事件的严重级别；恢复事件为空。 labels: type: object additionalProperties: type: string description: 从邮件中提取的标签：正文、发件人、收件人和主题都会以标签形式暴露。 AlertEmailPreviewParsed: type: object description: 转换时实际读到的邮件内容。 required: - subject - from - body - body_text properties: subject: type: string description: 解析后的邮件主题。 from: type: string description: 从邮件中取到的发件人地址。 body: type: string description: 转换使用的正文：存在 HTML 部分时用它，否则用纯文本部分。 body_text: type: string description: 纯文本正文；从描述中提取告警键时优先在这里搜索。 ErrorResponse: type: object description: 错误响应结构。`error` 必填，`data` 不存在。 properties: request_id: type: string example: 01HK8XQE3Z7JM2NTFQ5YJ8P9R4 description: 本次请求的唯一追踪 ID（trace ID），反馈问题时请提供该值以便检索日志。 error: $ref: '#/components/schemas/DutyError' required: - request_id - error AlertEmailRule: type: object description: 匹配一封邮件并从中提取告警键的规则。 required: - type - extract_from - extract_pattern - filters properties: type: type: string enum: - trigger - close description: '`trigger` 表示命中的邮件转为触发事件，`close` 转为恢复事件。' extract_from: type: string enum: - title - description description: >- 告警键从邮件的哪一部分提取：`title` 或 `description`。取 `description` 时依次搜索正文纯文本、带表格的正文、描述。 extract_pattern: type: string description: 提取告警键的正则表达式，捕获到的分组用 `,` 拼接为键来源；没有捕获到任何内容时回退为邮件主题。 filters: type: array items: $ref: '#/components/schemas/FilterCondition' description: 邮件必须全部满足的条件；传 `[]` 表示匹配所有邮件。 DutyError: type: object description: 响应结构中的错误 payload，仅在非 2xx 响应时出现。 properties: code: $ref: '#/components/schemas/ErrorCode' message: type: string description: >- 按响应语言（query 参数 `locale` / `lang` 或请求头 `Accept-Language`）返回的错误描述，可能包含出错的字段名，请不要解析它。 example: The specified parameter template_id is not valid. required: - code - message FilterCondition: type: object required: - key - oper - vals properties: key: type: string description: >- 要匹配的字段。可用的内置字段取决于策略类型，见承载条件的字段说明；任意 `labels.`（如 `labels.env`）始终可用。未知字段返回 `InvalidParameter`。告警或故障缺少该字段时，`IN` 不匹配，`NOTIN` 匹配。 oper: type: string enum: - IN - NOTIN description: 匹配操作符，区分大小写。`IN`：字段值匹配 `vals` 中任意一项即命中；`NOTIN`：与 `vals` 中所有项都不匹配才命中。 vals: type: array items: type: string description: >- 要比较的值，至少一项。每项的匹配方式：普通字符串精确匹配；含 `*` 或 `?` 时按通配符匹配整个值；用斜杠包裹时按正则表达式匹配，如 `/^db-/`（可匹配值的任意位置）；`cidr:<网段>` 匹配 IP 范围，如 `cidr:203.0.113.0/24`；`num::<数字>` 做数值比较，`op` 为 `lt`、`le`、`gt`、`ge`，如 `num:gt:90`。 ErrorCode: type: string description: >- 错误码。所有失败响应都会把 `error.code` 设为下列稳定字符串之一，请以它而不是 HTTP 状态码做判断。 | 错误码 | HTTP | 含义 | |---|---|---| | `OK` | 200 | 保留值，失败的请求不会返回。 | | `InvalidParameter` | 400 | 参数缺失、类型错误或未通过校验，`message` 通常会指出字段名。 | | `BadRequest` | 400 | 请求违反业务规则或与对象当前状态冲突，`message` 会说明原因。 | | `InvalidContentType` | 400 | 请求体没有以 `application/json` 发送。 | | `ResourceNotFound` | 400 | 引用的对象在本账户中不存在或已删除。注意 HTTP 状态码是 400 而不是 404。 | | `NoLicense` | 400 | 账户套餐不包含该功能、套餐配额已用完、套餐已过期或额度不足。 | | `ReferenceExist` | 400 | 对象仍被其他对象引用，无法删除。 | | `Unauthorized` | 401 | APP Key 缺失、无效或已删除。 | | `BalanceNotEnough` | 402 | 仅用于控制台计费流程，Open API 接口不会返回。 | | `AccessDenied` | 403 | APP Key 的权限范围或创建者角色不允许该操作或该对象。 | | `RouteNotFound` | 404 | 没有与该 HTTP 方法和路径匹配的接口。 | | `MethodNotAllowed` | 405 | 路径存在，但不支持该 HTTP 方法。 | | `UndonedOrderExist` | 409 | 仅用于控制台计费流程，Open API 接口不会返回。 | | `EntityTooLarge` | 413 | 请求体超出大小限制。 | | `RequestLocked` | 423 | 仅用于控制台登录保护，Open API 接口不会返回。 | | `RequestVerifyRequired` | 428 | 仅用于控制台验证码流程，Open API 接口不会返回。 | | `DangerousOperation` | 428 | 仅用于控制台高风险操作的 MFA 校验，Open API 接口不会返回。 | | `RequestTooFrequently` | 429 | 触发频率限制；请等待响应头 `Flashcat-Request-Rate-Limit-Delay` 给出的秒数后再重试。 | | `InternalError` | 500 | 服务端意外错误；请退避后重试，反馈问题时附上 `request_id`。 | | `ServiceUnavailable` | 503 | 后端依赖过载或不可用，请退避后重试。 | enum: - OK - InvalidParameter - BadRequest - InvalidContentType - ResourceNotFound - NoLicense - ReferenceExist - Unauthorized - BalanceNotEnough - AccessDenied - RouteNotFound - MethodNotAllowed - UndonedOrderExist - EntityTooLarge - RequestLocked - RequestVerifyRequired - DangerousOperation - RequestTooFrequently - InternalError - ServiceUnavailable x-enumDescriptions: OK: 保留值，失败的请求不会返回。 InvalidParameter: 参数缺失、类型错误或未通过校验，`message` 通常会指出字段名。 BadRequest: 请求违反业务规则或与对象当前状态冲突，`message` 会说明原因。 InvalidContentType: 请求体没有以 `application/json` 发送。 ResourceNotFound: 引用的对象在本账户中不存在或已删除。注意 HTTP 状态码是 400 而不是 404。 NoLicense: 账户套餐不包含该功能、套餐配额已用完、套餐已过期或额度不足。 ReferenceExist: 对象仍被其他对象引用，无法删除。 Unauthorized: APP Key 缺失、无效或已删除。 BalanceNotEnough: 仅用于控制台计费流程，Open API 接口不会返回。 AccessDenied: APP Key 的权限范围或创建者角色不允许该操作或该对象。 RouteNotFound: 没有与该 HTTP 方法和路径匹配的接口。 MethodNotAllowed: 路径存在，但不支持该 HTTP 方法。 UndonedOrderExist: 仅用于控制台计费流程，Open API 接口不会返回。 EntityTooLarge: 请求体超出大小限制。 RequestLocked: 仅用于控制台登录保护，Open API 接口不会返回。 RequestVerifyRequired: 仅用于控制台验证码流程，Open API 接口不会返回。 DangerousOperation: 仅用于控制台高风险操作的 MFA 校验，Open API 接口不会返回。 RequestTooFrequently: 触发频率限制；请等待响应头 `Flashcat-Request-Rate-Limit-Delay` 给出的秒数后再重试。 InternalError: 服务端意外错误；请退避后重试，反馈问题时附上 `request_id`。 ServiceUnavailable: 后端依赖过载或不可用，请退避后重试。 example: InvalidParameter responses: BadRequest: description: 请求非法 — 通常是参数缺失或格式不正确。 content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: missingParameter: value: request_id: 01HK8XQE3Z7JM2NTFQ5YJ8P9R4 error: code: InvalidParameter message: The specified parameter is not valid. Unauthorized: description: app_key 缺失或无效。 content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: missingAppKey: value: request_id: 01HK8XQE3Z7JM2NTFQ5YJ8P9R4 error: code: Unauthorized message: You are unauthorized. Forbidden: description: app_key 有效，但其权限范围或创建者角色不允许该操作或该对象。 content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: noEditPermission: value: request_id: 01HK8XQE3Z7JM2NTFQ5YJ8P9R4 error: code: AccessDenied message: Access Denied. TooManyRequests: description: 触发频率限制。请等待响应头 `Flashcat-Request-Rate-Limit-Delay` 给出的秒数后重试。 content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: rateLimited: value: request_id: 01HK8XQE3Z7JM2NTFQ5YJ8P9R4 error: code: RequestTooFrequently message: Request too frequently. headers: Flashcat-Request-Rate-Limit-Delay: description: 距当前限流窗口重置的秒数。请求被网关全局保护限流拒绝时不返回该响应头。 schema: type: integer minimum: 0 ServerError: description: 服务端未预期错误。反馈问题时请携带 request_id。 content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: internal: value: request_id: 01HK8XQE3Z7JM2NTFQ5YJ8P9R4 error: code: InternalError message: >- We encountered an internal error, and it has been reported. Please try again later. securitySchemes: AppKeyAuth: type: apiKey in: query name: app_key description: >- 在 Flashduty 控制台 我的 → APP Key 中创建的 APP Key。可通过 query 参数 `app_key` 或请求头 `Fd-App-Key` 传入。实际可访问范围是该 APP Key 的权限范围与创建者当前角色权限的交集，请妥善保管。 ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.