Sequenzy Sending Status API

openapi: 3.2.0
info:
  title: Sequenzy Sending Status API
  description: Sequenzy API for managing subscribers, tags, events, sequences, and transactional emails
  version: 1.0.0
servers:
- url: https://api.sequenzy.com/api/v1
  description: Production server
- url: https://api.sequenzy.com/v1
  description: Legacy production server alias
security:
- bearerAuth: []
tags:
- name: Sending Status
paths:
  /sending-status:
    get:
      operationId: getSendingStatus
      summary: Get sending status
      description: Returns whether company-level sending is active, paused, or suspended, the pause reason, the sender-health counts and thresholds behind it, the automated review state, whether sending can be restored without support, and ordered remediation steps. Call this whenever a send or test send fails for a reason that is not a validation error. Enforcement uses all-time totals from a reset watermark rather than a rolling window, so metricsWindow.expiresAt is always null and waiting does not restore sending. Requires the account:read scope.
      tags:
      - Sending Status
      responses:
        '200':
          description: Sending status returned
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SendingStatus'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: API key is missing the account:read scope
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '503':
          $ref: '#/components/responses/TransientDatabaseUnavailable'
  /sending-status/resume:
    post:
      operationId: resumeSending
      summary: Resume paused sending
      description: Restores company-level sending paused by a high permanent-bounce rate, after the cause has been fixed. This is not a bypass - it enforces the same gates as the dashboard and never removes suppressions. For a paused workspace, sending is restored only when selfResume.canSelfResume is true on GET /sending-status, which requires a high_hard_bounce_rate pause, a cleared automated sender-health review, and no admin block. An already-active workspace succeeds as an idempotent no-op with resumed false. On restoration the bounce watermark moves to now and the service attempts to requeue paused campaigns plus due sequence steps. A partial queue handoff still returns the committed active state with recovery guidance in message. Requires the companies:manage scope plus owner or admin access.
      tags:
      - Sending Status
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              required:
              - listSanitizationConfirmed
              properties:
                listSanitizationConfirmed:
                  type: boolean
                  description: Must be true. Confirms the source of the invalid addresses is fixed and permanent bounces remain suppressed. Recorded on the account audit trail.
      responses:
        '200':
          description: Sending resumed, or already active
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/SendingStatus'
                - type: object
                  properties:
                    resumed:
                      type: boolean
                      description: False when sending was already active.
                    message:
                      type: string
                      description: Confirms the outcome, or explains that sending resumed while some parked work still needs support.
        '400':
          description: Confirmation missing, or the pause reason is not self-resumable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Blocked by the automated review, an admin block, or view-only access
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Company not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    SenderHealthThresholdBound:
      type: object
      description: Threshold that applies at this send volume. Either bound may be null when the tier does not use it.
      properties:
        rate:
          type:
          - number
          - 'null'
        count:
          type:
          - integer
          - 'null'
    Error:
      type: object
      properties:
        success:
          type: boolean
          example: false
        error:
          type: string
          example: Error message
        code:
          type: string
          description: Optional stable machine-readable error discriminator when available.
          example: COMPANY_CREATE_REQUIRES_PERSONAL_KEY
        retryable:
          type: boolean
          description: Whether retrying the request can recover from the error.
        issues:
          type: array
          description: Field-level problems with the request, when the endpoint reports them. Up to ten entries; `error` summarizes the first three.
          items:
            $ref: '#/components/schemas/InputIssue'
      required:
      - error
    SenderHealthMetric:
      type: object
      properties:
        count:
          type: integer
        rate:
          type: number
          description: Percentage of the applicable bounceScopedSent, blockScopedSent or complaintScopedSent denominator.
        warnThreshold:
          $ref: '#/components/schemas/SenderHealthThresholdBound'
        pauseThreshold:
          $ref: '#/components/schemas/SenderHealthThresholdBound'
    SendingStatus:
      type: object
      description: Company-level sending state, the sender-health measurements behind it, and the remediation path. Enforcement is not time-windowed, so metricsWindow.expiresAt is always null.
      properties:
        success:
          type: boolean
          example: true
        status:
          type: string
          enum:
          - active
          - paused
          - suspended
          description: Anything other than active blocks every send for this workspace, including test sends.
        pauseReason:
          type:
          - string
          - 'null'
          description: Enforcement message including the measured rate, the threshold it crossed, and the volume it was measured over.
          example: Bounce rate (9.910%) exceeded threshold (5%) for 111 total emails
        pauseReasonKind:
          type:
          - string
          - 'null'
          enum:
          - high_hard_bounce_rate
          - high_soft_bounce_rate
          - high_block_rate
          - high_complaint_rate
          - phishing_guard
          - over_email_limit
          - manual
          - other
          - null
          description: Only high_hard_bounce_rate can be cleared through the resume endpoint. over_email_limit lifts automatically once the account has email allowance again.
        pausedAt:
          type:
          - string
          - 'null'
          format: date-time
        selfResume:
          type: object
          properties:
            canSelfResume:
              type: boolean
              description: Whether POST /sending-status/resume will succeed right now.
            supported:
              type: boolean
              description: Whether this pause reason is self-resumable at all.
            allowedByAdmin:
              type: boolean
            ownerIsTrusted:
              type: boolean
            aiReviewStatus:
              type: string
              enum:
              - not_required
              - pending
              - approved
              - flagged
              - failed
              description: State of the automated sender-health review opened when the pause was created.
            aiReviewReason:
              type:
              - string
              - 'null'
            aiReviewStartedAt:
              type:
              - string
              - 'null'
              format: date-time
            aiReviewedAt:
              type:
              - string
              - 'null'
              format: date-time
            unavailableReason:
              type:
              - string
              - 'null'
              enum:
              - unsupported_reason
              - waiting_for_review
              - blocked_by_ai
              - review_failed
              - blocked_by_admin
              - null
              description: The gate blocking resume. Null when resume is available.
        senderHealth:
          type:
          - object
          - 'null'
          description: Null when the workspace has no metrics record yet or sender-health analytics are temporarily unavailable. Pause state and remediation remain available during an analytics outage.
          properties:
            enforcementMode:
              type: string
              enum:
              - enforce
              - monitor_only
            scopedSent:
              type: integer
              description: Backward-compatible alias for bounceScopedSent.
            bounceScopedSent:
              type: integer
              description: Non-test sends counted from the bounce reset watermark - the denominator for hard- and soft-bounce rates.
            complaintScopedSent:
              type: integer
              description: Non-test sends counted from the complaint reset watermark - the denominator for complaint rates.
            blockScopedSent:
              type: integer
              description: Sends, test sends included, counted from the bounce reset watermark - the denominator for the block rate.
            hardBounce:
              $ref: '#/components/schemas/SenderHealthMetric'
            softBounce:
              $ref: '#/components/schemas/SenderHealthMetric'
            block:
              allOf:
              - $ref: '#/components/schemas/SenderHealthMetric'
              description: Refusals the sender caused - spam or content, the sending domain's reputation, policy, or failed SPF, DKIM or DMARC. Refusals caused by our infrastructure never count.
            complaint:
              $ref: '#/components/schemas/SenderHealthMetric'
        metricsWindow:
          type: object
          properties:
            kind:
              type: string
              enum:
              - all_time_since_reset
            expiresAt:
              type:
              - string
              - 'null'
              description: Always null. Enforcement totals are all-time from the watermark, so a paused rate never expires on its own.
            bounceResetAt:
              type:
              - string
              - 'null'
              format: date-time
            complaintResetAt:
              type:
              - string
              - 'null'
              format: date-time
            description:
              type: string
        remediation:
          type: object
          properties:
            steps:
              type: array
              description: Ordered next steps for the current state.
              items:
                type: string
            supportEmail:
              type: string
            docsUrl:
              type: string
            dashboardPath:
              type:
              - string
              - 'null'
            dashboardUrl:
              type:
              - string
              - 'null'
    InputIssue:
      type: object
      properties:
        path:
          type: string
          description: Dotted field path, such as `audience.subscriberIds[0]`. Empty when the problem is with the request body itself.
          example: kind
        message:
          type: string
          description: What is wrong with the field.
          example: must be "add_tags"
        allowedValues:
          type: array
          description: Accepted values when the field only takes a fixed set of values.
          items: {}
          example:
          - add_tags
      required:
      - path
      - message
  headers:
    RetryAfter:
      description: Number of seconds to wait before retrying the request.
      schema:
        type: integer
        minimum: 1
        example: 1
  responses:
    TransientDatabaseUnavailable:
      description: The database was temporarily unavailable. The request may be retried after the delay in Retry-After.
      headers:
        Retry-After:
          $ref: '#/components/headers/RetryAfter'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            success: false
            error: The service could not reach its database for a moment. Retry the request.
            code: SERVICE_UNAVAILABLE
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: API key passed as Bearer token