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

# Notify members

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

## Restrictions

| Aspect      | Value                                                                                                        |
| ----------- | ------------------------------------------------------------------------------------------------------------ |
| Rate limits | **200 requests/minute**; **10 requests/second** per account                                                  |
| Permissions | None — callable only with an AI SRE session credential; any other credential is rejected with `AccessDenied` |

## Usage

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


## OpenAPI

````yaml /api-reference/platform.openapi.en.json post /member/notify
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 issued from the Flashduty console under Account → APP Keys.
    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: Platform/Members
    description: ''
  - name: Platform/Teams
    description: ''
  - name: Platform/Roles & permissions
    description: ''
  - name: Platform/Audit logs
    description: Search and retrieve account operation audit logs.
  - name: Platform/Account
    description: Account profile and settings
paths:
  /member/notify:
    post:
      tags:
        - Platform/Members
      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.
      operationId: memberNotify
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MemberNotifyRequest'
            example:
              person_ids:
                - 5068740052131
                - 5068740052132
              subject: Incident 20260914-1 needs your input
              html: <p>Can you confirm the rollback window?</p>
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/SuccessEnvelope'
                  - type: object
                    properties:
                      data:
                        $ref: '#/components/schemas/MemberNotifyResponse'
              example:
                request_id: 01HK8XQE3Z7JM2NTFQ5YJ8P9R4
                data:
                  recipients:
                    - person_id: 5068740052131
                      status: accepted
                    - person_id: 5068740052132
                      status: skipped
                      reason: email_disabled
        '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:
    MemberNotifyRequest:
      type: object
      description: Notify members by email request
      required:
        - subject
        - html
      properties:
        person_ids:
          type: array
          items:
            type: integer
            format: int64
          maxItems: 20
          uniqueItems: true
          description: >-
            Recipient member IDs. Optional, up to 20, no duplicates. Omitted or
            empty sends to the caller only.
        subject:
          type: string
          minLength: 1
          maxLength: 200
          description: >-
            Email subject, used as written. Required, 1–200 characters. Line
            breaks are replaced with a space; leading/trailing whitespace is
            trimmed.
        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`.
    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: Endpoint-specific payload. See each operation's 200 response schema.
      required:
        - request_id
        - data
    MemberNotifyResponse:
      type: object
      description: Notify members by email response
      properties:
        recipients:
          type: array
          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.
    MemberNotifyResultItem:
      type: object
      description: Per-recipient notify result
      required:
        - person_id
        - status
      properties:
        person_id:
          type: integer
          format: int64
          description: Recipient member ID.
        status:
          type: string
          enum:
            - accepted
            - skipped
          description: >-
            Delivery status. `accepted` — the email was queued for asynchronous
            delivery; `skipped` — no email was queued, see `reason`.
        reason:
          type: string
          enum:
            - not_member
            - no_email
            - email_disabled
            - duplicate
            - rate_limited
            - send_failed
          description: >-
            Why the recipient was skipped. Only present when `status` is
            `skipped`. `not_member` — not an active member of the caller's
            account; `no_email` — the member has no email address on file;
            `email_disabled` — the member's notification preferences for this
            kind of message exclude email; `duplicate` — this recipient already
            received a message from the same AI SRE session turn; `rate_limited`
            — this recipient has already been sent 20 emails through this
            endpoint within the last hour; `send_failed` — enqueueing the email
            failed.
    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
    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, localized by the caller's
            Accept-Language. May contain field names, IDs, or other context from
            the failing request.
          example: The specified parameter template_id is not valid.
      required:
        - code
        - message
    ErrorCode:
      type: string
      description: >-
        Flashduty error code enum. Every failed API response sets `error.code`
        to one of these stable wire strings. HTTP status is informational — the
        authoritative signal is the enum value.


        | Code | HTTP | Meaning |

        |---|---|---|

        | `OK` | 200 | Reserved — not returned on real errors. |

        | `InvalidParameter` | 400 | A required parameter is missing or failed
        validation. |

        | `BadRequest` | 400 | Generic 400 used when no more specific code fits.
        |

        | `InvalidContentType` | 400 | The `Content-Type` header is not
        `application/json`. |

        | `ResourceNotFound` | 400 | The referenced resource does not exist.
        Note: returned as HTTP 400, not 404 (historical choice). |

        | `NoLicense` | 400 | The feature is license-gated and no active license
        was found. |

        | `ReferenceExist` | 400 | Deletion blocked — other entities still
        reference this resource. |

        | `Unauthorized` | 401 | `app_key` is missing, invalid, or expired. |

        | `BalanceNotEnough` | 402 | Billing-gated operation with insufficient
        account balance. |

        | `AccessDenied` | 403 | Authenticated but lacking the permission
        required for this operation. |

        | `RouteNotFound` | 404 | The request URL path is not a known route. |

        | `MethodNotAllowed` | 405 | The HTTP method is not allowed on this
        otherwise-known path. |

        | `UndonedOrderExist` | 409 | An outstanding billing order blocks this
        new one. Wait and retry. |

        | `RequestLocked` | 423 | Operation temporarily locked due to repeated
        failures. |

        | `EntityTooLarge` | 413 | Request body exceeds the configured max size.
        |

        | `RequestTooFrequently` | 429 | Rate limit hit — API-global,
        per-account, or per-integration. |

        | `RequestVerifyRequired` | 428 | Second-factor verification required
        but not supplied. |

        | `DangerousOperation` | 428 | High-risk operation requires MFA
        verification. |

        | `InternalError` | 500 | Unhandled server-side error. Include
        `request_id` in the bug report. |

        | `ServiceUnavailable` | 503 | A backend dependency is unavailable. Try
        again later. |
      enum:
        - OK
        - InvalidParameter
        - BadRequest
        - InvalidContentType
        - ResourceNotFound
        - NoLicense
        - ReferenceExist
        - Unauthorized
        - BalanceNotEnough
        - AccessDenied
        - RouteNotFound
        - MethodNotAllowed
        - UndonedOrderExist
        - RequestLocked
        - EntityTooLarge
        - RequestTooFrequently
        - RequestVerifyRequired
        - DangerousOperation
        - InternalError
        - ServiceUnavailable
      x-enumDescriptions:
        OK: Reserved — not returned on real errors.
        InvalidParameter: A required parameter is missing or failed validation.
        BadRequest: Generic 400 used when no more specific code fits.
        InvalidContentType: The `Content-Type` header is not `application/json`.
        ResourceNotFound: >-
          The referenced resource does not exist. Note: returned as HTTP 400,
          not 404 (historical choice).
        NoLicense: The feature is license-gated and no active license was found.
        ReferenceExist: Deletion blocked — other entities still reference this resource.
        Unauthorized: '`app_key` is missing, invalid, or expired.'
        BalanceNotEnough: Billing-gated operation with insufficient account balance.
        AccessDenied: Authenticated but lacking the permission required for this operation.
        RouteNotFound: The request URL path is not a known route.
        MethodNotAllowed: The HTTP method is not allowed on this otherwise-known path.
        UndonedOrderExist: An outstanding billing order blocks this new one. Wait and retry.
        RequestLocked: Operation temporarily locked due to repeated failures.
        EntityTooLarge: Request body exceeds the configured max size.
        RequestTooFrequently: Rate limit hit — API-global, per-account, or per-integration.
        RequestVerifyRequired: Second-factor verification required but not supplied.
        DangerousOperation: High-risk operation requires MFA verification.
        InternalError: Unhandled server-side error. Include `request_id` in the bug report.
        ServiceUnavailable: A backend dependency is unavailable. Try again later.
      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 lacks permission for this operation.
      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. Either the global API limit, a per-account limit, or a
        per-integration limit.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            rateLimited:
              value:
                request_id: 01HK8XQE3Z7JM2NTFQ5YJ8P9R4
                error:
                  code: RequestTooFrequently
                  message: Request too frequently.
    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 issued from the Flashduty console under Account → APP Keys.
        Required on every public API call. Keep it secret — it grants the same
        access as the owning account.

````