Modoboa Accounts API

openapi: 3.2.0
info:
  title: Modoboa Accounts API
  version: v2
servers:
- url: https://demo.modoboa.org/api/schema-v2/
  description: Remote Demo server
- url: https://localhost:5000/api/schema-v2/
  description: Local server
tags:
- name: Accounts
paths:
  /api/v2/accounts/:
    get:
      operationId: accounts_list
      description: ViewSet for User/Mailbox.
      parameters:
      - in: query
        name: domain
        schema:
          type: integer
      - name: ordering
        required: false
        in: query
        description: Which field to use when ordering the results.
        schema:
          type: string
      - name: page
        required: false
        in: query
        description: A page number within the paginated result set.
        schema:
          type: integer
      - name: page_size
        required: false
        in: query
        description: Number of results to return per page.
        schema:
          type: integer
      - in: query
        name: role
        schema:
          type: array
          items:
            type: string
            enum:
            - DomainAdmins
            - Resellers
            - SimpleUsers
            - SuperAdmins
        description: '* `SimpleUsers` - Simple user

          * `DomainAdmins` - Domain administrator

          * `Resellers` - Reseller

          * `SuperAdmins` - Super administrator'
        explode: true
        style: form
      - name: search
        required: false
        in: query
        description: A search term.
        schema:
          type: string
      tags:
      - Accounts
      security:
      - tokenAuth: []
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedAccountList'
          description: ''
      summary: Accounts list
      x-summary-source: derived
    post:
      operationId: accounts_create
      description: ViewSet for User/Mailbox.
      tags:
      - Accounts
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WritableAccount'
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/WritableAccount'
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/WritableAccount'
        required: true
      security:
      - tokenAuth: []
      responses:
        '201':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WritableAccount'
          description: ''
      summary: Accounts create
      x-summary-source: derived
  /api/v2/accounts/{id}/:
    get:
      operationId: accounts_retrieve
      description: ViewSet for User/Mailbox.
      parameters:
      - in: path
        name: id
        schema:
          type: integer
        description: A unique integer value identifying this user.
        required: true
      tags:
      - Accounts
      security:
      - tokenAuth: []
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Account'
          description: ''
      summary: Accounts retrieve
      x-summary-source: derived
    put:
      operationId: accounts_update
      description: ViewSet for User/Mailbox.
      parameters:
      - in: path
        name: id
        schema:
          type: integer
        description: A unique integer value identifying this user.
        required: true
      tags:
      - Accounts
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WritableAccount'
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/WritableAccount'
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/WritableAccount'
        required: true
      security:
      - tokenAuth: []
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WritableAccount'
          description: ''
      summary: Accounts update
      x-summary-source: derived
    patch:
      operationId: accounts_partial_update
      description: ViewSet for User/Mailbox.
      parameters:
      - in: path
        name: id
        schema:
          type: integer
        description: A unique integer value identifying this user.
        required: true
      tags:
      - Accounts
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PatchedWritableAccount'
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/PatchedWritableAccount'
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/PatchedWritableAccount'
      security:
      - tokenAuth: []
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WritableAccount'
          description: ''
      summary: Accounts partial update
      x-summary-source: derived
    delete:
      operationId: accounts_destroy
      description: ViewSet for User/Mailbox.
      parameters:
      - in: path
        name: id
        schema:
          type: integer
        description: A unique integer value identifying this user.
        required: true
      tags:
      - Accounts
      security:
      - tokenAuth: []
      responses:
        '204':
          description: No response body
      summary: Accounts destroy
      x-summary-source: derived
  /api/v2/accounts/{id}/delete/:
    post:
      operationId: accounts_delete_create
      description: Custom delete method that accepts body arguments.
      parameters:
      - in: path
        name: id
        schema:
          type: integer
        description: A unique integer value identifying this user.
        required: true
      tags:
      - Accounts
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DeleteAccount'
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/DeleteAccount'
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/DeleteAccount'
      security:
      - tokenAuth: []
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeleteAccount'
          description: ''
      summary: Accounts delete create
      x-summary-source: derived
  /api/v2/accounts/{id}/password/:
    put:
      operationId: accounts_password_update
      description: Change account password.
      parameters:
      - in: path
        name: id
        schema:
          type: integer
        description: A unique integer value identifying this user.
        required: true
      tags:
      - Accounts
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AccountPassword'
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/AccountPassword'
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/AccountPassword'
        required: true
      security:
      - tokenAuth: []
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccountPassword'
          description: ''
      summary: Accounts password update
      x-summary-source: derived
  /api/v2/accounts/bulk_delete/:
    post:
      operationId: accounts_bulk_delete_create
      description: Delete multiple accounts at the same time.
      tags:
      - Accounts
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AccountBulkDelete'
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/AccountBulkDelete'
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/AccountBulkDelete'
        required: true
      security:
      - tokenAuth: []
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccountBulkDelete'
          description: ''
      summary: Accounts bulk delete create
      x-summary-source: derived
  /api/v2/accounts/exists/:
    get:
      operationId: accounts_exists_retrieve
      description: 'Check if account exists.


        Requires a valid email address as argument. Example:


        GET /exists/?email=user@test.com'
      tags:
      - Accounts
      security:
      - tokenAuth: []
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WritableAccount'
          description: ''
      summary: Accounts exists retrieve
      x-summary-source: derived
  /api/v2/accounts/random_password/:
    get:
      operationId: accounts_random_password_retrieve
      description: Generate a random password.
      tags:
      - Accounts
      security:
      - tokenAuth: []
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WritableAccount'
          description: ''
      summary: Accounts random password retrieve
      x-summary-source: derived
  /api/v2/accounts/reset_password/:
    post:
      operationId: accounts_reset_password_create
      description: Reset account password and send a new one by SMS.
      tags:
      - Accounts
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ResetPassword'
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/ResetPassword'
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/ResetPassword'
        required: true
      security:
      - tokenAuth: []
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResetPassword'
          description: ''
      summary: Accounts reset password create
      x-summary-source: derived
  /api/v2/accounts/validate/:
    post:
      operationId: accounts_validate_create
      description: Validate given account without creating it.
      tags:
      - Accounts
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WritableAccount'
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/WritableAccount'
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/WritableAccount'
        required: true
      security:
      - tokenAuth: []
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WritableAccount'
          description: ''
      summary: Accounts validate create
      x-summary-source: derived
components:
  schemas:
    Account:
      type: object
      description: Add support for user resources.
      properties:
        pk:
          type: integer
          readOnly: true
          title: ID
        username:
          type: string
          maxLength: 254
        first_name:
          type: string
          maxLength: 150
        last_name:
          type: string
          maxLength: 150
        is_active:
          type: boolean
        mailbox:
          $ref: '#/components/schemas/Mailbox'
        role:
          type: string
          description: Return role.
          readOnly: true
        language:
          allOf:
          - $ref: '#/components/schemas/LanguageEnum'
          description: 'Prefered language to display pages.


            * `br` - breton

            * `cs` - čeština

            * `de` - deutsch

            * `en` - english

            * `el` - ελληνικά

            * `es` - español

            * `fi` - Suomalainen

            * `fr` - français

            * `it` - italiano

            * `ja` - 日本の

            * `nl` - nederlands

            * `pt` - português

            * `pt-br` - português (BR)

            * `pl` - polski

            * `ro` - Română

            * `ru` - русский

            * `sv` - svenska

            * `tr` - türk

            * `zh-hant` - 中文（台灣）'
        phone_number:
          type:
          - string
          - 'null'
          maxLength: 128
        secondary_email:
          description: An alternative e-mail address, can be used for recovery needs.
          oneOf:
          - type: string
            format: email
            maxLength: 254
          - type: string
            maxLength: 0
        domains:
          type: array
          items:
            type: string
          description: List of administered domains (resellers and domain administrators only).
          readOnly: true
        tfa_enabled:
          type: boolean
          readOnly: true
        totp_enabled:
          type: boolean
        webauthn_enabled:
          type: boolean
        date_joined:
          type: string
          format: date-time
        last_login:
          type:
          - string
          - 'null'
          format: date-time
        aliases:
          type: array
          items:
            type: string
            format: email
        possible_actions:
          type: string
          readOnly: true
        resources:
          type: string
          readOnly: true
      required:
      - aliases
      - domains
      - pk
      - possible_actions
      - resources
      - role
      - tfa_enabled
      - username
    LanguageEnum:
      enum:
      - br
      - cs
      - de
      - en
      - el
      - es
      - fi
      - fr
      - it
      - ja
      - nl
      - pt
      - pt-br
      - pl
      - ro
      - ru
      - sv
      - tr
      - zh-hant
      type: string
      description: '* `br` - breton

        * `cs` - čeština

        * `de` - deutsch

        * `en` - english

        * `el` - ελληνικά

        * `es` - español

        * `fi` - Suomalainen

        * `fr` - français

        * `it` - italiano

        * `ja` - 日本の

        * `nl` - nederlands

        * `pt` - português

        * `pt-br` - português (BR)

        * `pl` - polski

        * `ro` - Română

        * `ru` - русский

        * `sv` - svenska

        * `tr` - türk

        * `zh-hant` - 中文（台灣）'
    ResetPassword:
      type: object
      description: Serializer by the reset password endpoint.
      properties:
        email:
          type: string
          format: email
      required:
      - email
    AccountBulkDelete:
      type: object
      description: Serializer used with bulk delete operation.
      properties:
        ids:
          type: array
          items:
            type: integer
        keepdir:
          type: boolean
          default: false
      required:
      - ids
    DeleteAccount:
      type: object
      description: Serializer used with delete operation.
      properties:
        keepdir:
          type: boolean
          default: false
    PaginatedAccountList:
      type: object
      required:
      - count
      - results
      properties:
        count:
          type: integer
          example: 123
        next:
          type:
          - string
          - 'null'
          format: uri
          example: http://api.example.org/accounts/?page=4
        previous:
          type:
          - string
          - 'null'
          format: uri
          example: http://api.example.org/accounts/?page=2
        results:
          type: array
          items:
            $ref: '#/components/schemas/Account'
    WritableAccount:
      type: object
      description: Add support for aliases and sender addresses.
      properties:
        pk:
          type: integer
          readOnly: true
          title: ID
        username:
          type: string
          maxLength: 254
        first_name:
          type: string
          maxLength: 150
        last_name:
          type: string
          maxLength: 150
        is_active:
          type: boolean
        mailbox:
          $ref: '#/components/schemas/Mailbox'
        role:
          $ref: '#/components/schemas/RoleEnum'
        language:
          allOf:
          - $ref: '#/components/schemas/LanguageEnum'
          description: 'Prefered language to display pages.


            * `br` - breton

            * `cs` - čeština

            * `de` - deutsch

            * `en` - english

            * `el` - ελληνικά

            * `es` - español

            * `fi` - Suomalainen

            * `fr` - français

            * `it` - italiano

            * `ja` - 日本の

            * `nl` - nederlands

            * `pt` - português

            * `pt-br` - português (BR)

            * `pl` - polski

            * `ro` - Română

            * `ru` - русский

            * `sv` - svenska

            * `tr` - türk

            * `zh-hant` - 中文（台灣）'
        phone_number:
          type:
          - string
          - 'null'
          maxLength: 128
        secondary_email:
          description: An alternative e-mail address, can be used for recovery needs.
          oneOf:
          - type: string
            format: email
            maxLength: 254
          - type: string
            maxLength: 0
        tfa_enabled:
          type: boolean
          readOnly: true
        totp_enabled:
          type: boolean
        webauthn_enabled:
          type: boolean
        date_joined:
          type: string
          format: date-time
        last_login:
          type:
          - string
          - 'null'
          format: date-time
        password:
          type: string
          writeOnly: true
        aliases:
          type: array
          items:
            type: string
            format: email
      required:
      - pk
      - role
      - tfa_enabled
      - username
    PatchedWritableAccount:
      type: object
      description: Add support for aliases and sender addresses.
      properties:
        pk:
          type: integer
          readOnly: true
          title: ID
        username:
          type: string
          maxLength: 254
        first_name:
          type: string
          maxLength: 150
        last_name:
          type: string
          maxLength: 150
        is_active:
          type: boolean
        mailbox:
          $ref: '#/components/schemas/Mailbox'
        role:
          $ref: '#/components/schemas/RoleEnum'
        language:
          allOf:
          - $ref: '#/components/schemas/LanguageEnum'
          description: 'Prefered language to display pages.


            * `br` - breton

            * `cs` - čeština

            * `de` - deutsch

            * `en` - english

            * `el` - ελληνικά

            * `es` - español

            * `fi` - Suomalainen

            * `fr` - français

            * `it` - italiano

            * `ja` - 日本の

            * `nl` - nederlands

            * `pt` - português

            * `pt-br` - português (BR)

            * `pl` - polski

            * `ro` - Română

            * `ru` - русский

            * `sv` - svenska

            * `tr` - türk

            * `zh-hant` - 中文（台灣）'
        phone_number:
          type:
          - string
          - 'null'
          maxLength: 128
        secondary_email:
          description: An alternative e-mail address, can be used for recovery needs.
          oneOf:
          - type: string
            format: email
            maxLength: 254
          - type: string
            maxLength: 0
        tfa_enabled:
          type: boolean
          readOnly: true
        totp_enabled:
          type: boolean
        webauthn_enabled:
          type: boolean
        date_joined:
          type: string
          format: date-time
        last_login:
          type:
          - string
          - 'null'
          format: date-time
        password:
          type: string
          writeOnly: true
        aliases:
          type: array
          items:
            type: string
            format: email
    Mailbox:
      type: object
      description: Base mailbox serializer.
      properties:
        pk:
          type: integer
          readOnly: true
          title: ID
        full_address:
          type: string
          format: email
        use_domain_quota:
          type: boolean
        quota:
          type: string
        message_limit:
          type:
          - integer
          - 'null'
          maximum: 9223372036854775807
          minimum: 0
          format: int64
          title: Message sending limit
          description: Number of messages this mailbox can send per day
        quota_usage:
          type: integer
          readOnly: true
        is_send_only:
          type: boolean
        sent_messages_in_percent:
          type:
          - integer
          - 'null'
          description: Return number of sent messages as a percentage.
          readOnly: true
      required:
      - full_address
      - pk
      - quota_usage
      - sent_messages_in_percent
    AccountPassword:
      type: object
      description: A serializer used to change a user password.
      properties:
        password:
          type: string
          maxLength: 256
        new_password:
          type: string
      required:
      - new_password
      - password
    RoleEnum:
      enum:
      - SimpleUsers
      - DomainAdmins
      - Resellers
      - SuperAdmins
      type: string
      description: '* `SimpleUsers` - Simple user

        * `DomainAdmins` - Domain administrator

        * `Resellers` - Reseller

        * `SuperAdmins` - Super administrator'
  securitySchemes:
    oauth2:
      type: oauth2
      flows: {}
    tokenAuth:
      type: apiKey
      in: header
      name: Authorization
      description: Token-based authentication with required prefix "Token"