Sequenzy Email AI Style API

openapi: 3.2.0
info:
  title: Sequenzy Email AI Style 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: Email AI Style
paths:
  /email-ai-style:
    get:
      operationId: getEmailAiStyle
      summary: Get saved AI email style
      description: Requires emails:read. Returns the saved appearance and its revision. Read and review this state before replacing or clearing it.
      tags:
      - Email AI Style
      responses:
        '200':
          description: Current saved-style state
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EmailAiStyleState'
        '401':
          description: Missing or invalid API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Missing required scope or workspace role cannot perform this operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Company or accessible source email not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '503':
          $ref: '#/components/responses/TransientDatabaseUnavailable'
    put:
      operationId: saveEmailAiStyle
      summary: Save AI email style
      description: Requires emails:write and access to the source email. Snapshots the stored email appearance, using email then company theme and font defaults, or the optional unsaved canvas, plus detected layout habits such as dotted dividers around every button. Existing emails and company theme remain unchanged. Marketers cannot capture transactional sources. Replaces only the expected revision; explicit generation style requests and plain-text choices still take precedence.
      tags:
      - Email AI Style
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - emailId
              - expectedStyleId
              properties:
                emailId:
                  type: string
                  minLength: 1
                  description: Source email ID in this company, including campaign, sequence and transactional email rows. Use the underlying email ID, not a campaign ID or transactional slug.
                expectedStyleId:
                  type:
                  - string
                  - 'null'
                  minLength: 1
                  description: revisionId returned by GET. Use null only when no style is stored.
                canvas:
                  $ref: '#/components/schemas/EmailAiStyleCanvas'
                layoutRuleIds:
                  type: array
                  maxItems: 20
                  description: IDs of detected layout habits to keep. Omit to keep every habit detected in the source; pass an empty array to keep none. Unknown IDs are ignored. Review style.layout.rules in the response.
                  items:
                    type: string
                    minLength: 1
                    maxLength: 200
                notes:
                  type: string
                  maxLength: 500
                  description: Optional design notes for future generations, for example "always open with a short video". Treated as design guidance, never as email content.
      responses:
        '200':
          description: Current saved-style state
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EmailAiStyleState'
        '400':
          description: Invalid or oversized canvas, or no substantive email content
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Missing or invalid API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Missing required scope or workspace role cannot perform this operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Company or accessible source email not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '409':
          description: AI_STYLE_CONFLICT. Get the current style, review it and retry with its revisionId. Do not automatically retry a conflicting write.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '422':
          description: Missing or malformed required fields
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '503':
          $ref: '#/components/responses/TransientDatabaseUnavailable'
    delete:
      operationId: clearEmailAiStyle
      summary: Clear saved AI email style
      description: Requires emails:write. Clears only the reviewed revision. Future generations use normal brand defaults; existing emails stay unchanged. Replayed or stale clears return 409.
      tags:
      - Email AI Style
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - expectedStyleId
              properties:
                expectedStyleId:
                  type: string
                  minLength: 1
                  description: Nonempty revisionId returned by GET, including unsupported-version revisions.
      responses:
        '200':
          description: Current saved-style state
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EmailAiStyleState'
        '400':
          description: Invalid or oversized canvas, or no substantive email content
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Missing or invalid API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Missing required scope or workspace role cannot perform this operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Company or accessible source email not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '409':
          description: AI_STYLE_CONFLICT. Get the current style, review it and retry with its revisionId. Do not automatically retry a conflicting write.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '422':
          description: Missing or malformed required fields
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '503':
          $ref: '#/components/responses/TransientDatabaseUnavailable'
components:
  headers:
    RetryAfter:
      description: Number of seconds to wait before retrying the request.
      schema:
        type: integer
        minimum: 1
        example: 1
  schemas:
    EmailAiStyleCanvas:
      type: object
      required:
      - blocks
      - theme
      - fontFamily
      - emailPreset
      properties:
        blocks:
          type: array
          maxItems: 500
          description: Native blocks JSON, limited to 500,000 serialized characters. Must contain substantive email content.
          items:
            type: object
            additionalProperties: true
        theme:
          type: object
          description: Complete editor theme. Required color keys are primary, background, surface, text, mutedText, heading, border and link. Required typography keys are baseFontSize, leadFontSize, baseLineHeight, heading1Size, heading2Size, heading3Size and buttonFontSize. Required layout keys are contentWidth, containerPaddingX, containerPaddingY, blockSpacing, baseRadius, sectionPadding, buttonPaddingX, buttonPaddingY and borderedBlockPadding. Optional theme fields match the editor, including content color, heading font, button radius and weight, and layout.contentAlign (center or left).
          required:
          - presetId
          - colors
          - typography
          - layout
          properties:
            presetId:
              type: string
              enum:
              - default
              - soft
              - editorial
              - bold
            colors:
              type: object
              additionalProperties:
                type: string
            typography:
              type: object
              additionalProperties: true
            layout:
              type: object
              properties:
                contentAlign:
                  type: string
                  enum:
                  - center
                  - left
              additionalProperties:
                type: number
          additionalProperties: true
        fontFamily:
          type: string
          minLength: 1
          maxLength: 500
        emailPreset:
          type: string
          enum:
          - branded
          - minimal
    EmailAiStyleLayoutRule:
      type: object
      required:
      - id
      - kind
      - block
      - description
      properties:
        id:
          type: string
          description: Stable rule identifier, for example around|button|divider:dots. Pass it in layoutRuleIds to keep the habit.
        kind:
          type: string
          enum:
          - opener
          - around
          - before
          - after
        block:
          type: string
          description: Target block type, for example button or video.
        companion:
          type: string
          description: Content-free companion descriptor for around/before/after rules, for example divider:dots.
        description:
          type: string
          example: Dotted divider above and below every button
    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
    EmailAiStyleState:
      type: object
      required:
      - success
      - style
      - revisionId
      - canManage
      properties:
        success:
          type: boolean
        style:
          type:
          - object
          - 'null'
          description: Independent version 1 appearance snapshot. No source copy, links or bindings are stored in block styles. Unsupported versions are returned as null.
          properties:
            version:
              type: integer
              enum:
              - 1
            id:
              type: string
            sourceEmailId:
              type: string
            sourceName:
              type: string
            savedAt:
              type: string
              format: date-time
            theme:
              type: object
              additionalProperties: true
            fontFamily:
              type: string
            emailPreset:
              type: string
              enum:
              - branded
              - minimal
            blocks:
              type: array
              description: Appearance records keyed by block type and discriminator, not source email blocks.
              items:
                type: object
                additionalProperties: true
            layout:
              type: object
              description: Structure guidance captured with the appearance. Absent on snapshots saved before layout habits existed.
              properties:
                outline:
                  type: array
                  description: Top-level block descriptors in source order (for example heading:1, divider:dots, button:pill), excluding logo and footer scaffolding.
                  items:
                    type: string
                rules:
                  type: array
                  description: Confirmed layout habits. Generation follows them in prompts and inserts content-free companions (dividers, spacers) deterministically.
                  items:
                    $ref: '#/components/schemas/EmailAiStyleLayoutRule'
            notes:
              type: string
              description: Free-text design notes supplied when saving, up to 500 characters.
        revisionId:
          type:
          - string
          - 'null'
          description: Pass this as expectedStyleId on the next write. An unsupported style version still returns its revision for replacement or clearing.
        canManage:
          type: boolean
          description: Whether your key scopes and workspace role permit saving or clearing.
    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
  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