openapi.yaml

openapi: 3.0.3
info:
  title: Workplace Console API
  description: API for managing email and workplace service subscriptions.
  termsOfService: https://truehost.com/terms-of-service
  contact:
    email: support@truehost.cloud
  version: v1
servers:
  - url: https://workplace-console.truehost.cloud/api
    description: Production server
components:
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
  schemas:
    # DNS Related Schemas
    DnsRecord:
      type: object
      required:
        - host
        - type
        - value
        - priority
        - ttl
      properties:
        host:
          type: string
          description: DNS record host/name
        type:
          type: string
          description: DNS record type (A, MX, TXT, etc.)
        value:
          type: string
          description: DNS record value
        priority:
          type: string
          description: DNS record priority (may be "N/A" for non-MX records)
        ttl:
          type: integer
          description: DNS record TTL in seconds

    FoundDnsRecords:
      type: object
      description: Found DNS records organized by type
      properties:
        NS:
          type: array
          items:
            type: string
          description: Name server records
        A:
          type: array
          items:
            type: string
          description: IPv4 address records
        AAAA:
          type: array
          items:
            type: string
          description: IPv6 address records
        CNAME:
          type: array
          items:
            type: string
          description: Canonical name records
        MX:
          type: array
          items:
            type: string
          description: Mail exchange records
        TXT:
          type: array
          items:
            type: string
          description: Text records
        SOA:
          type: array
          items:
            type: string
          description: Start of authority records
        SRV:
          type: array
          items:
            type: string
          description: Service records
        PTR:
          type: array
          items:
            type: string
          description: Pointer records

    DnsInfoRequest:
      type: object
      required:
        - domain
        - client_id
        - email
      properties:
        domain:
          type: string
          description: Domain name
        client_id:
          type: string
          description: Client id
        email:
          type: string
          description: Email

    DnsInfoResponse:
      type: object
      required:
        - domain
        - score
        - all_dns_score
        - found
        - total
        - missing_dns
        - other_missing_dns
        - found_dns
      properties:
        domain:
          type: string
          description: The domain name that was checked
        score:
          type: number
          description: DNS configuration score
        all_dns_score:
          type: number
          description: Overall DNS score
        found:
          type: integer
          description: Number of required DNS records found
        total:
          type: integer
          description: Total number of required DNS records
        missing_dns:
          type: array
          description: List of missing required DNS records
          items:
            $ref: '#/components/schemas/DnsRecord'
        other_missing_dns:
          type: array
          description: List of other missing DNS records
          items:
            $ref: '#/components/schemas/DnsRecord'
        found_dns:
          $ref: '#/components/schemas/FoundDnsRecords'

    # Subscription Related Schemas
    SubscriptionDetails:
      type: object
      required:
        - name
      properties:
        id:
          type: integer
          readOnly: true
        name:
          type: string
          maxLength: 255
          minLength: 1
        mailbox:
          type: integer
          description: Number of mailboxes
          maximum: 2147483647
          minimum: -2147483648
        quota:
          type: integer
          description: Allowed quota number per mailbox in GB
          maximum: 2147483647
          minimum: -2147483648
        alias:
          type: integer
          description: Allowed number of aliases per mailbox
          maximum: 2147483647
          minimum: -2147483648
        forward:
          type: integer
          description: Allowed number of forwarding rules per mailbox
          maximum: 2147483647
          minimum: -2147483648
        platform:
          type: string
          enum:
            - whmcs
            - olitt
            - others
        price:
          type: string
          format: decimal

    SubScriptionInfo:
      type: object
      required:
        - domain
        - subscription
      properties:
        domain:
          type: string
          minLength: 1
        subscription:
          type: integer

    SubscriptionInfoResponse:
      type: object
      required:
        - info
        - emails
      properties:
        info:
          $ref: '#/components/schemas/OrderDisplay'
        emails:
          type: array
          items:
            $ref: '#/components/schemas/EmailDisplay'

    SubscriptionUsageResponse:
      type: object
      properties:
        used-emails:
          type: number
        remaining-quota:
          type: number
        remaining-emails:
          type: number
        allowed-emails:
          type: number
        allowed-alias:
          type: number
        remaining-alias:
          type: number
        allowed-quota:
          type: number

    SubscriptionsReadResponse:
      type: object
      properties:
        domain_context:
          type: object
        user_emails:
          type: array
          items:
            type: object
        email_aliases:
          type: object

    # Email Related Schemas
    EmailDisplay:
      type: object
      required:
        - name
      properties:
        id:
          type: integer
          readOnly: true
        name:
          type: string
          format: email
          maxLength: 254
          minLength: 1
        email_quota:
          type: integer
          description: Email quota in GB
          maximum: 2147483647
          minimum: -2147483648
        max_quota:
          type: integer
          description: Max email quota in GB
          maximum: 2147483647
          minimum: -2147483648
        used_quota:
          type: integer
          description: Used quota in GB
          maximum: 2147483647
          minimum: -2147483648
        email_id:
          type: integer
          maximum: 2147483647
          minimum: -2147483648
          nullable: true
        display_name:
          type: string
          maxLength: 255
          nullable: true
        order:
          type: integer
          nullable: true

    UpdateEmailQuota:
      type: object
      required:
        - email
        - quota
        - client_id
      properties:
        email:
          type: string
          format: email
          minLength: 1
        quota:
          type: integer
        client_id:
          type: integer
          minimum: 0

    DeleteEmail:
      type: object
      required:
        - email
        - domain
        - client_id
      properties:
        email:
          type: string
          format: email
          minLength: 1
        domain:
          type: string
          minLength: 1
        client_id:
          type: integer
          minimum: 0

    # Alias Related Schemas
    EmailAlias:
      type: object
      required:
        - email
        - domain
        - alias
        - client_id
      properties:
        email:
          type: string
          format: email
          minLength: 1
        domain:
          type: string
          minLength: 1
        alias:
          type: string
          format: email
          minLength: 1
        client_id:
          type: integer
          minimum: 0

    DeleteAlias:
      type: object
      required:
        - email
        - alias
        - domain
        - client_id
      properties:
        email:
          type: string
          format: email
          minLength: 1
        alias:
          type: string
          format: email
          minLength: 1
        domain:
          type: string
          minLength: 1
        client_id:
          type: integer
          minimum: 0

    AliasDisplay:
      type: object
      required:
        - name
      properties:
        id:
          type: integer
          readOnly: true
        primary_email:
          type: string
          readOnly: true
          minLength: 1
        name:
          type: string
          format: email
          maxLength: 254
          minLength: 1

    # Domain Related Schemas
    Domain:
      type: object
      required:
        - domain
      properties:
        domain:
          type: string
          minLength: 1

    DomainAction:
      type: object
      required:
        - action
        - domain
      properties:
        action:
          type: string
          minLength: 1
        domain:
          type: string
          minLength: 1

    OrderDisplay:
      type: object
      required:
        - domain
      properties:
        id:
          type: integer
          readOnly: true
        context_id:
          type: integer
          maximum: 2147483647
          minimum: -2147483648
          nullable: true
        domain:
          type: string
          maxLength: 255
          minLength: 1
        enabled:
          type: boolean
        synched_at:
          type: string
          format: date-time
          nullable: true
        average_size:
          type: integer
          maximum: 2147483647
          minimum: -2147483648
        filestore_id:
          type: integer
          maximum: 2147483647
          minimum: -2147483648
        filestore_name:
          type: string
          maxLength: 255
          nullable: true
        max_quota:
          type: integer
          maximum: 2147483647
          minimum: -2147483648
        context_name:
          type: string
          maxLength: 255
          nullable: true
        used_quota:
          type: integer
          maximum: 2147483647
          minimum: -2147483648
        gab_mode:
          type: string
          maxLength: 255
          nullable: true
        is_order_active:
          type: boolean
        updated_at:
          type: string
          format: date-time
          readOnly: true
        created_at:
          type: string
          format: date-time
          readOnly: true
        unallocated_quota:
          type: integer
          maximum: 2147483647
          minimum: -2147483648
        unallocated_alias:
          type: integer
          maximum: 2147483647
          minimum: -2147483648
        is_alias_calculated:
          type: boolean
        is_alias_synched:
          type: boolean
        last_dns_check:
          type: string
          format: date-time
          nullable: true
        is_dns_valid:
          type: boolean
        client_id:
          type: integer
          maximum: 2147483647
          minimum: -2147483648
          nullable: true
        is_verified:
          type: boolean
        subscription:
          type: integer
          nullable: true

    # Authentication Related Schemas
    TokenObtainPair:
      type: object
      required:
        - username
        - password
      properties:
        username:
          type: string
          minLength: 1
        password:
          type: string
          minLength: 1

    TokenRefresh:
      type: object
      required:
        - refresh
      properties:
        refresh:
          type: string
          minLength: 1
        access:
          type: string
          readOnly: true
          minLength: 1

    ResetEmailPassword:
      type: object
      required:
        - email
        - password
        - client_id
      properties:
        email:
          type: string
          format: email
          minLength: 1
        password:
          type: string
          minLength: 1
        client_id:
          type: integer
          minimum: 0

    # Account Creation Schemas
    WorkplaceCreateEmails:
      type: object
      required:
        - emails
        - domain_name
        - subscription
        - new_subscription
        - display_name
        - user_password
        - email_quota
        - client_id
        
      properties:
        emails:
          type: array
          items:
            type: string
            format: email
            minLength: 1
        domain_name:
          type: string
          maxLength: 255
          minLength: 1
        subscription:
          type: integer
          minimum: 0
        new_subscription:
          type: boolean
        display_name:
          type: string
          minLength: 1
        user_password:
          type: string
          minLength: 1
        email_quota:
          type: integer
          minimum: 0
        client_id:
          type: integer
          minimum: 0

    # Import Related Schemas
    ImportRequest:
      type: object
      required:
        - file
        - domain
      properties:
        file:
          type: string
          format: binary
          description: CSV or excel file containing email accounts
        domain:
          type: string
          description: Domain to associate with emails

    # Action Related Schemas
    ServiceAction:
      type: object
      required:
        - action
      properties:
        action:
          type: string
          minLength: 1

    # Common Response Schemas
    StandardResponse:
      type: object
      properties:
        message:
          type: string
        error:
          type: string

security:
  - BearerAuth: []

paths:
  /available-packages/:
    get:
      operationId: available-packages_list
      summary: Get available subscriptions
      description: Get available subscriptions
      tags:
        - available-packages
      responses:
        '200':
          description: List of available subscription packages
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/SubscriptionDetails'

  /change-quota/:
    post:
      operationId: update_email_quota
      summary: Update email quota
      description: Update email quota
      tags:
        - update-email-quota
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateEmailQuota'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StandardResponse'

  /create-alias/:
    post:
      operationId: create_email_alias
      summary: Create email alias
      description: Create email alias
      tags:
        - create-alias
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EmailAlias'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StandardResponse'

  /delete-alias/:
    post:
      operationId: delete_email_alias
      summary: Delete alias
      description: Delete alias
      tags:
        - delete-alias
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DeleteAlias'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StandardResponse'

  /delete-email/:
    post:
      operationId: delete_email
      summary: Delete email
      description: Delete email
      tags:
        - delete-email
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DeleteEmail'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StandardResponse'

  /dns-info/:
    post:
      operationId: dns-info_create
      summary: Get DNS information
      description: Get DNS configuration information for a domain
      tags:
        - dns-info
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DnsInfoRequest'
      responses:
        '200':
          description: DNS information response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DnsInfoResponse'

  /domain-alias/:
    post:
      operationId: domain-alias_create
      summary: Get domain alias list
      description: Get domain alias list
      tags:
        - domain-alias
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Domain'
      responses:
        '200':
          description: List of domain aliases
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/AliasDisplay'

  /domain-info/:
    post:
      operationId: domain-info_create
      summary: Get domain subscription details
      description: Get domain subscription details and emails list
      tags:
        - domain-info
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SubScriptionInfo'
      responses:
        '200':
          description: Domain subscription information
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubscriptionInfoResponse'

  /domain/:
    post:
      operationId: domain_create
      summary: Update domain subscription status
      description: Update domain subscription status, delete, suspend, unsuspend, etc...
      tags:
        - domain
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DomainAction'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StandardResponse'

  /get-token/:
    post:
      operationId: get-token_create
      summary: Obtain authentication token
      description: |-
        Takes a set of user credentials and returns an access and refresh JSON web
        token pair to prove the authentication of those credentials.
      tags:
        - get-token
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TokenObtainPair'
      responses:
        '201':
          description: Token pair created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TokenObtainPair'

  /import/:
    post:
      operationId: import_create
      summary: Bulk create emails
      description: Bulk create emails via uploaded file and domain
      tags:
        - import
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/ImportRequest'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StandardResponse'

  /refresh-token/:
    post:
      operationId: refresh-token_create
      summary: Refresh authentication token
      description: |-
        Takes a refresh type JSON web token and returns an access type JSON web
        token if the refresh token is valid.
      tags:
        - refresh-token
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TokenRefresh'
      responses:
        '201':
          description: Token refreshed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TokenRefresh'

  /reset-password/:
    post:
      operationId: reset_email_password
      summary: Reset subscription email password
      description: Reset subscription email password
      tags:
        - reset-password
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ResetEmailPassword'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StandardResponse'

  /subscription-info/:
    post:
      operationId: subscription-info_create
      summary: Get subscription usage info
      description: Get subscription usage info
      tags:
        - subscription-info
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SubScriptionInfo'
      responses:
        '200':
          description: Subscription usage information
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubscriptionUsageResponse'

  /subscriptions/:
    get:
      operationId: subscriptions_list
      summary: List subscriptions
      description: Get list of subscriptions
      tags:
        - subscriptions
      responses:
        '200':
          description: List of subscriptions
          content:
            application/json:
              schema:
                type: object

    post:
      operationId: emails_create
      summary: Create a new emails
      description: |-
        Create a new emails, it will also create a new subscription
        for the domain if emails list is not empty and new_subscription is true
      tags:
        - subscriptions
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WorkplaceCreateEmails'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StandardResponse'

  /subscriptions/{context_id}/:
    get:
      operationId: subscriptions_read
      summary: Get subscription details
      description: Get subscription details
      tags:
        - subscriptions
      parameters:
        - name: context_id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Subscription details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubscriptionsReadResponse'

    post:
      operationId: update_subscription_status
      summary: Update subscription status
      description: Update subscription status, delete, suspend, unsuspend, etc...
      tags:
        - subscriptions
      parameters:
        - name: context_id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ServiceAction'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StandardResponse'

  /upgrade/:
    post:
      operationId: upgrade_create
      summary: Upgrade subscription
      description: Upgrade subscription
      tags:
        - upgrade
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SubScriptionInfo'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StandardResponse'