Sequenzy Generation API

openapi: 3.2.0
info:
  title: Sequenzy Generation 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: Generation
paths:
  /generate/email:
    post:
      operationId: generateEmail
      summary: Generate email
      description: Generates a draft email from scratch as structured editor-compatible blocks. By default, the generated content is wrapped with the company's logo and footer.
      tags:
      - Generation
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - prompt
              properties:
                prompt:
                  type: string
                  description: What you want the email to say or accomplish.
                  example: Announce our new analytics dashboard to trial users
                style:
                  type: string
                  description: Optional style guidance. Pass "designed" or "plain" to force the designed or plain-text email style; other values (such as "minimal", "branded", or "promotional") are freeform prompt guidance. Defaults to the company's email style preference (designed unless the company chose plain text).
                  example: branded
                tone:
                  type: string
                  description: Optional tone guidance.
                  example: friendly
                applyBranding:
                  type: boolean
                  default: true
                  description: Whether to wrap generated content with the company logo and footer. Set to false to return raw generated content blocks.
                emailType:
                  type: string
                  enum:
                  - marketing
                  - transactional
                  default: marketing
                  description: Email type. Transactional emails include a footer without an unsubscribe link.
      responses:
        '200':
          description: Email generated successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  subject:
                    type: string
                    example: Meet your new analytics dashboard
                  previewText:
                    type: string
                    example: A clearer way to track what matters
                  blocks:
                    type: array
                    description: Generated editor-compatible blocks, including company logo and footer branding unless applyBranding is false.
                    items:
                      $ref: '#/components/schemas/EmailBlock'
                  message:
                    type: string
                    example: Generated a draft email.
        '400':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: No company selected
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Generation failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /generate/subjects:
    post:
      operationId: generateSubjectLines
      summary: Generate subject lines
      description: Generates draft subject line variants for a campaign or sequence email.
      tags:
      - Generation
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - topic
              properties:
                topic:
                  type: string
                  description: Topic, campaign idea, or context for the subject lines.
                  example: April product launch
                count:
                  type: number
                  minimum: 1
                  description: Number of variants to generate. Defaults to 5.
                  example: 5
      responses:
        '200':
          description: Subject lines generated successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  topic:
                    type: string
                    example: April product launch
                  subjects:
                    type: array
                    items:
                      type: string
                    example:
                    - Meet what we shipped in April
                    - Your April product update is here
        '400':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: No company selected
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Generation failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /generate/sms:
    post:
      operationId: generateSmsMessages
      summary: Generate SMS messages
      description: Generates draft SMS marketing message variants with per-message encoding and segment counts. Messages exclude opt-out footers and brand prefixes - Sequenzy adds both automatically at send time.
      tags:
      - Generation
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - prompt
              properties:
                prompt:
                  type: string
                  description: Description of the SMS to generate.
                  example: Cart reminder with a free-shipping hook
                count:
                  type: number
                  minimum: 1
                  maximum: 10
                  description: Number of variants to generate. Defaults to 3.
                  example: 3
      responses:
        '200':
          description: SMS messages generated successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  prompt:
                    type: string
                    example: Cart reminder with a free-shipping hook
                  messages:
                    type: array
                    items:
                      type: object
                      properties:
                        text:
                          type: string
                          example: Hey {{FIRST_NAME}}, your cart is waiting! Complete your order today and shipping is on us.
                        encoding:
                          type: string
                          enum:
                          - gsm7
                          - ucs2
                          example: gsm7
                        segments:
                          type: number
                          example: 1
                        characterCount:
                          type: number
                          example: 94
        '400':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: No company selected
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Generation failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    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
    EmailBlock:
      type: object
      description: Email content block. The shape depends on the block type. Any block may carry a `conditions` array so it renders only for matching recipients, the structural `group` type wraps children in Stack, Row, Grid, or Overlay layout, and `conditional-group` adds if/else branching via `ifBranch` and `elseBranch` (each an object with a `children` array).
      required:
      - type
      properties:
        id:
          type: string
          example: block_123
        type:
          type: string
          enum:
          - text
          - html
          - heading
          - list
          - button
          - spacer
          - divider
          - image
          - columns
          - group
          - conditional-group
          - repeat
          - card
          - cta
          - social
          - logo
          - header
          - footer
          - video
          - product
          - discount-code
          - code
          - countdown
          - hero
          - testimonial
          - gallery
          - badge
          - table
          - features
          - image-card
          - pricing
          - author
          - article
          - rating
          - stats
          - steps
          - product-grid
          - poll
          example: html
        content:
          type: string
          description: Content for text, html, and heading-like blocks.
          example: <h1>Hello</h1>
        label:
          type: string
          maxLength: 120
          default: Group
          description: Editor label for a structural group block.
        layout:
          type: string
          enum:
          - stack
          - row
          - grid
          - overlay
          default: stack
          description: Direct-child layout for a structural group block.
        columns:
          type: integer
          minimum: 1
          maximum: 4
          default: 2
          description: Number of columns used by a group with grid layout.
        gap:
          type: integer
          minimum: 0
          maximum: 64
          default: 16
          description: Gap in pixels between direct group children.
        stackOnMobile:
          type: boolean
          default: true
          description: Columns block only. Multi-column rows stack into a single column on screens 480px wide or narrower. Set to false to keep the columns side by side on mobile. Omit or set to true for the default stacking.
        padding:
          type: integer
          minimum: 0
          maximum: 64
          default: 0
          description: Uniform group padding in pixels; per-side styles.padding* fields override it.
        overlayColor:
          type: string
          default: '#000000'
          description: Opaque fallback and shade color for an overlay group.
        overlayShade:
          type: integer
          minimum: 0
          maximum: 100
          default: 35
          description: Overlay shade intensity as a percentage.
        overlayPosition:
          type: string
          enum:
          - top
          - center
          - bottom
          default: center
          description: Vertical position of overlay foreground content.
        children:
          type: array
          minItems: 1
          maxItems: 100
          description: Recursive child blocks for group and repeat containers.
          items:
            $ref: '#/components/schemas/EmailBlock'
        styles:
          type: object
          description: Per-block visual styles. For compatibility, style fields such as backgroundColor, backgroundOpacity, borderColor, borderWidth, and borderRadius can also be supplied at the block top level and are normalized into this object.
          additionalProperties: false
          properties:
            paddingTop:
              type: number
            paddingBottom:
              type: number
            paddingLeft:
              type: number
            paddingRight:
              type: number
            backgroundColor:
              type: string
              example: '#f8fafc'
            backgroundOpacity:
              type: number
              minimum: 0
              maximum: 100
              description: Background opacity percentage from 0 to 100.
              example: 80
            textColor:
              type: string
              example: '#111827'
            textAlign:
              type: string
              enum:
              - left
              - center
              - right
            keepAlign:
              type: boolean
              description: Keep a centered button, logo or footer centered when the email is left-aligned (layout.contentAlign left). Without it a left email moves these blocks left; right always stays.
            borderRadius:
              type: number
              example: 12
            borderColor:
              type: string
              example: '#cbd5e1'
            borderWidth:
              type: number
              example: 1
            bleed:
              type: boolean
              description: Stretch the block edge-to-edge across the email container. Top-level blocks only.
        conditions:
          type: array
          description: Optional per-block display rules. The block renders only when every rule matches. The same shape is used for a conditional-group block's top-level `conditions`.
          items:
            type: object
            required:
            - id
            - field
            - operator
            - value
            properties:
              id:
                type: string
                example: c1
              field:
                type: string
                enum:
                - variable
                - attribute
                - email
                - firstName
                - lastName
                description: '`variable` resolves a merge-tag path from the transactional send `variables` or an automation `event` payload (nested paths like `order.total` or `event.plan` work). `attribute` reads a stored subscriber attribute. `email`, `firstName`, and `lastName` read core subscriber fields.'
              operator:
                type: string
                enum:
                - is
                - is_not
                - contains
                - not_contains
                - gt
                - gte
                - lt
                - lte
                - is_empty
                - is_not_empty
              value:
                type: string
                description: For `variable` and `attribute`, use `name:value` - the part before the colon is the variable path or attribute name, and the part after it is the comparison value. For `email`, `firstName`, and `lastName`, provide the plain comparison string.
                example: plan:pro
      additionalProperties: true
    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
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: API key passed as Bearer token