Sequenzy Email Sends API

openapi: 3.2.0
info:
  title: Sequenzy Email Sends 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 Sends
paths:
  /email-sends:
    get:
      summary: List sent emails
      description: Lists the recent 14-day delivery history with dashboard-equivalent subject, recipient, status, type, bounce, source, pagination, and sorting filters. Pending, successful, and failed test sends are listed with `isTestEmail` set to true. Copied-recipient bookkeeping rows remain hidden except bounced or complained copied recipients.
      operationId: listEmailSends
      tags:
      - Email Sends
      parameters:
      - name: search
        in: query
        schema:
          type: string
        description: Case-insensitive subject/title or recipient search. `q` is accepted as an alias.
      - name: q
        in: query
        deprecated: true
        schema:
          type: string
        description: Compatibility alias for `search`.
      - name: subject
        in: query
        schema:
          type: string
        description: Case-insensitive subject/title filter. `title` is accepted as an alias.
      - name: title
        in: query
        deprecated: true
        schema:
          type: string
        description: Compatibility alias for `subject`.
      - name: recipient
        in: query
        schema:
          type: string
        description: Case-insensitive recipient email filter.
      - name: status
        in: query
        schema:
          type: string
          enum:
          - pending
          - sent
          - delivered
          - opened
          - clicked
          - bounced
          - complained
          - failed
          - suppressed
        description: Delivery status. Opened includes clicked deliveries.
      - name: emailType
        in: query
        schema:
          type: string
          enum:
          - campaign
          - transactional
          - sequence
      - name: bounceType
        in: query
        description: Transient is every temporary bounce. Blocked is the part the receiving server refused over content, policy or reputation, and Soft is the rest.
        schema:
          type: string
          enum:
          - Permanent
          - Transient
          - Soft
          - Blocked
      - name: campaignId
        in: query
        schema:
          type: string
      - name: transactionalEmailId
        in: query
        schema:
          type: string
      - name: automationId
        in: query
        schema:
          type: string
      - name: automationNodeId
        in: query
        schema:
          type: string
        description: Filter to one email step of a sequence. Take the node ID from the `steps` array of the sequence metrics endpoint. Combined with `automationId` the two intersect.
      - name: mailboxProvider
        in: query
        schema:
          type: string
        description: Recipient mailbox provider, with the same values and domain classification as the analytics `mailboxProvider` filter (e.g. gmail, microsoft, yahoo, icloud, orange). `other` matches every recipient domain outside the named providers. Case-insensitive; an unknown value returns 400.
      - name: listId
        in: query
        schema:
          type: string
        description: Only sends to active subscribers currently on this list, the same audience the analytics list filter uses. A list ID from another company matches no rows.
      - name: days
        in: query
        schema:
          type: integer
          minimum: 1
          maximum: 14
          default: 14
      - name: page
        in: query
        schema:
          type: integer
          minimum: 1
          default: 1
      - name: limit
        in: query
        schema:
          type: integer
          minimum: 1
          maximum: 100
          default: 20
      - name: sortField
        in: query
        schema:
          type: string
          enum:
          - recipientEmail
          - subject
          - status
          - eventAt
          - sentAt
          - createdAt
          default: createdAt
      - name: sortOrder
        in: query
        schema:
          type: string
          enum:
          - asc
          - desc
          default: desc
      responses:
        '200':
          description: Paginated sent-email history
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  retentionDays:
                    type: integer
                    example: 14
                  emailSends:
                    type: array
                    items:
                      allOf:
                      - $ref: '#/components/schemas/EmailSend'
                      - type: object
                        properties:
                          eventAt:
                            type: string
                            format: date-time
                          opened:
                            type: boolean
                          clicked:
                            type: boolean
                  pagination:
                    $ref: '#/components/schemas/Pagination'
        '400':
          description: Invalid filter or pagination value
          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'
        '503':
          $ref: '#/components/responses/TransientDatabaseUnavailable'
  /email-sends/{emailSendId}:
    get:
      summary: Get email send
      description: Gets an email delivery snapshot by ID, including queued and test sends, the stored HTML body when available, and retained ClickHouse events when the short-lived row has been cleaned up. Test sends appear in sent-email history and are available through this exact-ID endpoint while their row is retained.
      operationId: getEmailSend
      tags:
      - Email Sends
      parameters:
      - name: emailSendId
        in: path
        required: true
        schema:
          type: string
        description: Email send ID
      responses:
        '200':
          description: Email send found
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  source:
                    type: string
                    enum:
                    - database
                    - clickhouse_events
                  message:
                    type:
                    - string
                    - 'null'
                  emailSend:
                    $ref: '#/components/schemas/EmailSend'
                  events:
                    type: array
                    items:
                      $ref: '#/components/schemas/EmailSendEvent'
        '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 send not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal server error
          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:
    EmailSendEvent:
      type: object
      properties:
        id:
          type: string
          example: evt_123
        emailSendId:
          type: string
          example: send_123
        companyId:
          type: string
          example: company_123
        campaignId:
          type:
          - string
          - 'null'
        transactionalEmailId:
          type:
          - string
          - 'null'
        subscriberId:
          type:
          - string
          - 'null'
        email:
          type:
          - string
          - 'null'
          format: email
        emailName:
          type:
          - string
          - 'null'
          example: Welcome
        emailType:
          type:
          - string
          - 'null'
          enum:
          - campaign
          - transactional
          - sequence
          - null
          description: Send-source category retained for analytics compatibility. Use deliveryPolicy for the actual marketing or transactional policy.
        deliveryPolicy:
          type:
          - string
          - 'null'
          enum:
          - marketing
          - transactional
          - null
          description: Delivery policy used for suppression and compliance behavior, or null when retained legacy events cannot prove it.
        abTestId:
          type:
          - string
          - 'null'
        abTestVariantId:
          type:
          - string
          - 'null'
        eventType:
          type: string
          example: delivery
        bounceType:
          type:
          - string
          - 'null'
        bounceSubType:
          type:
          - string
          - 'null'
        complaintType:
          type:
          - string
          - 'null'
        clickedUrl:
          type:
          - string
          - 'null'
        ipAddress:
          type:
          - string
          - 'null'
        userAgent:
          type:
          - string
          - 'null'
        countryCode:
          type:
          - string
          - 'null'
        metadata:
          type: object
          additionalProperties: true
          description: Event details. Receiver replies (recipients[].diagnosticCode) are masked for bounced and blocked outcomes, generic for failed ones, and kept for delays only when the sender caused them. Sending infrastructure is never included.
        eventTime:
          type: string
          format: date-time
    Pagination:
      type: object
      properties:
        page:
          type: integer
          example: 1
        limit:
          type: integer
          example: 20
        total:
          type: integer
          example: 100
        totalPages:
          type: integer
          example: 5
    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
    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
    EmailSend:
      type: object
      properties:
        id:
          type: string
          example: send_123
        companyId:
          type: string
          example: company_123
        type:
          type:
          - string
          - 'null'
          enum:
          - campaign
          - transactional
          - sequence
          - null
          description: Send-source category. API/MCP sends use transactional here even when their delivery policy is marketing.
        emailType:
          type:
          - string
          - 'null'
          enum:
          - marketing
          - transactional
          - null
          description: Delivery policy used for suppression and compliance behavior, or null when retained legacy data cannot prove it.
        isTransactional:
          type:
          - boolean
          - 'null'
          description: Stored delivery-policy snapshot. Prefer emailType for a normalized value.
        isTestEmail:
          type: boolean
          description: Whether this delivery was a test send hidden from normal sent-email history.
        campaignId:
          type:
          - string
          - 'null'
        transactionalEmailId:
          type:
          - string
          - 'null'
        automationNodeId:
          type:
          - string
          - 'null'
        automationTokenId:
          type:
          - string
          - 'null'
        abTestVariantId:
          type:
          - string
          - 'null'
        subscriberId:
          type:
          - string
          - 'null'
        subscriberExternalId:
          type:
          - string
          - 'null'
          description: Customer-owned subscriber ID captured from a single-recipient transactional send.
        recipientEmail:
          type:
          - string
          - 'null'
          format: email
        additionalRecipients:
          type:
          - object
          - 'null'
          description: Full recipient envelope for multi-recipient transactional sends, as actually sent. Null for single-recipient sends.
          properties:
            to:
              type: array
              items:
                type: string
                format: email
            cc:
              type: array
              items:
                type: string
                format: email
            bcc:
              type: array
              items:
                type: string
                format: email
        subject:
          type:
          - string
          - 'null'
          example: Welcome
        senderEmail:
          type:
          - string
          - 'null'
          format: email
        senderName:
          type:
          - string
          - 'null'
        authenticatedDomainId:
          type:
          - string
          - 'null'
        originalReplyTo:
          type:
          - string
          - 'null'
          description: Resolved reply destination, optionally including a display name. When reply tracking is disabled, this is the sent Reply-To header. When reply tracking is enabled, the sent header is a unique trackable address and this value is the forwarding destination.
        sendingIpAddress:
          type:
          - string
          - 'null'
          description: Always null. Sending IPs are not shared with customers.
        observedSendingIpAddress:
          type:
          - string
          - 'null'
          description: Always null. Sending IPs are not shared with customers.
        sesMessageId:
          type:
          - string
          - 'null'
        status:
          type: string
          enum:
          - pending
          - sent
          - delivered
          - opened
          - clicked
          - bounced
          - complained
          - failed
          - suppressed
        outcome:
          type:
          - string
          - 'null'
          enum:
          - bounced
          - blocked
          - delayed
          - failed
          - null
          description: 'Why the email did not arrive. "bounced": the address cannot take mail. "blocked": the receiver refused because of the sender (spam or content, the sending domain, policy, or its SPF, DKIM or DMARC). "delayed": still retrying. "failed": we could not deliver it. Null for emails that arrived or have not finished.'
        reason:
          type:
          - string
          - 'null'
          description: One plain sentence about the outcome, with the receiver's status code when there is one. Null when outcome is null.
        bounceType:
          type:
          - string
          - 'null'
        bounceSubType:
          type:
          - string
          - 'null'
        complaintType:
          type:
          - string
          - 'null'
        suppressionReason:
          type:
          - string
          - 'null'
          enum:
          - bounced
          - complaint
          - unsubscribed
          - null
        errorMessage:
          type:
          - string
          - 'null'
        internalFailureCode:
          type:
          - string
          - 'null'
          enum:
          - transport_exhausted
          - admin_bounce
          - crash_orphaned_claim
          - null
          description: 'Why a send reached status "failed". Present only for terminal delivery failures, each of which has outcome "failed": "transport_exhausted" means we could not deliver the email; "admin_bounce" means the message was withdrawn before delivery; "crash_orphaned_claim" means sending stopped before the message was confirmed as handed off. None of them is a bounce: the address is still valid, stays subscribed, and is not suppressed. New codes can be added over time, so treat an unrecognized value as a generic failure rather than rejecting the response.'
        emailBody:
          type:
          - string
          - 'null'
          description: Stored HTML body. Null when the email send row has been cleaned up.
        isCopiedRecipient:
          type: boolean
          description: Whether this is an auxiliary CC/BCC delivery record whose content and engagement belong to a primary email send.
        primaryEmailSendId:
          type:
          - string
          - 'null'
          description: Primary email send ID for a copied-recipient delivery, or null for ordinary sends and when the primary record is unavailable.
        sentAt:
          type:
          - string
          - 'null'
          format: date-time
        deliveredAt:
          type:
          - string
          - 'null'
          format: date-time
        bouncedAt:
          type:
          - string
          - 'null'
          format: date-time
        complainedAt:
          type:
          - string
          - 'null'
          format: date-time
        openedAt:
          type:
          - string
          - 'null'
          format: date-time
        clickedAt:
          type:
          - string
          - 'null'
          format: date-time
        unsubscribedAt:
          type:
          - string
          - 'null'
          format: date-time
        suppressedAt:
          type:
          - string
          - 'null'
          format: date-time
        createdAt:
          type: string
          format: date-time
        subscriber:
          oneOf:
          - type: object
            properties:
              id:
                type: string
              email:
                type: string
                format: email
              firstName:
                type:
                - string
                - 'null'
              lastName:
                type:
                - string
                - 'null'
          - type: 'null'
        campaign:
          oneOf:
          - type: object
            properties:
              id:
                type: string
              name:
                type: string
          - type: 'null'
        automation:
          oneOf:
          - type: object
            properties:
              id:
                type: string
              name:
                type: string
          - type: 'null'
  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