Sequenzy Email Blocks API

openapi: 3.2.0
info:
  title: Sequenzy Email Blocks 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 Blocks
  description: Field reference for the email block types accepted by every blocks array
paths:
  /email-blocks/line-items/assist:
    post:
      summary: Preview cart items and suggest mappings
      operationId: previewCartItems
      tags:
      - Email Blocks
      description: Requires authentication, accepts existing restricted keys, and operates only on supplied data. Does not save or send. Safe to retry.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                items:
                  type: array
                  maxItems: 50
                  default: []
                  items:
                    type: object
                    additionalProperties: true
                itemFields:
                  type: object
                  description: Existing relative dotted paths. Blank values use defaults; unsafe prototype paths are rejected. Suggestions do not replace existing mappings.
                  properties:
                    title:
                      type: string
                      maxLength: 200
                    variantTitle:
                      type: string
                      maxLength: 200
                    quantity:
                      type: string
                      maxLength: 200
                    priceCents:
                      type: string
                      maxLength: 200
                    price:
                      type: string
                      maxLength: 200
                    imageUrl:
                      type: string
                      maxLength: 200
                    url:
                      type: string
                      maxLength: 200
                    currency:
                      type: string
                      maxLength: 200
                scenario:
                  type: string
                  enum:
                  - real
                  - one
                  - many
                  - empty
                  - missing-images
                  - long-names
                  default: real
                  description: Many returns 12 cloned rows; nonempty sample scenarios use a sample product if items are empty. Real preserves supplied items.
                priceUnit:
                  type: string
                  enum:
                  - minor
                  - major
                  default: minor
                  description: Numeric item prices use cents or explicit major units. The separate total remains in cents.
      responses:
        '200':
          description: Mapping suggestions, isolated preview data and design presets. No persistent changes.
          content:
            application/json:
              schema:
                type: object
                required:
                - success
                - suggestions
                - priceCandidates
                - previewItems
                - scenario
                - isSample
                - presets
                properties:
                  success:
                    type: boolean
                    const: true
                  suggestions:
                    type: array
                    items:
                      type: object
                      required:
                      - field
                      - path
                      - example
                      properties:
                        field:
                          type: string
                        path:
                          type: string
                        example:
                          type: string
                  priceCandidates:
                    type: array
                    description: Numeric prices requiring explicit unit selection.
                    items:
                      type: object
                      required:
                      - path
                      - example
                      - units
                      properties:
                        path:
                          type: string
                        example:
                          type: string
                        units:
                          type: string
                          const: unknown
                  previewItems:
                    type: array
                    items:
                      type: object
                      additionalProperties: true
                  scenario:
                    type: string
                    enum:
                    - real
                    - one
                    - many
                    - empty
                    - missing-images
                    - long-names
                  isSample:
                    type: boolean
                    description: True for every scenario except real.
                  presets:
                    type: array
                    items:
                      type: object
                      required:
                      - id
                      - label
                      - description
                      - settings
                      properties:
                        id:
                          type: string
                        label:
                          type: string
                        description:
                          type: string
                        settings:
                          type: object
                          properties:
                            imageSize:
                              type: integer
                              minimum: 32
                              maximum: 120
                            rowSpacing:
                              type: integer
                              minimum: 0
                              maximum: 32
                            fontSize:
                              type: integer
                              minimum: 12
                              maximum: 24
                            imageFit:
                              type: string
                              enum:
                              - cover
                              - contain
        '400':
          description: Invalid items, mappings, scenario or price units. Returns success false, error and validation details.
        '401':
          description: Missing or invalid authentication.
        '403':
          description: Authentication access restriction.
  /email-blocks:
    get:
      summary: List email block types
      description: Lists every block type accepted by the `blocks` array on campaigns, sequence email steps, templates, transactional emails, and email components, with the required and optional fields of each. Derived from the same schemas that validate a write, so it cannot drift from what those endpoints accept.
      operationId: listEmailBlockTypes
      tags:
      - Email Blocks
      parameters:
      - name: creatableOnly
        in: query
        required: false
        schema:
          type: string
          enum:
          - 'true'
        description: Hide structural block types the editor manages for you.
      responses:
        '200':
          description: Block types listed
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  blockTypes:
                    type: array
                    items:
                      $ref: '#/components/schemas/EmailBlockTypeReference'
                  conditionFields:
                    type: array
                    description: The per-field table for block conditions, always returned with the list. This is the call made to find out what exists, and the table adds about 9% to it.
                    items:
                      $ref: '#/components/schemas/EmailBlockConditionFieldReference'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '503':
          $ref: '#/components/responses/TransientDatabaseUnavailable'
  /email-blocks/{type}:
    get:
      summary: Get email block type
      description: Returns the full field reference for one block type, with a minimal valid example and authoring notes. For line-items, includes optional itemFields mappings from display fields to relative dotted paths within each item. Omitted or blank mappings use standard field names. Mapping values must be strings of at most 200 characters.
      operationId: getEmailBlockType
      tags:
      - Email Blocks
      parameters:
      - name: type
        in: path
        required: true
        schema:
          type: string
        description: Block type, for example list, steps, text, or hero.
        example: steps
      - name: conditionFields
        in: query
        required: false
        schema:
          type: string
          enum:
          - 'true'
        description: Include the per-field condition table in the response. Not needed for `conditional-group`, which always carries it. The table is several times the size of one block type's reference, so a targeted lookup does not carry it unless asked.
      responses:
        '200':
          description: Block type reference
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  blockType:
                    $ref: '#/components/schemas/EmailBlockTypeReference'
                  conditionFields:
                    type: array
                    description: The per-field table for block conditions. Returned when `type` is `conditional-group`, or when `conditionFields=true` is passed.
                    items:
                      $ref: '#/components/schemas/EmailBlockConditionFieldReference'
                  conditionFieldsHint:
                    type: string
                    description: Returned in place of `conditionFields` when the table was not included, saying that conditions are per-field and how to request the table.
                    example: 'Every block also takes a `conditions` array, and each condition field accepts only its own operators. Request this endpoint with ?conditionFields=true, or GET /email-blocks, for `conditionFields`: the operators, value format, and render-preview support of every condition field.'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Unknown block type
          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
  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:
    EmailBlockTypeReference:
      type: object
      description: 'Field reference for one email block type. Lists are their own block type rather than a text variant: a `text` block accepts only variant paragraph, lead, or html and never accepts `items`.'
      properties:
        type:
          type: string
          example: steps
        creatable:
          type: boolean
          description: False for structural types the editor manages, which should not be hand-authored.
        reason:
          type: string
          description: Why a non-creatable type is excluded.
        required:
          type: array
          items:
            type: string
          example:
          - items
          - variant
        optional:
          type: array
          items:
            type: string
          example:
          - id
          - accentColor
          - styles
          - conditions
        fields:
          type: array
          items:
            $ref: '#/components/schemas/EmailBlockFieldReference'
        example:
          type: object
          description: A minimal valid block of this type.
          additionalProperties: true
        notes:
          type: array
          items:
            type: string
    EmailBlockConditionFieldReference:
      type: object
      description: 'One field a block condition may filter on. A block''s own `field` and `operator` entries are two flat enums that pool every field''s operators together, and the schema narrows them against each other when it validates - so `{"field": "tag", "operator": "is"}` parses and is then rejected. This is that narrowing, spelled out.'
      properties:
        field:
          type: string
          example: tag
        label:
          type: string
          example: Tag
        operators:
          type: array
          description: The only operators this field accepts.
          items:
            type: string
          example:
          - contains
          - not_contains
          - is_empty
          - is_not_empty
        values:
          type: array
          description: Closed value set, for the fields that have one.
          items:
            type: string
        valueFormat:
          type: string
          description: How the `value` string is shaped for this field.
        serverEvaluated:
          type: boolean
          description: Whether the field reads stored subscriber state rather than the merge data of the send.
        previewSupport:
          type: string
          enum:
          - any_contact
          - inline_tags_or_stored_subscriber
          - stored_subscriber
          description: What a render needs before it can evaluate this field. any_contact - resolved from merge data. inline_tags_or_stored_subscriber - tag, which an inline contact can state for itself. stored_subscriber - needs subscriberId. A condition a render cannot evaluate renders as false and is listed in that render's unevaluatedConditions.
        example:
          type: object
          description: A valid condition using this field.
          additionalProperties: true
      required:
      - field
      - label
      - operators
      - valueFormat
      - serverEvaluated
      - previewSupport
      - example
    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
    EmailBlockFieldReference:
      type: object
      properties:
        name:
          type: string
          example: variant
        required:
          type: boolean
        type:
          type: string
          description: Value shape, for example string, number, boolean, enum, array, or object.
          example: enum
        values:
          type: array
          description: Allowed values, for enum and literal-union fields.
          items: {}
          example:
          - numbered
          - timeline
        itemFields:
          type: array
          description: 'Shape of one entry in an array field. This is where `list` and `steps` differ: list items carry `content`, steps items carry `title` and an optional `description`.'
          items:
            $ref: '#/components/schemas/EmailBlockFieldReference'
        fields:
          type: array
          description: Shape of an object field, for example the `mode`, `strategy`, `lookbackDays`, `sort`, and `filters` of a repeat block's `productSource`.
          items:
            $ref: '#/components/schemas/EmailBlockFieldReference'
    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