Sequenzy Tracking Settings API

openapi: 3.2.0
info:
  title: Sequenzy Tracking Settings 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: Tracking Settings
paths:
  /tracking-settings:
    get:
      operationId: getTrackingSettings
      summary: Get tracking settings
      description: Returns account-wide and Transactional API open/click tracking flags, unsubscribe tracking, attribution, UTM tagging, tracking domain, inbound reply settings and signup consent settings.
      tags:
      - Tracking Settings
      responses:
        '200':
          description: Tracking configuration returned
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TrackingSettings'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '503':
          $ref: '#/components/responses/TransientDatabaseUnavailable'
    patch:
      operationId: updateTrackingSettings
      summary: Update tracking settings
      description: Updates the account-wide and Transactional API tracking defaults - open, click, and unsubscribe tracking, strict bot filtering, the default attribution window, and automatic UTM tagging - plus the double opt-in requirement for new contacts. Applies to emails sent afterwards; already-sent emails keep the links they were rendered with. Reply tracking is updated through the company endpoint.
      tags:
      - Tracking Settings
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              properties:
                openTrackingEnabled:
                  type: boolean
                  description: Whether to embed the open-tracking pixel.
                clickTrackingEnabled:
                  type: boolean
                  description: Whether to rewrite links through the click-tracking redirect.
                strictBotFilteringEnabled:
                  type: boolean
                  description: Opt-in aggressive bot detection (strict user-agent patterns, datacenter and Microsoft Azure IPs, fast campaign and sequence clicks from IPs clicking other recipients' emails, cross-send IP sweeps). Off by default; enabling it can lower reported open and click rates.
                unsubscribeTrackingEnabled:
                  type: boolean
                  description: Whether to track unsubscribe link clicks. When false, Sequenzy unsubscribe links go directly to https://sequenzy.com, even with a custom tracking domain. Actual unsubscribes and their email attribution are still recorded.
                emailContentStorageEnabled:
                  type: boolean
                  description: Whether to keep each sent email's rendered content and subject, and the IP address, user agent and country of opens and clicks. When false, sent-email records keep no body once the email is sent and store the email's name (campaign, template or sequence) in place of its subject, opens and clicks store no IP address, user agent or country, and view-in-browser links stop working. Body and subject rules apply to emails sent afterwards; IP address, user agent and country follow the setting at each open or click.
                defaultAttributionWindowHours:
                  type: integer
                  minimum: 1
                  maximum: 720
                  description: Default revenue attribution window in hours.
                doubleOptInEnabled:
                  type: boolean
                  description: Whether new contacts must confirm by email before they become subscribed. This is the account-wide default that the per-request optInMode on subscriber creation overrides. Enabling it requires a sender profile and provisions the confirmation email automatically; it does not change contacts that are already active.
                doubleOptInRedirectUrl:
                  type:
                  - string
                  - 'null'
                  maxLength: 500
                  description: Where the hosted confirmation page sends subscribers after they confirm. Must be an http(s) URL of at most 500 characters after normalization; a bare domain is normalized to https. Null (or an empty string) clears it, keeping subscribers on the confirmation page branded with the company's name, logo, and colors.
                autoUtmEnabled:
                  type: boolean
                  description: Whether UTM parameters are appended to outbound links automatically. Enabling this with no stored parameters seeds the platform defaults.
                autoUtmSettings:
                  type:
                  - object
                  - 'null'
                  description: UTM templates merged over the stored ones. Null resets every parameter to the platform defaults; a null field stops that parameter being emitted.
                  properties:
                    source:
                      type:
                      - string
                      - 'null'
                    medium:
                      type:
                      - string
                      - 'null'
                    campaign:
                      type:
                      - string
                      - 'null'
                    content:
                      type:
                      - string
                      - 'null'
                    term:
                      type:
                      - string
                      - 'null'
                transactionalOpenTrackingEnabled:
                  type: boolean
                  description: Open tracking default for sends through the Send Email API. Account-wide open tracking must also be enabled; per-send trackingSettings can only opt out.
                transactionalClickTrackingEnabled:
                  type: boolean
                  description: Click tracking default for sends through the Send Email API. Account-wide click tracking must also be enabled; per-send trackingSettings can only opt out.
      responses:
        '200':
          description: Tracking configuration updated
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/TrackingSettings'
                - type: object
                  properties:
                    message:
                      type: string
        '400':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Company not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
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:
    TrackingSettings:
      type: object
      properties:
        success:
          type: boolean
          example: true
        tracking:
          type: object
          properties:
            openTrackingEnabled:
              type: boolean
            clickTrackingEnabled:
              type: boolean
            strictBotFilteringEnabled:
              type: boolean
              description: Opt-in aggressive bot detection (strict user-agent patterns, datacenter and Microsoft Azure IPs, fast campaign and sequence clicks from IPs clicking other recipients' emails, cross-send IP sweeps). Off by default; enabling it can lower reported open and click rates.
            unsubscribeTrackingEnabled:
              type: boolean
              description: Whether to track unsubscribe link clicks. When false, Sequenzy unsubscribe links go directly to https://sequenzy.com, even with a custom tracking domain. Actual unsubscribes and their email attribution are still recorded.
            emailContentStorageEnabled:
              type: boolean
              description: Whether to keep each sent email's rendered content and subject, and the IP address, user agent and country of opens and clicks. When false, sent-email records keep no body once the email is sent and store the email's name (campaign, template or sequence) in place of its subject, opens and clicks store no IP address, user agent or country, and view-in-browser links stop working. Body and subject rules apply to emails sent afterwards; IP address, user agent and country follow the setting at each open or click.
            defaultAttributionWindowHours:
              type: integer
            transactionalOpenTrackingEnabled:
              type: boolean
              description: Open tracking default for sends through the Send Email API. Account-wide open tracking must also be enabled; per-send trackingSettings can only opt out.
            transactionalClickTrackingEnabled:
              type: boolean
              description: Click tracking default for sends through the Send Email API. Account-wide click tracking must also be enabled; per-send trackingSettings can only opt out.
        consent:
          type: object
          description: Signup consent settings, as opposed to engagement measurement.
          properties:
            doubleOptInEnabled:
              type: boolean
              description: Whether new contacts must confirm by email before they become subscribed. When on, contacts added by forms, the API, and integrations start pending and are never sent marketing email until they confirm.
            doubleOptInEmailId:
              type:
              - string
              - 'null'
              description: Confirmation email sent to pending contacts. Null when double opt-in has never been enabled; enabling it provisions one automatically.
            doubleOptInRedirectUrl:
              type:
              - string
              - 'null'
              description: Where the hosted confirmation page sends subscribers after they confirm. Null keeps them on the branded confirmation page.
        autoUtm:
          type: object
          properties:
            enabled:
              type: boolean
            settings:
              type: object
              additionalProperties: true
        trackingDomain:
          type:
          - object
          - 'null'
          description: Company tracking domain, used by every sending domain for tracked links and opens. Null when links use the shared Sequenzy tracking domain; links also use it while the tracking domain is not verified. Manage it with the Tracking Domain endpoints.
          properties:
            domain:
              type: string
            status:
              type: string
            sslStatus:
              type:
              - string
              - 'null'
            verifiedAt:
              type:
              - string
              - 'null'
              format: date-time
            lastCheckedAt:
              type:
              - string
              - 'null'
              format: date-time
            error:
              type:
              - string
              - 'null'
        replyTracking:
          type: object
          properties:
            inboundEmailEnabled:
              type: boolean
            inboundReplyDomainMode:
              type: string
              enum:
              - sequenzy
              - custom
              description: Where reply addresses in your emails point. custom uses your verified receiving domain for emails from every sending domain, and inbound.sequenzy.com until one is verified; sequenzy always uses inbound.sequenzy.com. Adding your first receiving domain sets it to custom.
            forwardReplies:
              type: boolean
    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
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: API key passed as Bearer token