SendClean Email API

openapi: 3.0.3
info:
  title: SendClean Email 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: SMTP Users
  description: Manage SMTP sub-users (create, edit, reset password, list)
- name: Sending Domains
  description: Add, verify, list, and delete sending domains
- name: Tracking Domains
  description: Add, check, list, and delete tracking domains
- name: Webhooks
  description: Configure event webhooks for email delivery events
- name: Messages
  description: Send transactional emails and retrieve message info
- name: Accounts
  description: Retrieve account/user details
components:
  schemas:
    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
    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
    SmtpUser:
      type: object
      properties:
        smtp_user_name:
          type: string
          example: smtps456546
        password:
          type: string
          example: cgvddgrsd
        status:
          type: string
          enum:
          - Enable
          - Disable
          example: Enable
        total_limit:
          type: integer
          example: 200
        hourly_limit:
          type: integer
          example: 20
    AddSmtpRequest:
      allOf:
      - $ref: '#/components/schemas/AuthFields'
      - type: object
        required:
        - total_limit
        - hourly_limit
        properties:
          total_limit:
            type: integer
            description: Total sending limit (positive integer)
            example: 100
          hourly_limit:
            type: integer
            description: Hourly sending limit (positive integer)
            example: 10
    AddSmtpResponse:
      type: object
      properties:
        status:
          type: string
          enum:
          - success
        message:
          type: string
          example: SMTP User Created
        smtp_user_name:
          type: string
          example: smtp12345
        smtp_password:
          type: string
          example: asfsf4w343
    EditSmtpRequest:
      allOf:
      - $ref: '#/components/schemas/AuthFields'
      - type: object
        required:
        - smtp_user_name
        properties:
          smtp_user_name:
            type: string
            description: A valid SMTP user name
            example: smtp12345
          total_limit:
            type: integer
            description: New total limit (positive integer)
            example: 80
          hourly_limit:
            type: integer
            description: New hourly limit (positive integer)
            example: 15
          status:
            type: string
            enum:
            - Enable
            - Disable
            description: Enable or disable the SMTP user
            example: Disable
    ResetSmtpPasswordRequest:
      allOf:
      - $ref: '#/components/schemas/AuthFields'
      - type: object
        required:
        - smtp_user_name
        properties:
          smtp_user_name:
            type: string
            description: A valid SMTP user name
            example: smtp12345
    ResetSmtpPasswordResponse:
      type: object
      properties:
        status:
          type: string
          enum:
          - success
        message:
          type: string
          example: password reseted
        smtp_user_name:
          type: string
          example: smtp12345
        smtp_password:
          type: string
          example: 2fg345gy6r7
    ListSmtpRequest:
      $ref: '#/components/schemas/AuthFields'
    ListSmtpResponse:
      type: object
      properties:
        status:
          type: string
          enum:
          - success
        smtp_list:
          type: array
          items:
            $ref: '#/components/schemas/SmtpUser'
    DomainRequest:
      allOf:
      - $ref: '#/components/schemas/AuthFields'
      - type: object
        required:
        - domain
        properties:
          domain:
            type: string
            description: Fully qualified domain name
            example: abc.com
    CheckSendingDomainResponse:
      type: object
      properties:
        status:
          type: string
          enum:
          - success
        domain:
          type: string
          example: abc.com
        dkim:
          type: object
          properties:
            valid:
              type: string
              enum:
              - 'Yes'
              - 'No'
              example: 'Yes'
        spf:
          type: object
          properties:
            valid:
              type: string
              enum:
              - 'Yes'
              - 'No'
              example: 'No'
        valid_signing:
          type: string
          enum:
          - 'Yes'
          - 'No'
          example: 'No'
    VerifySendingDomainRequest:
      allOf:
      - $ref: '#/components/schemas/AuthFields'
      - type: object
        required:
        - domain
        - mailbox
        properties:
          domain:
            type: string
            example: abc.com
          mailbox:
            type: string
            description: Mailbox name to send verification instructions to
            example: john
    SendingDomainListEntry:
      type: object
      properties:
        domain:
          type: string
          example: abc.com
        create_date:
          type: integer
          format: int64
          description: Creation timestamp in microseconds
          example: 67457775764
        dkim:
          type: object
          properties:
            valid:
              type: string
              enum:
              - 'Yes'
              - 'No'
        spf:
          type: object
          properties:
            valid:
              type: string
              enum:
              - 'Yes'
              - 'No'
        verify_domain:
          type: object
          properties:
            valid:
              type: string
              enum:
              - 'Yes'
              - 'No'
    ListSendingDomainResponse:
      type: object
      properties:
        status:
          type: string
          enum:
          - success
        sending_domain_list:
          type: array
          items:
            $ref: '#/components/schemas/SendingDomainListEntry'
    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'
    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'
    ListTrackingDomainResponse:
      type: object
      properties:
        status:
          type: string
          enum:
          - success
        tracking_domain_list:
          type: array
          items:
            $ref: '#/components/schemas/TrackingDomainListEntry'
    AddWebhookRequest:
      allOf:
      - $ref: '#/components/schemas/AuthFields'
      - type: object
        required:
        - url
        properties:
          url:
            type: string
            description: Webhook URL. Must respond with 'God bless you, SendClean'
            example: https://example.com/webhook
          event:
            type: string
            description: Comma-separated list of events to subscribe to
            example: send,open,click,soft_bounce,hard_bounce,spam
          description:
            type: string
            description: Human-readable description
            example: My webhook for open and click events
          store_log:
            type: string
            enum:
            - Enable
            - Disable
            example: Enable
    EditWebhookRequest:
      allOf:
      - $ref: '#/components/schemas/AuthFields'
      - type: object
        required:
        - webhook_id
        - url
        properties:
          webhook_id:
            type: string
            example: '424353445757557577457'
          url:
            type: string
            description: Updated webhook URL. Must respond with 'God bless you, SendClean'
            example: https://example.com/webhook
          event:
            type: string
            example: open,click
          description:
            type: string
            example: Updated description
          store_log:
            type: string
            enum:
            - Enable
            - Disable
    WebhookIdRequest:
      allOf:
      - $ref: '#/components/schemas/AuthFields'
      - type: object
        required:
        - webhook_id
        properties:
          webhook_id:
            type: string
            description: A valid webhook ID
            example: '424353445757557577457'
    KeyResetWebhookResponse:
      type: object
      properties:
        status:
          type: string
          enum:
          - success
        message:
          type: string
          example: Webhook key reseted
        webhook_id:
          type: string
          example: '424353445757557577457'
        key:
          type: string
          example: 2fg345gy6r7
    WebhookListEntry:
      type: object
      properties:
        webhook_id:
          type: string
          example: '424353445757557577457'
        url:
          type: string
          example: http://abc.com/wh1.php
        event:
          type: string
          example: open,click
        key:
          type: string
          example: cgvddgrsd
        store_log:
          type: string
          enum:
          - Enable
          - Disable
        description:
          type: string
          example: this webhook for only open and click
        create_date:
          type: integer
          format: int64
          example: 754453534
    ListWebhookResponse:
      type: object
      properties:
        status:
          type: string
          enum:
          - success
        webhook_list:
          type: array
          items:
            $ref: '#/components/schemas/WebhookListEntry'
    WebhookInfoResponse:
      type: object
      properties:
        status:
          type: string
          enum:
          - success
        webhook_data:
          type: object
          properties:
            webhook_id:
              type: string
              example: '405602261459333060372'
            url:
              type: string
              example: http://xyz.com/webhook3.php
            event:
              type: string
              example: open
            description:
              type: string
              example: webhook for open events
            store_log:
              type: string
              enum:
              - Enable
              - Disable
            key:
              type: string
              example: aVLnPysvkKUU95AFrb47Zr
            create_date:
              type: integer
              format: int64
              example: 1459333060
            last_success:
              type: integer
              format: int64
              description: Timestamp of last successful delivery
              example: 1459366666
            total_event:
              type: integer
              description: Total events sent to this webhook URL
              example: 23
    Recipient:
      type: object
      required:
      - email
      properties:
        email:
          type: string
          format: email
          example: recipient@example.com
        name:
          type: string
          description: Optional display name
          example: Recipient Name
        type:
          type: string
          enum:
          - to
          - cc
          - bcc
          default: to
          description: Header type for the recipient
    Attachment:
      type: object
      properties:
        type:
          type: string
          description: MIME type of the attachment
          example: text/plain
        name:
          type: string
          description: File name of the attachment
          example: myfile.txt
        content:
          type: string
          format: byte
          description: Base64-encoded content of the attachment
          example: ZXhhbXBsZSBmaWxl
    EmbeddedImage:
      type: object
      properties:
        type:
          type: string
          description: MIME type — must start with "image/"
          example: image/png
        name:
          type: string
          description: Content ID for the image. Reference in HTML as <img src="cid:THIS_VALUE">
          example: IMAGECID
        content:
          type: string
          format: byte
          description: Base64-encoded image content
          example: ZXhhbXBsZSBmaWxl
    MessageHeaders:
      type: object
      description: Optional custom headers for the message
      properties:
        Reply-To:
          type: string
          format: email
          example: reply@example.com
        X-Unique-Id:
          type: string
          description: Custom message ID for tracking via getMessageInfo
          example: my-unique-id-123
        X-STes-TrackOpen:
          type: string
          enum:
          - 'yes'
          - 'no'
          description: Enable or disable open tracking
        X-STes-TrackClick:
          type: string
          enum:
          - html
          - text
          - both
          - 'no'
          description: Enable or disable click tracking
        X-STes-Autotext:
          type: string
          enum:
          - 'yes'
          - 'no'
          description: Auto-generate plain-text version from HTML
        X-STes-AutoHtml:
          type: string
          enum:
          - 'yes'
          - 'no'
          description: Auto-generate HTML version from plain text
        X-STes-TrackingDomain:
          type: string
          description: Custom domain for tracking opens and clicks
        X-STes-SigningDomain:
          type: string
          description: Custom domain for SPF/DKIM signing
        X-STes-ReturnPathDomain:
          type: string
          description: Custom domain for the return-path
    SendMailMessage:
      type: object
      description: The message payload for sendMail
      properties:
        html:
          type: string
          description: Full HTML content of the email. Either html or text is required.
          example: <h1>Hello World</h1>
        text:
          type: string
          description: Full plain-text content of the email. Either html or text is required.
          example: Hello World
        subject:
          type: string
          description: Message subject line
          example: Your order confirmation
        from_email:
          type: string
          format: email
          description: Sender email address
          example: noreply@yourdomain.com
        from_name:
          type: string
          description: Optional sender display name
          example: SendClean Notifications
        to:
          type: array
          items:
            $ref: '#/components/schemas/Recipient'
        headers:
          $ref: '#/components/schemas/MessageHeaders'
        attachments:
          type: array
          items:
            $ref: '#/components/schemas/Attachment'
        images:
          type: array
          description: Embedded inline images (referenced by CID in HTML)
          items:
            $ref: '#/components/schemas/EmbeddedImage'
    SendMailRequest:
      allOf:
      - $ref: '#/components/schemas/AuthFields'
      - type: object
        required:
        - smtp_user_name
        - message
        properties:
          smtp_user_name:
            type: string
            description: A valid SMTP user name
            example: smtp12345
          message:
            $ref: '#/components/schemas/SendMailMessage'
    SendMailResponse:
      type: object
      properties:
        status:
          type: string
          enum:
          - success
        message:
          type: string
          example: message have been Queued ...
    TemplateMessage:
      type: object
      required:
      - template_id
      properties:
        template_id:
          type: string
          description: Previously created template ID
          example: Template_Id_123
        subject:
          type: string
          example: Order Confirmation
        from_email:
          type: string
          format: email
          example: noreply@yourdomain.com
        from_name:
          type: string
          example: SendClean Notifications
        to:
          type: array
          items:
            $ref: '#/components/schemas/Recipient'
        headers:
          $ref: '#/components/schemas/MessageHeaders'
        dynamic_value:
          type: object
          description: Key-value pairs to replace template placeholders. Field names are case-sensitive.
          additionalProperties:
            type: string
          example:
            NAME: John Doe
            Email: john@example.com
        attachments:
          type: array
          items:
            $ref: '#/components/schemas/Attachment'
        images:
          type: array
          items:
            $ref: '#/components/schemas/EmbeddedImage'
    SendTemplateRequest:
      allOf:
      - $ref: '#/components/schemas/AuthFields'
      - type: object
        required:
        - smtp_user_name
        - message
        properties:
          smtp_user_name:
            type: string
            example: smtp12345
          message:
            $ref: '#/components/schemas/TemplateMessage'
    MessageInfoRequest:
      allOf:
      - $ref: '#/components/schemas/AuthFields'
      - type: object
        required:
        - x_unique_id
        properties:
          x_unique_id:
            type: string
            description: The X-Unique-Id header value used when the message was sent
            example: test
          skip_page:
            type: integer
            description: Pagination offset (number of records to skip)
            default: 0
            example: 0
    OpenData:
      type: object
      properties:
        ip:
          type: array
          items:
            type: string
          example:
          - 0.0.0.0
          - 0.0.0.0
        ua:
          type: array
          items:
            type: string
          description: User-agent strings of the openers
        time:
          type: array
          items:
            type: integer
            format: int64
          description: Timestamps of each open event
    ClickData:
      type: object
      properties:
        ip:
          type: array
          items:
            type: string
          example:
          - 0.0.0.0
        ua:
          type: array
          items:
            type: string
          description: User-agent strings of the clickers
        time:
          type: array
          items:
            type: integer
            format: int64
          description: Timestamps of each click event
    MessageInfoEntry:
      type: object
      properties:
        subject:
          type: string
          example: this is subject ..
        sender:
          type: string
          format: email
          example: xyz@sendclean.com
        email:
          type: string
          format: email
          example: abc@sendclean.com
        sendFrom:
          type: string
          description: IP address the email was sent from
          example: 0.0.0.0
        mailSize:
          type: integer
          example: 1919
        attchSize:
          type: integer
          example: 0
        status:
          type: string
          enum:
          - delivered
          - soft_bounce
          - hard_bounce
          - spam
          - open
          - click
          - send
          example: delivered
        time:
          type: integer
          format: int64
          description: Send timestamp in milliseconds
          example: 1458034022169
        open:
          type: integer
          description: Total open count
          example: 1
        openData:
          $ref: '#/components/schemas/OpenData'
        click:
          type: integer
          description: Total click count
          example: 1
        clickData:
          $ref: '#/components/schemas/ClickData'
    MessageInfoResponse:
      type: object
      properties:
        status:
          type: string
          enum:
          - success
        message_data:
          type: array
          items:
            $ref: '#/components/schemas/MessageInfoEntry'
    AccountDetailRequest:
      $ref: '#/components/schemas/AuthFields'
    AccountDetailResponse:
      type: object
      properties:
        status:
          type: string
          enum:
          - success
        user_details:
          type: object
          description: Account and user detail fields (varies by plan)
          additionalProperties: true
paths:
  /settings/addSmtp:
    post:
      tags:
      - SMTP Users
      summary: Add a new SMTP user
      description: Creates a new SMTP sub-user with defined sending limits.
      operationId: addSmtpUser
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AddSmtpRequest'
            example:
              owner_id: example id
              token: example token
              total_limit: 100
              hourly_limit: 10
      responses:
        '200':
          description: SMTP user created successfully
          content:
            application/json:
              schema:
                oneOf:
                - $ref: '#/components/schemas/AddSmtpResponse'
                - $ref: '#/components/schemas/ErrorResponse'
              examples:
                success:
                  summary: Successful response
                  value:
                    status: success
                    message: SMTP User Created
                    smtp_user_name: smtp12345
                    smtp_password: asfsf4w343
                error:
                  summary: Authentication error
                  value:
                    status: error
                    code: -1
                    name: AuthenticationError
                    message: Token MissMatch
  /settings/editSmtp:
    post:
      tags:
      - SMTP Users
      summary: Edit an existing SMTP user
      description: Updates the sending limits or status of an SMTP sub-user.
      operationId: editSmtpUser
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EditSmtpRequest'
            example:
              owner_id: example id
              token: example token
              smtp_user_name: smtp12345
              total_limit: 80
              hourly_limit: 15
              status: Disable
      responses:
        '200':
          description: SMTP user updated successfully
          content:
            application/json:
              schema:
                oneOf:
                - $ref: '#/components/schemas/SuccessResponse'
                - $ref: '#/components/schemas/ErrorResponse'
              examples:
                success:
                  value:
                    status: success
                    message: SMTP User Updated
                error:
                  value:
                    status: error
                    code: -1
                    name: AuthenticationError
                    message: Token MissMatch
  /settings/resetSmtpPassword:
    post:
      tags:
      - SMTP Users
      summary: Reset SMTP user password
      description: Generates a new password for the specified SMTP sub-user.
      operationId: resetSmtpPassword
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ResetSmtpPasswordRequest'
            example:
              owner_id: example id
              token: example token
              smtp_user_name: smtp12345
      responses:
        '200':
          description: Password reset successfully
          content:
            application/json:
              schema:
                oneOf:
                - $ref: '#/components/schemas/ResetSmtpPasswordResponse'
                - $ref: '#/components/schemas/ErrorResponse'
              examples:
                success:
                  value:
                    status: success
                    message: password reseted
                    smtp_user_name: smtp12345
                    smtp_password: 2fg345gy6r7
  /settings/listSmtp:
    post:
      tags:
      - SMTP Users
      summary: List all SMTP users
      description: Returns a list of all SMTP sub-users associated with the account.
      operationId: listSmtpUsers
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AuthFields'
            example:
              owner_id: example id
              token: example token
      responses:
        '200':
          description: List of SMTP users
          content:
            application/json:
              schema:
                oneOf:
                - $ref: '#/components/schemas/ListSmtpResponse'
                - $ref: '#/components/schemas/ErrorResponse'
  /settings/addSendingDomain:
    post:
      tags:
      - Sending Domains
      summary: Add a sending domain
      description: Registers a new sending domain to the account.
      operationId: addSendingDomain
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DomainRequest'
            example:
              owner_id: example id
              token: example token
              domain: abc.com
      responses:
        '200':
          description: Sending domain added
          content:
            application/json:
              schema:
                oneOf:
                - $ref: '#/components/schemas/SuccessResponse'
                - $ref: '#/components/schemas/ErrorResponse'
              examples:
                success:
                  value:
                    status: success
                    message: Sending Domain Added
  /settings/checkSendingDomain:
    post:
      tags:
      - Sending Domains
      summary: Verify DKIM and SPF records
      description: Checks whether DKIM and SPF DNS records are correctly configured for the domain.
      operationId: checkSendingDomain
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DomainRequest'
            example:
              owner_id: example id
              token: example token
              domain: abc.com
      responses:
        '200':
          description: Domain check result
          content:
            application/json:
              schema:
                oneOf:
                - $ref: '#/components/schemas/CheckSendingDomainResponse'
                - $ref: '#/components/schemas/ErrorResponse'
              examples:
                success:
                  value:
                    status: success
                    domain: abc.com
                    dkim:
                      valid: 'Yes'
                    spf:
                      valid: 'No'
                    valid_signing: 'No'
  /settings/verifySendingDomain:
    post:
      tags:
      - Sending Domains
      summary: Verify sending domain via email
      description: Sends a verification instruction email to `mailbox@domain`.
      operationId: verifySendingDomain
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/VerifySendingDomainRequest'
            example:
              owner_id: example id
              token: example token
              domain: abc.com
              mailbox: john
      responses:
        '200':
          description: Verification email sent
          content:
            application/json:
              schema:
                oneOf:
                - $ref: '#/components/schemas/SuccessResponse'
                - $ref: '#/components/schemas/ErrorResponse'
              examples:
                success:
                  value:
                    status: success
                    message: Verification instruction has been sent to john@abc.com
  /settings/listSendingDomain:
    post:
      tags:
      - Sending Domains
      summary: List sending domains
      description: Returns all sending domains registered to the account with their DNS validation status.
      operationId: listSendingDomains
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AuthFields'
            example:
              owner_id: example id
              token: example token
      responses:
        '200':
          description: List of sending domains
          content:
            application/json:
              schema:
                oneOf:
                - $ref: '#/components/schemas/ListSendingDomainResponse'
                - $ref: '#/components/schemas/ErrorResponse'
  /settings/deleteSendingDomain:
    post:
      tags:
      - Sending Domains
      summary: Delete a sending domain
      description: Removes the specified sending domain from the account.
      operationId: deleteSendingDomain
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DomainRequest'
            example:
              owner_id: example id
              token: example token
              domain: abc.com
      responses:
        '200':
          description: Sending domain deleted
          content:
            application/json:
              schema:
                oneOf:
                - $ref: '#/components/schemas/SuccessResponse'
                - $ref: '#/components/schemas/E

# --- truncated at 32 KB (50 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/route-mobile/refs/heads/main/openapi/route-mobile-sendclean-email.yml