> ## Documentation Index
> Fetch the complete documentation index at: https://broker-docs.newyorkcityservers.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Send Cancellation Warning

> Email a client a cancellation warning without cancelling their service.

Send a warning to the service's client email address using your active cancellation-warning template. Requires `admin:full` and a nonblank `warningReason`.

This action sends an email. It does not cancel the service or schedule a cancellation.

## Before sending

The service must belong to your broker and must not be cancelled or terminated. It needs a client email address, and your broker needs an active [Cancellation Warning template](/broker/customization/email-templates).

## Understand the result

HTTP `200` with `request_status: "approved"` means the email send succeeded. The API then attempts to save a request-history entry. If that entry cannot be saved, `request_id` can be `null` even though the email was sent.

<Warning>
  This endpoint does not support `X-Idempotency-Key`. Repeating a call can send another email. Confirm the outcome before retrying a timeout or error.
</Warning>

Sandbox calls return a simulated warning record without sending email or writing request history.

## Endpoint errors

For authentication, permissions, rate limits, and safe retries, see [Errors and Retries](/api/errors-and-retries).

| HTTP status | Code                                                        | What to check                                                              |
| ----------- | ----------------------------------------------------------- | -------------------------------------------------------------------------- |
| `400`       | `invalid_request`, `missing_parameter`, `invalid_parameter` | Send valid JSON, a numeric service number, and a nonblank `warningReason`. |
| `400`       | `invalid_state`                                             | The service is cancelled or terminated.                                    |
| `400`       | `missing_customer_email`                                    | Add the client's email address to the service.                             |
| `400`       | `template_not_found`                                        | Create an active cancellation-warning template.                            |
| `404`       | `not_found`                                                 | Check the service number and broker ownership.                             |
| `500`       | `email_send_error`, `server_error`                          | Check the outcome before repeating the request.                            |


## OpenAPI

````yaml api/openapi.yaml POST /v1/services/{service_number}/cancellation-warning
openapi: 3.1.0
info:
  title: Broker API
  version: 1.0.0
  description: API for broker-scoped service, request, and report operations.
servers:
  - url: https://brokers.newyorkcityservers.com/api
    description: Broker Panel API
security:
  - bearerAuth: []
tags:
  - name: Authentication
  - name: Services
  - name: Requests
  - name: Reports
paths:
  /v1/services/{service_number}/cancellation-warning:
    post:
      tags:
        - Services
      summary: Send Cancellation Warning
      description: >-
        Sends a warning email without cancelling or scheduling cancellation.
        Requires `admin:full`. Repeated live calls can send duplicate emails;
        X-Idempotency-Key is not supported.
      operationId: sendCancellationWarning
      parameters:
        - $ref: '#/components/parameters/ServiceNumber'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - warningReason
              properties:
                warningReason:
                  type: string
                  description: >-
                    Nonblank reason for the warning. Leading and trailing spaces
                    are removed.
                  pattern: \S
            example:
              warningReason: Please contact your broker about the account balance.
      responses:
        '200':
          description: >-
            Warning email sent, or simulated in Sandbox Mode. The
            request-history entry is best-effort.
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/SuccessEnvelope'
                  - type: object
                    required:
                      - data
                    properties:
                      data:
                        $ref: '#/components/schemas/CancellationWarningResult'
              example:
                success: true
                data:
                  request_id: REQ-004219
                  type: cancellation-warning
                  request_status: approved
                  service_number: 971100321
                  warning_reason: Please contact your broker about the account balance.
                  submitted_date: '2026-06-23T12:00:00.000Z'
                  processed_date: '2026-06-23T12:00:00.000Z'
        '400':
          description: >-
            Codes `invalid_request`, `missing_parameter`, `invalid_parameter`,
            `invalid_state`, `missing_customer_email`, or `template_not_found`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          $ref: '#/components/responses/AuthenticationError'
        '403':
          $ref: '#/components/responses/PermissionError'
        '404':
          $ref: '#/components/responses/ServiceNotFound'
        '429':
          $ref: '#/components/responses/RateLimitError'
        '500':
          description: >-
            Email send failed (`email_send_error`) or an internal operation
            failed (`server_error`). Check the outcome before retrying.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  parameters:
    ServiceNumber:
      name: service_number
      in: path
      required: true
      description: Public service number parsed as a base-10 integer.
      schema:
        type: integer
        format: int64
  schemas:
    SuccessEnvelope:
      type: object
      required:
        - success
      properties:
        success:
          type: boolean
          const: true
        message:
          type: string
        pagination:
          $ref: '#/components/schemas/Pagination'
    CancellationWarningResult:
      type: object
      required:
        - request_id
        - type
        - request_status
        - service_number
        - warning_reason
        - submitted_date
        - processed_date
      properties:
        request_id:
          type:
            - string
            - 'null'
          description: >-
            Public request ID, or null if the email was sent but the history
            entry could not be saved.
        type:
          type: string
          const: cancellation-warning
        request_status:
          type: string
          const: approved
        service_number:
          type:
            - integer
            - 'null'
        warning_reason:
          type: string
        submitted_date:
          type: string
          format: date-time
        processed_date:
          type: string
          format: date-time
        mode:
          type: string
          const: test
          description: Present in simulated Sandbox responses only.
        simulated:
          type: boolean
          const: true
          description: Present in simulated Sandbox responses only.
    ErrorResponse:
      type: object
      required:
        - success
        - error
      properties:
        success:
          type: boolean
          const: false
        error:
          $ref: '#/components/schemas/Error'
    Pagination:
      type: object
      required:
        - page
        - perPage
        - total
        - totalPages
      properties:
        page:
          type: integer
          minimum: 1
        perPage:
          type: integer
          minimum: 1
          maximum: 100
        total:
          type: integer
          minimum: 0
        totalPages:
          type: integer
          minimum: 0
    Error:
      type: object
      required:
        - code
        - message
      properties:
        code:
          type: string
        message:
          type: string
        details:
          type: object
          additionalProperties: true
  responses:
    AuthenticationError:
      description: >-
        Code `authentication_failed` for a missing, malformed, invalid,
        inactive, or expired API key.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            success: false
            error:
              code: authentication_failed
              message: Invalid API key
    PermissionError:
      description: >-
        Code `insufficient_permissions` when the request IP is not whitelisted
        or a required scope is missing.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            success: false
            error:
              code: insufficient_permissions
              message: IP address not whitelisted
    ServiceNotFound:
      description: Code `not_found` when no broker-owned service matches.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            success: false
            error:
              code: not_found
              message: Service not found or access denied
    RateLimitError:
      description: Code `rate_limit_exceeded` when the API key exceeds its rate limit.
      headers:
        Retry-After:
          description: Seconds to wait before retrying.
          schema:
            type: integer
            minimum: 1
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            success: false
            error:
              code: rate_limit_exceeded
              message: Rate limit exceeded
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API key
      description: >-
        Send the API key in the Authorization bearer header. Production keys
        begin with `sk_live_`.

````