Sequenzy Notification Preferences API

openapi: 3.2.0
info:
  title: Sequenzy Notification Preferences 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: Notification Preferences
paths:
  /notification-preferences:
    get:
      operationId: getNotificationPreferences
      summary: Get account notification preferences
      description: Returns the account notification settings for the API key's own user in the active company, along with the modes each event supports and the platform defaults. Every event available to the requesting client is present; an event the user has never configured reports its default. Default Node and Undici clients must send x-sequenzy-client to receive weekly_report. There is no way to read another member's preferences through this API. Requires account:read.
      tags:
      - Notification Preferences
      parameters:
      - name: x-sequenzy-client
        in: header
        required: false
        schema:
          type: string
        description: Identifies a client that supports the complete notification event list, including weekly_report. Any non-empty value opts a default Node or Undici client into the full response.
      responses:
        '200':
          description: Notification preferences returned
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotificationPreferences'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '503':
          $ref: '#/components/responses/TransientDatabaseUnavailable'
    patch:
      operationId: updateNotificationPreferences
      summary: Update account notification preferences
      description: Changes which account notifications Sequenzy emails the API key's own user for the active company. Events not listed keep their current value. Useful before a bulk import or migration, though imports never trigger new-subscriber notifications in the first place. Requires companies:manage; account:read alone cannot mutate these settings.
      tags:
      - Notification Preferences
      parameters:
      - name: x-sequenzy-client
        in: header
        required: false
        schema:
          type: string
        description: Identifies a client that supports the complete notification event list, including weekly_report. Any non-empty value opts a default Node or Undici client into the full response.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - notificationPreferences
              properties:
                notificationPreferences:
                  type: array
                  minItems: 1
                  description: Preferences to set. Events not listed are left unchanged.
                  items:
                    $ref: '#/components/schemas/NotificationPreference'
      responses:
        '200':
          description: Notification preferences updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotificationPreferences'
        '400':
          description: Unsupported event or mode. "daily" is not valid for form_submitted or campaign_completed; "weekly" is only valid for weekly_report; account_health accepts only "off" or "instant".
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  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
  schemas:
    NotificationPreference:
      type: object
      required:
      - event
      - mode
      properties:
        event:
          type: string
          enum:
          - new_subscriber
          - form_submitted
          - campaign_completed
          - weekly_report
          - account_health
          description: Which notification to configure. weekly_report is the Monday summary of last week's sends, engagement, new subscribers, revenue, goals, and sequence trends; it is on by default for the workspace owner, off by default for invited members, and only sent for weeks with more than 10 emails sent. account_health is the findings of the scheduled account health check, carried inside the Monday report when the person gets it and sent as their own email otherwise; on by default for the workspace owner, off for invited members.
        mode:
          type: string
          enum:
          - 'off'
          - instant
          - daily
          - weekly
          description: How to receive it. "instant" sends one email per occurrence, "daily" one summary per day, "weekly" one report per week. Instant form_submitted notifications stop after 50 per workspace per UTC day. "daily" is not supported for form_submitted or campaign_completed; weekly_report accepts only "off" or "weekly"; account_health accepts only "off" or "instant".
    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
    NotificationPreferences:
      type: object
      properties:
        success:
          type: boolean
        notificationPreferences:
          type: array
          description: Every notification event available to this client with its current mode, defaults included. Node and Undici clients that omit x-sequenzy-client receive the three legacy events for compatibility, and Sequenzy CLI releases up to 0.0.174 (x-sequenzy-client cli/0.0.174 or earlier) do not receive account_health.
          items:
            $ref: '#/components/schemas/NotificationPreference'
        supportedModes:
          type: object
          description: Modes each event accepts, keyed by event.
          additionalProperties:
            type: array
            items:
              type: string
        defaults:
          type: object
          description: Mode each event uses when the user has never configured it, resolved for the API key's user. The workspace owner defaults to weekly_report "weekly" and account_health "instant"; invited members default to "off".
          additionalProperties:
            type: string
    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
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: API key passed as Bearer token