Sequenzy References API

openapi: 3.2.0
info:
  title: Sequenzy References 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: References
  description: Email gallery examples from brands like yours, to model new emails on
paths:
  /references:
    get:
      operationId: listEmailReferences
      summary: List email references
      description: Lists real emails (and, for sequences, whole sequences) from the Sequenzy email gallery to model a new email on, for the kind of email you are creating. By default they come from the gallery brands most like you, ranked by how close their businesses (what each sells, and to whom) are in meaning to your company description, closest first (rankings are reused for up to 10 minutes; a description change counts at once). Each `url` works with the from-example endpoints. Always empty when the gallery is not available. Requires `templates:read`.
      tags:
      - References
      parameters:
      - name: kind
        in: query
        required: true
        schema:
          type: string
          enum:
          - campaign
          - sequence
          - transactional
      - name: scope
        in: query
        required: false
        description: '`similar` (default) lists emails from the gallery brands most like you; `all` lists the whole gallery for the kind, a page at a time.'
        schema:
          type: string
          enum:
          - similar
          - all
          default: similar
      - name: q
        in: query
        required: false
        description: Search words matched by meaning, most relevant first. With `scope=similar` only those brands' emails are searched. A search is paged.
        schema:
          type: string
          maxLength: 80
      - name: page
        in: query
        required: false
        description: Page for `scope=all` or a search.
        schema:
          type: integer
          minimum: 1
          maximum: 200
          default: 1
      - name: subtype
        in: query
        required: false
        description: For `scope=similar` without `q`, a gallery subtype to list first, such as `password_reset`. Ignored when it does not belong to the kind.
        schema:
          type: string
          maxLength: 64
      - name: limit
        in: query
        required: false
        description: For `scope=similar` without `q`, most emails (and sequences) to return. Also caps sequences elsewhere.
        schema:
          type: integer
          minimum: 1
          maximum: 60
          default: 24
      responses:
        '200':
          description: References
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  kind:
                    type: string
                    enum:
                    - campaign
                    - sequence
                    - transactional
                  scope:
                    type: string
                    enum:
                    - similar
                    - all
                  page:
                    type: integer
                  pageCount:
                    type: integer
                  profile:
                    type: string
                    enum:
                    - ready
                    - missing
                    description: '`missing` when your company has neither a description nor company context to find brands like you; `scope=similar` is then empty. Always `ready` for `scope=all`.'
                  brands:
                    type: array
                    description: With `scope=similar`, the gallery brands most like you, closest first. Empty for `scope=all`.
                    items:
                      type: object
                      properties:
                        name:
                          type: string
                        domain:
                          type: string
                        slug:
                          type: string
                        url:
                          type: string
                  emails:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                        subject:
                          type:
                          - string
                          - 'null'
                        preheader:
                          type:
                          - string
                          - 'null'
                        type:
                          type:
                          - string
                          - 'null'
                        subtype:
                          type:
                          - string
                          - 'null'
                        sentAt:
                          type: string
                          format: date-time
                        analysis:
                          $ref: '#/components/schemas/GalleryEmailAnalysis'
                        brand:
                          type: object
                          properties:
                            name:
                              type: string
                            domain:
                              type: string
                            slug:
                              type: string
                        url:
                          type: string
                  sequences:
                    type: array
                    description: For `kind=sequence` on the first page only.
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                        name:
                          type: string
                        emailCount:
                          type: integer
                        brand:
                          type: object
                          properties:
                            name:
                              type: string
                            domain:
                              type: string
                            slug:
                              type: string
                        url:
                          type: string
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: API key lacks `templates:read`
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '422':
          $ref: '#/components/responses/ValidationError'
        '503':
          description: Your company description could not be compared with gallery brands right now (`REFERENCES_UNAVAILABLE`). Retry shortly, or use `scope=all`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /gallery/brand-requests:
    get:
      operationId: listGalleryBrandRequests
      summary: List brand requests
      description: Lists your requests to add brands (usually competitors) to the Sequenzy email gallery, newest first, with where each one stands. A request moves from `requested` to `collecting` once the brand is added to the gallery, then to `available` once its emails are in the gallery, when `brand.url` links to them and List Email References can return them. Requests are private to your company. Requires `templates:read`.
      tags:
      - References
      responses:
        '200':
          description: Your brand requests
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  requests:
                    type: array
                    items:
                      $ref: '#/components/schemas/GalleryBrandRequest'
                  limit:
                    type: integer
                    description: How many requests a company can keep, declined ones included.
                    example: 50
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: API key lacks `templates:read`
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    post:
      operationId: createGalleryBrandRequest
      summary: Request a brand
      description: Asks for a brand, usually a competitor, to be added to the Sequenzy email gallery, the same as **Suggest a brand** in the dashboard's gallery picker. Asking again for the same domain keeps the one request (a new `note` replaces the old) and returns 200 with `created` false, so retries never duplicate. If the brand is already in the gallery, the request comes back with status `available`. Requires `templates:write`.
      tags:
      - References
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - website
              properties:
                website:
                  type: string
                  maxLength: 255
                  description: The brand's website or domain, such as `competitor.com` or `https://competitor.com/pricing`. It is reduced to the registrable domain, so `www.competitor.com` and `competitor.com` are the same request. It cannot be your own website.
                note:
                  type: string
                  maxLength: 300
                  description: Optional. What you want to see from the brand, such as its onboarding emails.
      responses:
        '200':
          description: Already requested; the existing request, with its note updated when one was sent
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GalleryBrandRequestResult'
        '201':
          description: Requested
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GalleryBrandRequestResult'
        '400':
          description: Not a valid website, your own website, or the company already keeps 50 requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: API key lacks `templates:write`
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '422':
          $ref: '#/components/responses/ValidationError'
  /gallery/brand-requests/{id}:
    delete:
      operationId: deleteGalleryBrandRequest
      summary: Remove a brand request
      description: Withdraws one of your brand requests. A brand already added to the gallery stays there. Requires `templates:write`.
      tags:
      - References
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Removed
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  deleted:
                    type: boolean
                    example: true
                  id:
                    type: string
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: API key lacks `templates:write`
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: No request with this ID for your company
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /gallery/watchlist:
    get:
      operationId: listGalleryWatchlist
      summary: List watched brands
      description: Lists the brands your company watches, usually competitors, newest watch first. This is the dashboard's **Competitors** page. A brand already in the Sequenzy email gallery is `available`, with how many of its emails are in the gallery and when the newest was sent. Read the emails with List Watched Brand Emails. A watch is a brand request, so List Brand Requests returns the same rows. Requires `templates:read`.
      tags:
      - References
      responses:
        '200':
          description: Your watched brands
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  watchlist:
                    type: array
                    items:
                      $ref: '#/components/schemas/GalleryWatchedBrand'
                  limit:
                    type: integer
                    description: How many watches and brand requests a company can keep together.
                    example: 50
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: API key lacks `templates:read`
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    post:
      operationId: watchGalleryBrand
      summary: Watch a brand
      description: Watches a brand, usually a competitor, by its website. A brand already in the gallery is watched at once with status `available`. Any other brand is requested, the same as Request a Brand, and its emails show up once it is added and they are collected. Watching again keeps the one watch (a new `note` replaces the old) and returns 200 with `created` false, so retries never duplicate. Requires `templates:write`.
      tags:
      - References
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - website
              properties:
                website:
                  type: string
                  maxLength: 255
                  description: The brand's website or domain, such as `competitor.com` or `https://competitor.com/pricing`. It is reduced to the registrable domain. It cannot be your own website.
                note:
                  type: string
                  maxLength: 300
                  description: Optional. What you want to see from the brand, such as its onboarding emails.
      responses:
        '200':
          description: Already watched; the existing watch, with its note updated when one was sent
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GalleryWatchResult'
        '201':
          description: Watching
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GalleryWatchResult'
        '400':
          description: Not a valid website, your own website, or the company already keeps 50 watches and brand requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: API key lacks `templates:write`
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '422':
          $ref: '#/components/responses/ValidationError'
  /gallery/watchlist/emails:
    get:
      operationId: listGalleryWatchlistEmails
      summary: List watched brand emails
      description: Lists emails from the brands your company watches, newest sent first, a page at a time. Emails usually arrive a few hours after they are sent. Hidden and removed emails are never included. Requires `templates:read`.
      tags:
      - References
      parameters:
      - name: domain
        in: query
        required: false
        description: Only this watched brand, by website or domain, such as `linear.app`.
        schema:
          type: string
          maxLength: 255
      - name: since
        in: query
        required: false
        description: Only emails sent at or after this ISO 8601 date or time, such as `2026-10-01` or `2026-10-01T00:00:00Z`.
        schema:
          type: string
      - name: limit
        in: query
        required: false
        description: Emails per page.
        schema:
          type: integer
          minimum: 1
          maximum: 60
          default: 24
      - name: cursor
        in: query
        required: false
        description: '`nextCursor` from the previous page, for older emails.'
        schema:
          type: string
          maxLength: 200
      responses:
        '200':
          description: Emails from your watched brands
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  emails:
                    type: array
                    items:
                      $ref: '#/components/schemas/GalleryWatchedBrandEmail'
                  nextCursor:
                    type:
                    - string
                    - 'null'
                    description: Pass as `cursor` for the next page. `null` on the last page.
        '400':
          description: '`domain` is not a website, `since` is not an ISO 8601 date, or `cursor` is not one returned by this endpoint'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: API key lacks `templates:read`
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '422':
          $ref: '#/components/responses/ValidationError'
  /gallery/watchlist/{id}:
    delete:
      operationId: unwatchGalleryBrand
      summary: Stop watching a brand
      description: Stops watching a brand. This also withdraws the brand request with the same ID. The brand stays in the gallery. Requires `templates:write`.
      tags:
      - References
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: No longer watched
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  deleted:
                    type: boolean
                    example: true
                  id:
                    type: string
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: API key lacks `templates:write`
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: No watch with this ID for your company (`WATCHED_BRAND_NOT_FOUND`)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    GalleryEmailAnalysis:
      type:
      - object
      - 'null'
      description: The email's breakdown, `null` until it has been analyzed. Counts come from its HTML; `voice`, `language`, `structure` and `takeaways` from AI reading the copy. Any field is `null` (or an empty list) when unknown.
      properties:
        mainButton:
          type:
          - string
          - 'null'
          description: Label of the first button, the primary call to action.
        buttonLabels:
          type: array
          items:
            type: string
          description: Button labels in reading order, up to 5.
        buttonCount:
          type:
          - integer
          - 'null'
        linkCount:
          type:
          - integer
          - 'null'
          description: Links of any kind, buttons included.
        wordCount:
          type:
          - integer
          - 'null'
        readingTimeSeconds:
          type:
          - integer
          - 'null'
        imageCount:
          type:
          - integer
          - 'null'
          description: Content images; icons and spacers are left out.
        hasGif:
          type:
          - boolean
          - 'null'
        darkMode:
          type:
          - boolean
          - 'null'
          description: Whether the email ships custom `prefers-color-scheme` dark styles.
        fonts:
          type: array
          items:
            type: string
          description: Most used font families, up to 3.
        columns:
          type:
          - string
          - 'null'
          enum:
          - single
          - multi
          - null
        format:
          type:
          - string
          - 'null'
          enum:
          - plain
          - text_heavy
          - balanced
          - visual
          - null
        voice:
          type:
          - string
          - 'null'
          enum:
          - friendly
          - professional
          - playful
          - urgent
          - inspirational
          - informative
          - personal
          - null
        language:
          type:
          - string
          - 'null'
          description: BCP 47 language code, such as `en`.
        structure:
          type: array
          items:
            type: string
          description: The email's beats in order, such as "Logo header" and "Primary button".
        takeaways:
          type: array
          items:
            type: string
          description: Why the email works, as observations about its choices. Never performance claims.
        sender:
          type:
          - object
          - 'null'
          description: The sender as shown on gallery pages, with personal details redacted. `null` when unknown.
          properties:
            name:
              type:
              - string
              - 'null'
            address:
              type:
              - string
              - 'null'
    GalleryBrandRequest:
      type: object
      properties:
        id:
          type: string
        domain:
          type: string
          example: competitor.com
        note:
          type:
          - string
          - 'null'
        status:
          type: string
          enum:
          - requested
          - collecting
          - available
          - declined
          description: '`requested`: not in the gallery yet. `collecting`: the brand is added and its emails are being collected. `available`: its emails are in the gallery. `declined`: it will not be added; see `declineReason`.'
        declineReason:
          type:
          - string
          - 'null'
        requestedAt:
          type: string
          format: date-time
        brand:
          type:
          - object
          - 'null'
          description: The gallery brand, once its emails are in the gallery.
          properties:
            name:
              type: string
            slug:
              type: string
            url:
              type: string
    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
    GalleryBrandRequestResult:
      type: object
      properties:
        success:
          type: boolean
          example: true
        created:
          type: boolean
          description: False when your company had already requested this domain.
        request:
          $ref: '#/components/schemas/GalleryBrandRequest'
        message:
          type: string
    GalleryWatchResult:
      type: object
      properties:
        success:
          type: boolean
          example: true
        created:
          type: boolean
          description: False when your company already watched this domain.
        watch:
          $ref: '#/components/schemas/GalleryWatchedBrand'
        message:
          type: string
    GalleryWatchedBrand:
      type: object
      properties:
        id:
          type: string
          description: Watch ID. The same row is a brand request, so this is also its request ID.
        domain:
          type: string
          example: linear.app
        note:
          type:
          - string
          - 'null'
        status:
          type: string
          enum:
          - requested
          - collecting
          - available
          - declined
          description: '`available`: its emails are in the gallery. `requested`: not in the gallery yet. `collecting`: the brand is added and its emails are being collected. `declined`: it will not be added; see `declineReason`.'
        declineReason:
          type:
          - string
          - 'null'
        watchedAt:
          type: string
          format: date-time
        emailCount:
          type: integer
          description: The brand's emails in the gallery. 0 unless `available`.
        latestEmailAt:
          type:
          - string
          - 'null'
          format: date-time
          description: When its newest email in the gallery was sent. `null` unless `available`.
        brand:
          type:
          - object
          - 'null'
          description: The gallery brand, once its emails are in the gallery.
          properties:
            name:
              type: string
            slug:
              type: string
            url:
              type: string
    GalleryWatchedBrandEmail:
      type: object
      properties:
        id:
          type: string
        subject:
          type:
          - string
          - 'null'
        preheader:
          type:
          - string
          - 'null'
        type:
          type:
          - string
          - 'null'
        subtype:
          type:
          - string
          - 'null'
        sentAt:
          type: string
          format: date-time
        collectedAt:
          type: string
          format: date-time
          description: When the gallery received the email, usually a few hours after `sentAt`.
        analysis:
          $ref: '#/components/schemas/GalleryEmailAnalysis'
        brand:
          type: object
          properties:
            name:
              type: string
            domain:
              type: string
            slug:
              type: string
        url:
          type: string
          description: The email's gallery page. Also accepted as `url` by [Create Template from Example](/api-reference/templates/create-from-example).
    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:
    ValidationError:
      description: The request body or parameters are invalid
      content:
        application/json:
          schema:
            type: object
            properties:
              success:
                type: boolean
                example: false
              error:
                type: string
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: API key passed as Bearer token