openapi: 3.2.0
info:
  title: SendClean Email Tracking Domains API
  description: 'The SendClean Email API is a RESTful HTTP API for sending transactional emails, managing SMTP users,

    sending/tracking domains, webhooks, and account information.


    ## Base URL

    All API calls are relative to:

    ```

    https://api.sendclean.net/v1.0

    ```


    ## Authentication

    Every request requires `owner_id` and `token` fields in the request body (JSON POST).


    ## Request Format

    - All API calls use **HTTP POST** (except `sendTemplateHTTPGet` which uses HTTP GET).

    - Request bodies must be `Content-Type: application/json`.

    - Any non-200 HTTP response code indicates an error.


    ## Response Format

    All responses return JSON with a `status` field of either `"success"` or `"error"`.


    ## Error Types

    | Type | Description |

    |------|-------------|

    | `ValidationError` | Invalid or missing required parameters |

    | `GeneralError` | Unexpected server-side error |

    | `AuthenticationError` | `owner_id` and `token` did not match |

    '
  version: 1.0.0
  contact:
    email: support@sendclean.com
servers:
- url: https://api.sendclean.net/v1.0
  description: Production API server
tags:
- name: Tracking Domains
  description: Add, check, list, and delete tracking domains
paths:
  /settings/addTrackingDomain:
    post:
      tags:
      - Tracking Domains
      summary: Add a tracking domain
      description: Registers a custom tracking domain for open and click tracking.
      operationId: addTrackingDomain
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DomainRequest'
            example:
              owner_id: example id
              token: example token
              domain: track.abc.com
      responses:
        '200':
          description: Tracking domain added
          content:
            application/json:
              schema:
                oneOf:
                - $ref: '#/components/schemas/SuccessResponse'
                - $ref: '#/components/schemas/ErrorResponse'
              examples:
                success:
                  value:
                    status: success
                    message: Tracking Domain Added
  /settings/checkTrackingDomain:
    post:
      tags:
      - Tracking Domains
      summary: Check tracking domain CNAME
      description: Validates whether the CNAME record for the tracking domain is correctly configured.
      operationId: checkTrackingDomain
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DomainRequest'
            example:
              owner_id: example id
              token: example token
              domain: track.abc.com
      responses:
        '200':
          description: Tracking domain check result
          content:
            application/json:
              schema:
                oneOf:
                - $ref: '#/components/schemas/CheckTrackingDomainResponse'
                - $ref: '#/components/schemas/ErrorResponse'
              examples:
                success:
                  value:
                    status: success
                    domain: abc.com
                    valid_tracking: 'Yes'
                    cname:
                      valid: 'Yes'
  /settings/listTrackingDomain:
    post:
      tags:
      - Tracking Domains
      summary: List tracking domains
      description: Returns all tracking domains registered to the account.
      operationId: listTrackingDomains
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AuthFields'
            example:
              owner_id: example id
              token: example token
      responses:
        '200':
          description: List of tracking domains
          content:
            application/json:
              schema:
                oneOf:
                - $ref: '#/components/schemas/ListTrackingDomainResponse'
                - $ref: '#/components/schemas/ErrorResponse'
  /settings/deleteTrackingDomain:
    post:
      tags:
      - Tracking Domains
      summary: Delete a tracking domain
      description: Removes the specified tracking domain from the account.
      operationId: deleteTrackingDomain
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DomainRequest'
            example:
              owner_id: example id
              token: example token
              domain: track.abc.com
      responses:
        '200':
          description: Tracking domain deleted
          content:
            application/json:
              schema:
                oneOf:
                - $ref: '#/components/schemas/SuccessResponse'
                - $ref: '#/components/schemas/ErrorResponse'
              examples:
                success:
                  value:
                    status: success
                    message: Tracking Domain Deleted
components:
  schemas:
    DomainRequest:
      allOf:
      - $ref: '#/components/schemas/AuthFields'
      - type: object
        required:
        - domain
        properties:
          domain:
            type: string
            description: Fully qualified domain name
            example: abc.com
    SuccessResponse:
      type: object
      properties:
        status:
          type: string
          enum:
          - success
          example: success
        message:
          type: string
          example: Operation successful
    ErrorResponse:
      type: object
      properties:
        status:
          type: string
          enum:
          - error
          example: error
        code:
          type: integer
          example: -1
        name:
          type: string
          enum:
          - ValidationError
          - GeneralError
          - AuthenticationError
          example: AuthenticationError
        message:
          type: string
          example: Token MissMatch
    AuthFields:
      type: object
      required:
      - owner_id
      - token
      properties:
        owner_id:
          type: string
          description: A valid SendClean User ID
          example: example_owner_id
        token:
          type: string
          description: A valid API token
          example: example_token
    ListTrackingDomainResponse:
      type: object
      properties:
        status:
          type: string
          enum:
          - success
        tracking_domain_list:
          type: array
          items:
            $ref: '#/components/schemas/TrackingDomainListEntry'
    TrackingDomainListEntry:
      type: object
      properties:
        domain:
          type: string
          example: abc.com
        create_date:
          type: integer
          format: int64
          description: Creation timestamp in microseconds
          example: 67457775764
        cname:
          type: object
          properties:
            valid:
              type: string
              enum:
              - 'Yes'
              - 'No'
    CheckTrackingDomainResponse:
      type: object
      properties:
        status:
          type: string
          enum:
          - success
        domain:
          type: string
          example: abc.com
        valid_tracking:
          type: string
          enum:
          - 'Yes'
          - 'No'
          example: 'Yes'
        cname:
          type: object
          properties:
            valid:
              type: string
              enum:
              - 'Yes'
              - 'No'
              example: 'Yes'