Sequenzy Emails API

openapi: 3.2.0
info:
  title: Sequenzy Emails 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: Emails
paths:
  /emails:
    post:
      summary: Create email
      description: Creates an email template with block content. Raw HTML is stored as a native HTML body.
      operationId: createEmail
      tags:
      - Emails
      requestBody:
        required: true
        content:
          application/json:
            schema:
              allOf:
              - $ref: '#/components/schemas/EmailBodyInput'
              - type: object
                required:
                - name
                - subject
                properties:
                  name:
                    type: string
                    example: Welcome email
                  subject:
                    type: string
                    example: Welcome
                  previewText:
                    type:
                    - string
                    - 'null'
                    example: Here's what to do next
      responses:
        '201':
          description: Email created
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  email:
                    $ref: '#/components/schemas/Email'
                  warnings:
                    $ref: '#/components/schemas/BlockFieldWarnings'
        '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: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /emails/{emailId}:
    patch:
      summary: Update email
      description: Updates email metadata or replaces the email body.
      operationId: updateEmail
      tags:
      - Emails
      parameters:
      - name: emailId
        in: path
        required: true
        schema:
          type: string
        description: Email ID
      requestBody:
        required: true
        content:
          application/json:
            schema:
              allOf:
              - $ref: '#/components/schemas/EmailBodyInput'
              - type: object
                properties:
                  name:
                    type: string
                  subject:
                    type: string
                  previewText:
                    type:
                    - string
                    - 'null'
      responses:
        '200':
          description: Email updated
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  email:
                    $ref: '#/components/schemas/Email'
                  warnings:
                    $ref: '#/components/schemas/BlockFieldWarnings'
        '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'
        '404':
          description: Email not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /emails/{emailId}/blocks:
    patch:
      summary: Update email blocks
      description: Replaces an email body or mutates an existing block type.
      operationId: updateEmailBlocks
      tags:
      - Emails
      parameters:
      - name: emailId
        in: path
        required: true
        schema:
          type: string
        description: Email ID
      requestBody:
        required: true
        content:
          application/json:
            schema:
              allOf:
              - $ref: '#/components/schemas/EmailBodyInput'
              - type: object
                properties:
                  blockId:
                    type: string
                    description: Existing block ID to mutate.
                  type:
                    type: string
                    description: New block type. Type mutation supports text and html.
                    enum:
                    - text
                    - html
                  content:
                    type: string
                    description: Optional replacement content for the mutated block.
      responses:
        '200':
          description: Email blocks updated
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  email:
                    $ref: '#/components/schemas/Email'
                  warnings:
                    $ref: '#/components/schemas/BlockFieldWarnings'
        '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'
        '404':
          description: Email or block not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    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
    BlockFieldWarnings:
      type: array
      description: Non-blocking advisories about a successful write. Present when an input was discarded or did not take effect as requested. This includes block fields that do not render as their names suggest, sequence email-step formatting restored on top of submitted blocks, and sender-identity conflicts such as a replyToName that differs from the saved profile. Each message identifies the affected input and gives recovery guidance. Absent when there is nothing to report.
      items:
        type: string
      example:
      - 'blocks[0].styles.color is not a supported field and was ignored. Button label color comes from the block-level `buttonTextColor` field. Supported styles fields: backgroundColor, backgroundOpacity, bleed, borderColor, borderRadius, borderWidth, keepAlign, paddingBottom, paddingLeft, paddingRight, paddingTop, textAlign, textColor.'
    EmailBodyInput:
      type: object
      properties:
        html:
          type: string
          description: Raw HTML body. Provide either html or blocks, not both.
          example: <h1>Hello</h1>
        blocks:
          type: array
          description: Structured email blocks. Provide either blocks or html, not both. Put visual styling under styles; top-level style keys such as backgroundColor, backgroundOpacity, borderColor, borderWidth, and borderRadius are normalized into styles.
          items:
            $ref: '#/components/schemas/EmailBlock'
    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
    Email:
      type: object
      properties:
        id:
          type: string
          example: email_123
        companyId:
          type: string
          example: company_123
        name:
          type: string
          example: Welcome email
        subject:
          type: string
          example: Welcome
        previewText:
          type:
          - string
          - 'null'
          example: Here's what to do next
        blocks:
          type: array
          items:
            $ref: '#/components/schemas/EmailBlock'
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
    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