> ## 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. # Preview email-to-alert conversion > Run unsaved email integration settings over one email, the way ingestion would. ## Restrictions | Aspect | Value | | - | - | | Rate limits | **1,000 requests/minute**; **50 requests/second** per account | | Permissions | **Channels Manage** (`on-call`) or **Integrations Read** (`on-call`) or **Integrations Manage** (`on-call`) | ## Usage * Nothing is written: no integration, alert or event is created or changed. * `integration_id` seeds the preview with the integration's stored address prefix; the address itself is never used, so the preview works on the create page too. * `settings` passes the same validator the save endpoint runs, so an unsupported `mode`, rule `type`, `extract_from` or an invalid `extract_pattern` fails with `InvalidParameter` before the email is parsed. * When `eml` is set the message is parsed as a mail file, within the SMTP message size limit, and `email` in the response shows what the parser read. * `event` is `null` when the settings discard the email, and `email` is `null` when the message cannot be parsed. * In `alwaysTrigger` mode every email becomes its own alert: `alert_key` and `key_source` come back empty. ## OpenAPI ````yaml /api-reference/on-call.openapi.en.json post /alert/email/preview openapi: 3.1.0 info: title: Flashduty Open API description: >- Public HTTP API for the Flashduty incident management platform — incidents, notification templates, channels, schedules, monitors, RUM, and platform administration. Every operation is authenticated with an `app_key` query parameter created in the Flashduty console under My → APP Key (or sent in the `Fd-App-Key` header). Responses follow a uniform envelope: `{ request_id, data }` on success, `{ request_id, error }` on failure. version: 1.0.0 servers: - url: https://api.flashcat.cloud description: Flashduty Open API security: - AppKeyAuth: [] tags: - name: On-call/Incidents description: '' - name: On-call/Channels description: '' - name: On-call/Alerts description: >- Search, inspect, and act on alerts. Manage card views and alert processing pipelines. - name: On-call/Integrations description: '' - name: On-call/IM integrations description: IM integration queries, such as which integrations have war room enabled. - name: On-call/Schedules description: '' - name: On-call/Licenses description: '' - name: On-call/Calendars description: '' - name: On-call/Notification templates description: '' - name: On-call/Alert enrichment description: Custom fields, enrichment rules, and data mapping (schema, data, API). - name: On-call/Analytics description: '' - name: On-call/Status pages description: '' - name: On-call/Changes description: '' paths: /alert/email/preview: post: tags: - On-call/Integrations summary: Preview email-to-alert conversion description: >- Run unsaved email integration settings over one email, the way ingestion would. 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: Request body of `POST /alert/email/preview`. required: - settings - email properties: integration_id: type: integer format: int64 description: >- Email integration whose saved settings seed the preview. `0` or omitted is what the console sends on the create page, before the integration exists. settings: $ref: '#/components/schemas/AlertEmailPreviewSettings' description: >- Settings to preview. They are validated the way the save endpoint validates them. email: $ref: '#/components/schemas/AlertEmailPreviewEmail' description: The email to convert. SuccessEnvelope: type: object description: >- Success response envelope. On every 2xx response, `request_id` identifies the call (also mirrored in the `Flashcat-Request-Id` header) and `data` holds the endpoint-specific payload. Failure responses use a different shape — see `ErrorResponse`. properties: request_id: type: string description: >- Unique ID for this request. Mirrored in the Flashcat-Request-Id response header. Include it when reporting issues. example: 01HK8XQE3Z7JM2NTFQ5YJ8P9R4 data: description: >- Operation-specific payload, documented in each operation's 200 response. Operations without a payload return `{}` or omit `data` entirely. required: - request_id AlertEmailPreviewResponse: type: object description: How the settings treated the email, plus what the conversion read. required: - result - matched_rule - key_source - key_fallback - alert_key - event - email properties: result: type: string enum: - trigger - close - discard description: >- What the settings make of this email: `trigger` (a firing event), `close` (a recovery event) or `discard` (dropped). matched_rule: type: - integer - 'null' description: >- Zero-based index of the rule that matched. `null` when no rule matched, and always `null` in `alwaysTrigger` and `triggerByTitle` modes. key_source: type: string description: >- What the alert key was hashed from. Empty when every email is its own alert (`alwaysTrigger`) or the email is discarded. key_fallback: type: boolean description: >- `true` when the rule's pattern captured nothing and the subject was used as the key source. alert_key: type: string description: >- Hash of `key_source`. Empty in `alwaysTrigger` mode, where each email gets a random key. event: oneOf: - $ref: '#/components/schemas/AlertEmailPreviewEvent' - type: 'null' description: The event the email produces. `null` when the email is discarded. email: oneOf: - $ref: '#/components/schemas/AlertEmailPreviewParsed' - type: 'null' description: >- What the conversion read from the email. `null` when the email could not be parsed. AlertEmailPreviewSettings: type: object description: >- Email integration settings to preview, in the shape the save endpoint accepts. properties: mode: type: string enum: - alwaysTrigger - triggerByTitle - triggerOrCloseByRule description: >- How the integration decides what an email becomes. Omitted defaults to `alwaysTrigger`. - `alwaysTrigger`: every email becomes its own alert, keyed randomly. - `triggerByTitle`: every email becomes a firing event whose alert key is hashed from the subject. - `triggerOrCloseByRule`: `rules` decide whether an email triggers, closes or is discarded, and `default` handles the rest. rules: type: array maxItems: 50 items: $ref: '#/components/schemas/AlertEmailRule' description: >- Rules tried in order when `mode` is `triggerOrCloseByRule`; each entry must be a non-empty object. At most 50. default: type: string enum: - trigger - discard description: >- What happens to an email that matches no rule when `mode` is `triggerOrCloseByRule`: `trigger` turns it into a firing event, `discard` drops it. AlertEmailPreviewEmail: type: object description: The email to run the preview over. properties: subject: type: string description: Email subject. body: type: string description: 'Email body: HTML when it starts with `<`, otherwise plain text.' from: type: string description: Sender address. eml: type: string description: >- A whole email file (`.eml`) as base64. When set it stands in for `subject`, `body` and `from` and is parsed the way the SMTP server parses mail. AlertEmailPreviewEvent: type: object description: The alert event the email would have produced. required: - title - description - event_status - event_severity - labels properties: title: type: string description: Event title. description: type: string description: Event description. event_status: type: string enum: - Critical - Warning - Info - Ok description: Status of the event this email produces. event_severity: type: string enum: - Critical - Warning - Info description: Severity of a firing event; empty for a recovery. labels: type: object additionalProperties: type: string description: >- Labels taken from the email: the body, sender, recipients and subject are exposed as labels. AlertEmailPreviewParsed: type: object description: The email as the conversion read it. required: - subject - from - body - body_text properties: subject: type: string description: Subject as the parser decoded it. from: type: string description: Sender address taken from the email. body: type: string description: >- Body the conversion used: the HTML part when there is one, otherwise the text part. body_text: type: string description: >- Body as plain text; a key extracted from the description is looked for here first. ErrorResponse: type: object description: Response envelope for errors. `error` is required; `data` is absent. properties: request_id: type: string example: 01HK8XQE3Z7JM2NTFQ5YJ8P9R4 description: >- Unique trace ID of this request; include it when reporting issues so logs can be located. error: $ref: '#/components/schemas/DutyError' required: - request_id - error AlertEmailRule: type: object description: One rule that matches an email and extracts the alert key from it. required: - type - extract_from - extract_pattern - filters properties: type: type: string enum: - trigger - close description: >- `trigger` turns a matching email into a firing event, `close` into a recovery event. extract_from: type: string enum: - title - description description: >- Which part of the email the alert key is extracted from: `title` or `description`. For `description` the body text is searched first, then the body text with tables, then the description. extract_pattern: type: string description: >- Regular expression the key is extracted with; the captured groups are joined by `,` to form the key source. A pattern that captures nothing falls back to the subject. filters: type: array items: $ref: '#/components/schemas/FilterCondition' description: >- AND conditions the email must match for the rule to apply. Send `[]` to match every email. DutyError: type: object description: >- Error payload inside the response envelope. Present only on non-2xx responses. properties: code: $ref: '#/components/schemas/ErrorCode' message: type: string description: >- Human-readable error message in the response language (`locale` / `lang` query parameter or `Accept-Language` header). May name the offending field; do not parse it. example: The specified parameter template_id is not valid. required: - code - message FilterCondition: type: object required: - key - oper - vals properties: key: type: string description: >- Field to match. Which built-in keys are allowed depends on the rule type and is listed on the field that holds the conditions; any `labels.` key (for example `labels.env`) is always accepted. An unknown key returns `InvalidParameter`. When the alert or incident has no value for the key, `IN` does not match and `NOTIN` matches. oper: type: string enum: - IN - NOTIN description: >- Match operator, case-sensitive. `IN`: matches when the field value matches any entry in `vals`. `NOTIN`: matches when it matches none of them. vals: type: array items: type: string description: >- Values to compare, at least one. Each entry is matched as: an exact string; a wildcard pattern when it contains `*` or `?` (must match the whole value); a regular expression when wrapped in slashes, such as `/^db-/` (may match anywhere in the value); an IP range written `cidr:`, such as `cidr:203.0.113.0/24`; or a numeric comparison `num::` with `lt`, `le`, `gt` or `ge`, such as `num:gt:90`. ErrorCode: type: string description: >- Error code. Every failed response sets `error.code` to one of these stable strings; branch on it rather than on the HTTP status. | Code | HTTP | Meaning | |---|---|---| | `OK` | 200 | Reserved; never returned on a failed request. | | `InvalidParameter` | 400 | A parameter is missing, has the wrong type, or failed validation; `message` usually names the field. | | `BadRequest` | 400 | The request breaks a business rule or conflicts with the current state of an object; `message` says which. | | `InvalidContentType` | 400 | The body is not sent as `application/json`. | | `ResourceNotFound` | 400 | The referenced object does not exist in this account or was deleted. Returned as HTTP 400, not 404. | | `NoLicense` | 400 | The account's plan does not include the feature, a plan quota is used up, the plan has expired, or credits are insufficient. | | `ReferenceExist` | 400 | The object is still referenced by other objects, so it cannot be deleted. | | `Unauthorized` | 401 | The APP Key is missing, invalid, or deleted. | | `BalanceNotEnough` | 402 | Console-only (billing); not returned by Open API operations. | | `AccessDenied` | 403 | The APP Key's permission scope or the creator's role does not allow this operation or object. | | `RouteNotFound` | 404 | No operation matches the HTTP method and path. | | `MethodNotAllowed` | 405 | The path exists but not for this HTTP method. | | `UndonedOrderExist` | 409 | Console-only (billing); not returned by Open API operations. | | `EntityTooLarge` | 413 | The request body exceeds the size limit. | | `RequestLocked` | 423 | Console-only (sign-in protection); not returned by Open API operations. | | `RequestVerifyRequired` | 428 | Console-only (verification code); not returned by Open API operations. | | `DangerousOperation` | 428 | Console-only (MFA for high-risk actions); not returned by Open API operations. | | `RequestTooFrequently` | 429 | A rate limit was hit; wait for the `Flashcat-Request-Rate-Limit-Delay` response header (seconds) before retrying. | | `InternalError` | 500 | Unexpected server error; retry with backoff and include `request_id` when reporting. | | `ServiceUnavailable` | 503 | A backend dependency is overloaded or unavailable; retry with backoff. | enum: - OK - InvalidParameter - BadRequest - InvalidContentType - ResourceNotFound - NoLicense - ReferenceExist - Unauthorized - BalanceNotEnough - AccessDenied - RouteNotFound - MethodNotAllowed - UndonedOrderExist - EntityTooLarge - RequestLocked - RequestVerifyRequired - DangerousOperation - RequestTooFrequently - InternalError - ServiceUnavailable x-enumDescriptions: OK: Reserved; never returned on a failed request. InvalidParameter: >- A parameter is missing, has the wrong type, or failed validation; `message` usually names the field. BadRequest: >- The request breaks a business rule or conflicts with the current state of an object; `message` says which. InvalidContentType: The body is not sent as `application/json`. ResourceNotFound: >- The referenced object does not exist in this account or was deleted. Returned as HTTP 400, not 404. NoLicense: >- The account's plan does not include the feature, a plan quota is used up, the plan has expired, or credits are insufficient. ReferenceExist: >- The object is still referenced by other objects, so it cannot be deleted. Unauthorized: The APP Key is missing, invalid, or deleted. BalanceNotEnough: Console-only (billing); not returned by Open API operations. AccessDenied: >- The APP Key's permission scope or the creator's role does not allow this operation or object. RouteNotFound: No operation matches the HTTP method and path. MethodNotAllowed: The path exists but not for this HTTP method. UndonedOrderExist: Console-only (billing); not returned by Open API operations. EntityTooLarge: The request body exceeds the size limit. RequestLocked: >- Console-only (sign-in protection); not returned by Open API operations. RequestVerifyRequired: Console-only (verification code); not returned by Open API operations. DangerousOperation: >- Console-only (MFA for high-risk actions); not returned by Open API operations. RequestTooFrequently: >- A rate limit was hit; wait for the `Flashcat-Request-Rate-Limit-Delay` response header (seconds) before retrying. InternalError: >- Unexpected server error; retry with backoff and include `request_id` when reporting. ServiceUnavailable: A backend dependency is overloaded or unavailable; retry with backoff. example: InvalidParameter responses: BadRequest: description: Invalid request — usually a missing or malformed parameter. 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: Missing or invalid 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: >- The app_key is valid, but its permission scope or the creator's role does not allow this operation or object. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: noEditPermission: value: request_id: 01HK8XQE3Z7JM2NTFQ5YJ8P9R4 error: code: AccessDenied message: Access Denied. TooManyRequests: description: >- Rate limit hit. Wait for the number of seconds in `Flashcat-Request-Rate-Limit-Delay`, then retry. 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: >- Seconds until the current rate-limit window resets. Absent when the request was rejected by the gateway's global protection limit. schema: type: integer minimum: 0 ServerError: description: Unexpected server-side error. Include the request_id when reporting. 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: >- APP Key created in the Flashduty console under My → APP Key. Send it as the `app_key` query parameter or in the `Fd-App-Key` request header. Its effective access is the intersection of the key's permission scope and the creator's current role permissions. Keep it secret. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.