power-mailinabox/api/mailinabox.yml

openapi: 3.0.3
info:
  title: Mail-in-a-Box
  description: |
    Mail-in-a-Box API HTTP specification.

    # Introduction
    This API is documented in [**OpenAPI format**](http://spec.openapis.org/oas/v3.0.3).
    ([View the full HTTP specification](https://raw.githubusercontent.com/mail-in-a-box/mailinabox/api-spec/api/mailinabox.yml).)

    All endpoints are relative to `https://{host}/admin` and are secured with [`Basic Access` authentication](https://en.wikipedia.org/wiki/Basic_access_authentication). If you have multi-factor authentication enabled, authentication with a `user:password` combination will fail unless a valid OTP is supplied via the `x-auth-token` header. Authentication via a `user:user_key` pair is possible without the header being present.
  contact:
    name: Mail-in-a-Box support
    url: https://mailinabox.email/
  license:
    name: CC0 1.0 Universal
    url: https://creativecommons.org/publicdomain/zero/1.0/legalcode
  version: 60.3
  x-logo:
    url: https://mailinabox.email/static/logo.png
    altText: Mail-in-a-Box logo
externalDocs:
  description: Find out more about Mail-in-a-box.
  url: https://mailinabox.email/
servers:
  - url: https://{host}/admin
    variables:
      host:
        default: box.example.com
        description: The API hostname.
security:
  - basicAuth: []
tags:
  - name: User
    description: Endpoints related to user authentication.
  - name: Mail
    description: |
      Mail operations, which include getting all users, getting all aliases, adding/updating/removing users and aliases and getting all mail domains.
  - name: DNS
    description: |
      DNS operations, which include adding custom records, adding a secondary nameserver and viewing all DNS records.
  - name: SSL
    description: |
      TLS (SSL) Certificates operations, which include checking certificate status
      and installing custom certificates.
  - name: Web
    description: |
      Static web hosting operations, which include getting domain information and updating domain root directories.
  - name: MFA
    description: |
      Manage multi-factor authentication schemes. Currently, only TOTP is supported.
  - name: System
    description: |
      System operations, which include system status checks, new version checks
      and reboot status.
  - name: PGP
    description: |
      PGP Key operations, which include key management and publishing.
  - name: WKD
    description: |
      WKD (Web Key Directory) operations, which include publishing public PGP keys on the internet.
paths:
  /login:
    post:
      tags:
        - User
      summary: Exchange a username and password for a session API key.
      description: |
        Returns user information and a session API key.

        Authenticate a user by supplying the auth token as a base64 encoded string in
        format `email:password` using basic authentication headers.

        If successful, a long-lived `api_key` is returned which can be used for subsequent
        requests to the API in place of the password.
      operationId: login
      x-codeSamples:
        - lang: curl
          source: |
            curl -X POST "https://{host}/admin/login" \
              -u "<email>:<password>"
      responses:
        200:
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MeResponse'
              examples:
                invalid:
                  value:
                    reason: Incorrect username or password
                    status: invalid
                ok:
                  value:
                    api_key: 1a2b3c4d5e6f7g8h9i0j
                    email: user@example.com
                    privileges:
                      - admin
                    status: ok
  /logout:
    post:
      tags:
        - User
      summary: Invalidates a session API key.
      description: |
        Invalidates a session API key so that it cannot be used after this API call.
      operationId: logout
      x-codeSamples:
        - lang: curl
          source: |
            curl -X POST "https://{host}/admin/logout" \
              -u "<email>:<session_key>"
      responses:
        200:
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LogoutResponse'
  /system/status:
    post:
      tags:
        - System
      summary: Get system status
      description: |
        Returns an array of statuses which can include headings.
      operationId: getSystemStatus
      x-codeSamples:
        - lang: curl
          source: |
            curl -X POST "https://{host}/admin/system/status" \
              -u "<email>:<password>"
      responses:
        200:
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SystemStatusResponse'
              example:
                - type: heading
                  text: System
                  extra: []
                - type: warning
                  text: This domain's DNSSEC DS record is not set
                  extra:
                    - monospace: false
                      text: 'Digest Type: 2 / SHA-25'
        403:
          description: Forbidden
          content:
            text/html:
              schema:
                type: string
  /system/version:
    get:
      tags:
        - System
      summary: Get system version
      description: Returns installed Mail-in-a-Box version.
      operationId: getSystemVersion
      x-codeSamples:
        - lang: curl
          source: |
            curl -X GET "https://{host}/admin/system/version" \
              -u "<email>:<password>"
      responses:
        200:
          description: Successful operation
          content:
            text/html:
              schema:
                $ref: '#/components/schemas/SystemVersionResponse'
              example: v0.46
        403:
          description: Forbidden
          content:
            text/html:
              schema:
                type: string
  /system/latest-upstream-version:
    post:
      tags:
        - System
      summary: Get system upstream version
      description: Returns Mail-in-a-Box upstream version.
      operationId: getSystemUpstreamVersion
      x-codeSamples:
        - lang: curl
          source: |
            curl -X POST "https://{host}/admin/system/latest-upstream-version" \
              -u "<email>:<password>"
      responses:
        200:
          description: Successful operation
          content:
            text/html:
              schema:
                $ref: '#/components/schemas/SystemVersionUpstreamResponse'
              example: v0.47
        403:
          description: Forbidden
          content:
            text/html:
              schema:
                type: string
  /system/updates:
    get:
      tags:
        - System
      summary: Get system updates
      description: Returns system (apt) updates.
      operationId: getSystemUpdates
      x-codeSamples:
        - lang: curl
          source: |
            curl -X GET "https://{host}/admin/system/updates" \
              -u "<email>:<password>"
      responses:
        200:
          description: Successful operation
          content:
            text/html:
              schema:
                $ref: '#/components/schemas/SystemUpdatesResponse'
              example: |
                libgnutls30 (3.5.18-1ubuntu1.4)
                libxau6 (1:1.0.8-1ubuntu1)
        403:
          description: Forbidden
          content:
            text/html:
              schema:
                type: string
  /system/update-packages:
    post:
      tags:
        - System
      summary: Update system packages
      description: Updates system (apt) packages.
      operationId: updateSystemPackages
      x-codeSamples:
        - lang: curl
          source: |
            curl -X POST "https://{host}/admin/system/update-packages" \
              -u "<email>:<password>"
      responses:
        200:
          description: Successful operation
          content:
            text/html:
              schema:
                $ref: '#/components/schemas/SystemUpdatePackagesResponse'
              example: |
                Calculating upgrade...
                The following packages will be upgraded:
                  cloud-init grub-common
        403:
          description: Forbidden
          content:
            text/html:
              schema:
                type: string
  /system/privacy:
    get:
      tags:
        - System
      summary: Get system privacy status
      description: |
        Returns system privacy (new-version check) status.

        Response:

          - `true`: Private, new-version checks will not be performed
          - `false`: Not private, new-version checks will be performed
      operationId: getSystemPrivacyStatus
      x-codeSamples:
        - lang: curl
          source: |
            curl -X GET "https://{host}/admin/system/privacy" \
              -u "<email>:<password>"
      responses:
        200:
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SystemPrivacyStatusResponse'
        403:
          description: Forbidden
          content:
            text/html:
              schema:
                type: string
    post:
      tags:
        - System
      summary: Update system privacy
      description: |
        Updates system privacy (new-version checks).

        Request:

          - `value: private`: Disable new version checks
          - `value: off`: Enable new version checks
      operationId: updateSystemPrivacy
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/SystemPrivacyUpdateRequest'
            examples:
              enable:
                summary: Enable new version checks
                value:
                  value: 'off'
              disable:
                summary: Disable new version checks
                value:
                  value: private
      x-codeSamples:
        - lang: curl
          source: |
            curl -X POST "https://{host}/admin/system/privacy" \
              -d "value=<string>" \
              -u "<email>:<password>"
      responses:
        200:
          description: Successful operation
          content:
            text/html:
              schema:
                $ref: '#/components/schemas/SystemPrivacyUpdateResponse'
              example: OK
        400:
          description: Bad request
          content:
            text/html:
              schema:
                type: string
        403:
          description: Forbidden
          content:
            text/html:
              schema:
                type: string
  /system/reboot:
    get:
      tags:
        - System
      summary: Get system reboot status
      description: |
        Returns the system reboot status.

        Response:

          - `true`: A reboot is required
          - `false`: A reboot is not required
      operationId: getSystemRebootStatus
      x-codeSamples:
        - lang: curl
          source: |
            curl -X GET "https://{host}/admin/system/reboot" \
              -u "<email>:<password>"
      responses:
        200:
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SystemRebootStatusResponse'
        403:
          description: Forbidden
          content:
            text/html:
              schema:
                type: string
    post:
      tags:
        - System
      summary: Reboot system
      description: Reboots the system.
      operationId: rebootSystem
      x-codeSamples:
        - lang: curl
          source: |
            curl -X POST "https://{host}/admin/system/reboot" \
              -u "<email>:<password>"
      responses:
        200:
          description: Successful operation
          content:
            text/html:
              schema:
                $ref: '#/components/schemas/SystemRebootResponse'
              example: No reboot is required, so it is not allowed.
        403:
          description: Forbidden
          content:
            text/html:
              schema:
                type: string
  /system/backup/status:
    get:
      tags:
        - System
      summary: Get system backup status
      description: |
        Returns the system backup status.

        If the list of backups is empty, this implies no backups have been made yet.
      operationId: getSystemBackupStatus
      x-codeSamples:
        - lang: curl
          source: |
            curl -X GET "https://{host}/admin/system/backup/status" \
              -u "<email>:<password>"
      responses:
        200:
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SystemBackupStatusResponse'
        403:
          description: Forbidden
          content:
            text/html:
              schema:
                type: string
  /system/backup/config:
    get:
      tags:
        - System
      summary: Get system backup config
      description: Returns the system backup config.
      operationId: getSystemBackupConfig
      x-codeSamples:
        - lang: curl
          source: |
            curl -X GET "https://{host}/admin/system/backup/config" \
              -u "<email>:<password>"
      responses:
        200:
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SystemBackupConfigResponse'
        403:
          description: Forbidden
          content:
            text/html:
              schema:
                type: string
    post:
      tags:
        - System
      summary: Update system backup config
      description: Updates the system backup config.
      operationId: updateSystemBackupConfig
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/SystemBackupConfigUpdateRequest'
            examples:
              s3:
                summary: S3 backup
                value:
                  target: s3://s3.eu-central-1.amazonaws.com/box-example-com
                  target_user: ACCESS_KEY
                  target_pass: SECRET_ACCESS_KEY
                  minAge: 3
              local:
                summary: Local backup
                value:
                  target: local
                  target_user: ''
                  target_pass: ''
                  minAge: 3
              rsync:
                summary: Rsync backup
                value:
                  target: rsync://username@box.example.com//backups/box.example.com
                  target_user: ''
                  target_pass: ''
                  minAge: 3
              off:
                summary: Disable backups
                value:
                  target: 'off'
                  target_user: ''
                  target_pass: ''
                  minAge: 0
      x-codeSamples:
        - lang: curl
          source: |
            curl -X POST "https://{host}/admin/system/backup/config" \
              -d "target=<hostname>" \
              -d "target_user=<string>" \
              -d "target_pass=<password>" \
              -d "min_age=<integer>" \
              -u "<email>:<password>"
      responses:
        200:
          description: Successful operation
          content:
            text/html:
              schema:
                $ref: '#/components/schemas/SystemBackupConfigUpdateResponse'
              example: OK
        400:
          description: Bad request
          content:
            text/html:
              schema:
                type: string
        403:
          description: Forbidden
          content:
            text/html:
              schema:
                type: string
  /system/backup/new:
    post:
      tags:
        - System
      summary: Perform system backup
      description: Performs a system backup.
      operationId: performSystemBackup
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/PerformBackupRequest'
            examples:
              incremental:
                summary: Perform incremental backup.
                value:
                  full: false
              full:
                summary: Force a full backup.
                value:
                  full: true
      x-codeSamples:
        - lang: curl
          source: |
            curl -X POST "https://{host}/admin/system/backup/new" \
              -d "full=<boolean>" \
              -u "<email>:<password>"
      responses:
        200:
          description: Successful operation
          content:
            text/html:
              schema:
                $ref: '#/components/schemas/PerformBackupResponse'
        403:
          description: Forbidden
          content:
            text/plain:
              schema:
                type: string
  /system/smtp/relay:
    get:
      tags:
        - System
      summary: Get SMTP relay configuration
      description: Gets basic configuration on how the box should use third-party relay services to deliver mail.
      operationId: getRelayConfig
      x-codeSamples:
        - lang: curl
          source: |
            curl -X GET "https://{host}/admin/system/smtp/relay" \
              -u "<email>:<password>"
      responses:
        200:
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SmtpRelayConfig'
        403:
          description: Forbidden
          content:
            text/html:
              schema:
                type: string
    post:
      tags:
        - System
      summary: Set SMTP relay configuration
      description: Sets the configuration on how the box should use third-party relays to deliver mail.
      operationId: setRelayConfig
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/SetSmtpRelayConfigRequest'
            examples:
              disable:
                summary: Do not use relays.
                value:
                  enabled: false
                  host: ""
                  auth_enabled: false
                  user: ""
                  key: ""
              no_auth:
                summary: Use a relay that does not require authentication.
                value:
                  enabled: true
                  host: smtp.relay.net
                  auth_enabled: false
                  user: ""
                  key: ""
              auth:
                summary: Use a relay that requires authentication.
                value:
                  enabled: true
                  host: smtp.relay.net
                  auth_enabled: true
                  user: someuser
                  key: key-or-password-here
      responses:
        200:
          description: Successful operation
          content:
            text/plain:
              schema:
                type: string
        403:
          description: Forbidden
          content:
            text/html:
              schema:
                type: string
  /system/pgp/:
    get:
      tags:
        - PGP
      summary: Get all PGP keys
      description: Gets a JSON summary of all public PGP keys in the keyring.
      operationId: getPGPKeys
      x-codeSamples:
        - lang: curl
          source: |
            curl -X GET "https://{host}/admin/system/pgp/" \
              -u "<email>:<password>"
      responses:
        200:
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PgpKeyring'
              example:
                daemon:
                  ids:
                    - Power Mail-in-a-Box Management Daemon <administrator@mailinabox.lan>
                  master_fpr: 62037B88B743626997E63EFE2469394FBC0CF8DA
                  revoked: false
                  subkeys:
                    - algorithm: RSA
                      auth: true
                      cert: true
                      encr: true
                      sign: true
                      bits: 4096
                      expired: false
                      expires: 1617378256
                      expires_date: 04/02/21
                      expires_days: 179
                      fpr: 62037B88B743626997E63EFE2469394FBC0CF8DA
                      master: true
                imported:
                  - ids:
                    - Someone You Used To Know <nobody@nowhere>
                    master_fpr: B9BD7309D18784392D812050A174D33254CC2820
                    revoked: false
                    subkeys:
                      - algorithm: RSA
                        auth: true
                        cert: true
                        encr: true
                        sign: true
                        bits: 4096
                        expired: false
                        expires: 1615290372
                        expires_date: 03/09/21
                        expires_days: 155
                        fpr: B9BD7309D18784392D812050A174D33254CC2820
                        master: true
                  - ids:
                    - Linus Torvalds <torvalds@kernel.org>
                    - Linus Torvalds <torvalds@linux-foundation.org>
                    master_fpr: ABAF11C65A2970B130ABE3C479BE3E4300411886
                    revoked: false
                    subkeys:
                      - algorithm: RSA
                        auth: false
                        cert: true
                        encr: false
                        sign: true
                        bits: 2048
                        expired: false
                        expires: null
                        expires_date: null
                        expires_days: null
                        fpr: ABAF11C65A2970B130ABE3C479BE3E4300411886
                        master: true
                      - algorithm: RSA
                        auth: false
                        cert: false
                        encr: true
                        sign: false
                        bits: 2048
                        expired: false
                        expires: null
                        expires_date: null
                        expires_days: null
                        fpr: AEE416F7DCCB753BB3D5609D88BCE80F012F54CA
                        master: false
        403:
          description: Forbidden
          content:
            text/html:
              schema:
                type: string
  /system/pgp/{fpr}:
    get:
      tags:
        - PGP
      summary: Get a specific PGP key
      description: Gets a JSON summary of the PGP key with the given fingerprint.
      operationId: getPGPKey
      x-codeSamples:
        - lang: curl
          source: |
            curl -X GET "https://{host}/admin/system/pgp/<fingerprint>" \
              -u "<email>:<password>"
      responses:
        200:
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PgpKey'
              example:
                ids:
                  - Power Mail-in-a-Box Management Daemon <administrator@mailinabox.lan>
                master_fpr: 62037B88B743626997E63EFE2469394FBC0CF8DA
                revoked: false
                subkeys:
                  - algorithm: RSA
                    auth: true
                    cert: true
                    encr: true
                    sign: true
                    bits: 4096
                    expired: false
                    expires: 1617378256
                    expires_date: 04/02/21
                    expires_days: 179
                    fpr: 62037B88B743626997E63EFE2469394FBC0CF8DA
                    master: true
        403:
          description: Forbidden
          content:
            text/html:
              schema:
                type: string
        404:
          description: Key not found in public keyring
          content:
            text/html:
              schema:
                type: string
    delete:
      tags:
        - PGP
      summary: Remove a PGP key
      description: Removes the PGP key with the given fingerprint from the keyring
      operationId: removePGPKey
      x-codeSamples:
        - lang: curl
          source: |
            curl -X DELETE "https://{host}/admin/system/pgp/<fingerprint>" \
              -u "<email>:<password>"
      responses:
        200:
          description: Operation successful
          content:
            text/plain:
              schema:
                type: string
              example: OK
        403:
          description: Forbidden
          content:
            text/html:
              schema:
                type: string
        404:
          description: Key not found in public keyring
          content:
            text/html:
              schema:
                type: string
  /system/pgp/{fpr}/export:
    get:
      tags:
        - PGP
      summary: Export a PGP key
      description: Exports the PGP key with the given fingerprint.
      operationId: exportPGPKey
      x-codeSamples:
        - lang: curl
          source: |
            curl -X GET "https://{host}/admin/system/pgp/<fingerprint>/export" \
              -u "<email>:<password>"
      responses:
        200:
          description: Successful operation
          content:
            text/plain:
              schema:
                $ref: '#/components/schemas/PgpKeyExport'
              example: |
                -----BEGIN PGP PUBLIC KEY BLOCK-----

                mQINBF957dABEADz7P2flznzRq5wuUhxDS+wytdn8yQhMXZr7kvcpwbRl9f7+dx3
                ...
                vo4j/rEYuOuqVo+TwsO0XNCfsA8as/UPLA9CgIxXXoIFmy2rL298lPQg5HgJ
                =via/
                -----END PGP PUBLIC KEY BLOCK-----
        403:
          description: Forbidden
          content:
            text/html:
              schema:
                type: string
        404:
          description: Key not found in public keyring
          content:
            text/html:
              schema:
                type: string
  /system/pgp/import:
    post:
      tags:
        - PGP
      summary: Import a PGP key
      description: Imports a PGP key block into the keyring. Only public keys are accepted.
      operationId: importPGPKey
      x-codeSamples:
        - lang: curl
          source: |
            curl -X POST "https://{host}/admin/system/pgp/import" \
              --data-urlencode "key=$(gpg --export --armor <fingerprint>)" \
              -u "<email>:<password>"
      responses:
        200:
          description: Successful operation
          content:
            text/plain:
              schema:
                $ref: '#/components/schemas/PgpKeyImportResult'
              example:
                keys_read: 1
                keys_added: 1
                keys_unchanged: 0
                uids_added: 0
                sigs_added: 0
                revs_added: 0
        400:
          description: Import refused
          content:
            text/plain:
              schema:
                type: string
              examples:
                private_key:
                  value: Import cannot contain private keys!
                invalid_format:
                  value: Import is not a valid PGP key block!
        403:
          description: Forbidden
          content:
            text/html:
              schema:
                type: string
  /system/pgp/wkd:
    get:
      tags:
        - WKD
      summary: Get WKD status
      description: Gets the current configuration applied to the Web Key Directory for each email hosted in the box, along with a JSON summary of all public PGP keys in the keyring.
      operationId: getWKDstatus
      x-codeSamples:
        - lang: curl
          source: |
            curl -X GET "https://{host}/admin/system/pgp/wkd" \
              -u "<email>:<password>"
      responses:
        200:
          description: Successful operation
          content:
            application/json:
              schema:
                type: object
                required:
                  - keys
                  - wkd
                properties:
                  keys:
                    type: array
                    items:
                      $ref: '#/components/schemas/PgpKey'
                  wkd:
                    type: object
                    # Because keys are dynamic (emails), there's not a lot we can do here :(
              example:
                keys:
                  - ids:
                    - Power Mail-in-a-Box Management Daemon <administrator@mailinabox.lan>
                    master_fpr: 62037B88B743626997E63EFE2469394FBC0CF8DA
                    revoked: false
                    subkeys:
                      - algorithm: RSA
                        auth: true
                        cert: true
                        encr: true
                        sign: true
                        bits: 4096
                        expired: false
                        expires: 1617378256
                        expires_date: 04/02/21
                        expires_days: 179
                        fpr: 62037B88B743626997E63EFE2469394FBC0CF8DA
                        master: true
                  - ids:
                    - Someone You Used To Know <nobody@nowhere>
                    master_fpr: B9BD7309D18784392D812050A174D33254CC2820
                    revoked: false
                    subkeys:
                      - algorithm: RSA
                        auth: true
                        cert: true
                        encr: true
                        sign: true
                        bits: 4096
                        expired: false
                        expires: 1615290372
                        expires_date: 03/09/21
                        expires_days: 155
                        fpr: B9BD7309D18784392D812050A174D33254CC2820
                        master: true
                  - ids:
                    - Linus Torvalds <torvalds@kernel.org>
                    - Linus Torvalds <torvalds@linux-foundation.org>
                    master_fpr: ABAF11C65A2970B130ABE3C479BE3E4300411886
                    revoked: false
                    subkeys:
                      - algorithm: RSA
                        auth: false
                        cert: true
                        encr: false
                        sign: true
                        bits: 2048
                        expired: false
                        expires: null
                        expires_date: null
                        expires_days: null
                        fpr: ABAF11C65A2970B130ABE3C479BE3E4300411886
                        master: true
                      - algorithm: RSA
                        auth: false
                        cert: false
                        encr: true
                        sign: false
                        bits: 2048
                        expired: false
                        expires: null
                        expires_date: null
                        expires_days: null
                        fpr: AEE416F7DCCB753BB3D5609D88BCE80F012F54CA
                        master: false
                wkd:
                  me@mailinabox.lan:
                    selection: null
                    options: []
                  administrator@mailinabox.lan:
                    selection: 62037B88B743626997E63EFE2469394FBC0CF8DA
                    options:
                      - 62037B88B743626997E63EFE2469394FBC0CF8DA
        403:
          description: Forbidden
          content:
            text/html:
              schema:
                type: string
  /ssl/status:
    get:
      tags:
        - SSL
      summary: Get SSL status
      description: Returns the SSL status for all domains.
      operationId: getSSLStatus
      x-codeSamples:
        - lang: curl
          source: |
            curl -X GET "https://{host}/admin/ssl/status" \
              -u "<email>:<password>"
      responses:
        200:
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SSLStatusResponse'
        403:
          description: Forbidden
          content:
            text/html:
              schema:
                type: string
  /ssl/csr/{domain}:
    post:
      tags:
        - SSL
      summary: Generate SSL CSR
      description: |
        Generates a Certificate Signing Request (CSR) for a domain & country code.
      operationId: generateSSLCSR
      parameters:
        - in: path
          name: domain
          schema:
            $ref: '#/components/schemas/Hostname'
          required: true
          description: Domain to generate CSR for.
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/SSLCSRGenerateRequest'
            example:
              countrycode: 'GB'
      x-codeSamples:
        - lang: curl
          source: |
            curl -X POST "https://{host}/admin/ssl/csr/<hostname>" \
              -d "countrycode=<string>" \
              -u "<email>:<password>"
      responses:
        200:
          description: Successful operation
          content:
            text/html:
              schema:
                $ref: '#/components/schemas/SSLCSRGenerateResponse'
              example: |
                -----BEGIN CERTIFICATE REQUEST-----
                MIICaDCCAVACAQAwIzELMAkGA1UEBhMCQlMxFDASBgNVBAMMC2V4YW1wbGUuY29t
                ...
                JmFDQESSfUxLPHLC660Wnf3GmrP/duZHpPC+qTe8b1AlQ7zDT3cOaAQ+Mb0=
                -----END CERTIFICATE REQUEST-----
        400:
          description: Bad request
          content:
            text/html:
              schema:
                type: string
        403:
          description: Forbidden
          content:
            text/html:
              schema:
                type: string
  /ssl/install:
    post:
      tags:
        - SSL
      summary: Install SSL certificate
      description: |
        Installs a custom certificate. The chain certificate is optional.
      operationId: installSSLCertificate
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/SSLCertificateInstallRequest'
            example:
              domain: example.com
              cert: CERT_STRING
              chain: CHAIN_STRING
      x-codeSamples:
        - lang: curl
          source: |
            curl -X POST "https://{host}/admin/ssl/install" \
              -d "domain=<hostname>" \
              -d "cert=<string>" \
              -d "chain=<string>" \
              -u "<email>:<password>"
      responses:
        200:
          description: Successful operation
          content:
            text/html:
              schema:
                $ref: '#/components/schemas/SSLCertificateInstallResponse'
              example: OK
        400:
          description: Bad request
          content:
            text/html:
              schema:
                type: string
        403:
          description: Forbidden
          content:
            text/html:
              schema:
                type: string
  /ssl/provision:
    post:
      tags:
        - SSL
      summary: Provision SSL certificates
      description: |
        Provisions certificates for all domains.
      operationId: provisionSSLCertificates
      x-codeSamples:
        - lang: curl
          source: |
            curl -X POST "https://{host}/admin/ssl/provision" \
              -u "<email>:<password>"
      responses:
        200:
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SSLCertificatesProvisionResponse'
        403:
          description: Forbidden
          content:
            text/html:
              schema:
                type: string
  /dns/secondary-nameserver:
    get:
      tags:
        - DNS
      summary: Get DNS secondary nameserver
      description: |
        Returns a list of nameserver hostnames.
      operationId: getDnsSecondaryNameserver
      x-codeSamples:
        - lang: curl
          source: |
            curl -X GET "https://{host}/admin/dns/secondary-nameserver" \
              -u "<email>:<password>"
      responses:
        200:
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DNSSecondaryNameserverResponse'
        403:
          description: Forbidden
          content:
            text/html:
              schema:
                type: string
    post:
      tags:
        - DNS
      summary: Add DNS secondary nameserver
      description: |
        Adds one or more secondary nameservers.
      operationId: addDnsSecondaryNameserver
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/DNSSecondaryNameserverAddRequest'
            example:
              hostnames: ns2.hostingcompany.com, ns3.hostingcompany.com
      x-codeSamples:
        - lang: curl
          source: |
            curl -X POST "https://{host}/admin/dns/secondary-nameserver" \
              -d "hostnames=<string>" \
              -u "<email>:<password>"
      responses:
        200:
          description: Successful operation
          content:
            text/html:
              schema:
                $ref: '#/components/schemas/DNSSecondaryNameserverAddResponse'
              example: 'updated DNS: example.com'
        400:
          description: Bad request
          content:
            text/html:
              schema:
                type: string
                example: Could not resolve the IP address of badhostname
        403:
          description: Forbidden
          content:
            text/html:
              schema:
                type: string
  /dns/zones:
    get:
      tags:
        - DNS
      summary: Get DNS zones
      description: Returns an array of all managed top-level domains.
      operationId: getDnsZones
      x-codeSamples:
        - lang: curl
          source: |
            curl -X GET "https://{host}/admin/dns/zones" \
              -u "<email>:<password>"
      responses:
        200:
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DNSZonesResponse'
        403:
          description: Forbidden
          content:
            text/html:
              schema:
                type: string
  /dns/zonefile/{zone}:
    parameters:
      - in: path
        name: zone
        schema:
          $ref: '#/components/schemas/Hostname'
        required: true
        description: Hostname
    get:
      tags:
        - DNS
      summary: Get DNS zonefile
      description: Returns a DNS zone file for a hostname.
      operationId: getDnsZonefile
      x-codeSamples:
        - lang: curl
          source: |
            curl -X GET "https://{host}/admin/dns/zonefile/<zone>" \
              -u "<email>:<password>"
      responses:
        200:
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DNSZonefileResponse'
        403:
          description: Forbidden
          content:
            text/html:
              schema:
                type: string
  /dns/update:
    post:
      tags:
        - DNS
      summary: Update DNS
      description: Updates the DNS. Involves creating zone files and restarting `nsd`.
      operationId: updateDns
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/DNSUpdateRequest'
            example:
              force: 1
      x-codeSamples:
        - lang: curl
          source: |
            curl -X POST "https://{host}/admin/dns/update" \
              -d "force=<integer>" \
              -u "<email>:<password>"
      responses:
        200:
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DNSUpdateResponse'
        400:
          description: Bad request
          content:
            text/html:
              schema:
                type: string
        403:
          description: Forbidden
          content:
            text/html:
              schema:
                type: string
  /dns/custom:
    get:
      tags:
        - DNS
      summary: Get DNS custom records
      description: Returns all custom DNS records.
      operationId: getDnsCustomRecords
      x-codeSamples:
        - lang: curl
          source: |
            curl -X GET "https://{host}/admin/dns/custom" \
              -u "<email>:<password>"
      responses:
        200:
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DNSCustomRecordsResponse'
        403:
          description: Forbidden
          content:
            text/html:
              schema:
                type: string
  /dns/custom/{qname}/{rtype}:
    parameters:
      - in: path
        name: qname
        schema:
          $ref: '#/components/schemas/Hostname'
        required: true
        description: DNS record query name
      - in: path
        name: rtype
        schema:
          $ref: '#/components/schemas/DNSRecordType'
        required: true
        description: Record type
    get:
      tags:
        - DNS
      summary: Get DNS custom records
      description: Returns all custom records for the specified query name and type.
      operationId: getDnsCustomRecordsForQNameAndType
      x-codeSamples:
        - lang: curl
          source: |
            curl -X GET "https://{host}/admin/dns/custom/<qname>/<rtype>" \
              -u "<email>:<password>"
      responses:
        200:
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DNSCustomRecordsResponse'
        403:
          description: Forbidden
          content:
            text/html:
              schema:
                type: string
    post:
      tags:
        - DNS
      summary: Add DNS custom record
      description: Adds a custom DNS record for the specified query name and type.
      operationId: addDnsCustomRecord
      requestBody:
        $ref: '#/components/requestBodies/DNSCustomRecordRequest'
      x-codeSamples:
        - lang: curl
          source: |
            curl -X POST "https://{host}/admin/dns/custom/<qname>/<rtype>" \
              -H "Content-Type: text/plain" \
              --data-raw "<string>" \
              -u "<email>:<password>"
      responses:
        200:
          description: Successful operation
          content:
            text/html:
              schema:
                $ref: '#/components/schemas/DNSCustomRecordUpsertResponse'
              example: 'updated DNS: example.com'
        400:
          description: Bad request
          content:
            text/html:
              schema:
                type: string
                example: "'badhostname' does not appear to be an IPv4 or IPv6 address"
        403:
          description: Forbidden
          content:
            text/html:
              schema:
                type: string
    put:
      tags:
        - DNS
      summary: Update DNS custom record
      description: Updates an existing DNS custom record value for the specified qname and type.
      operationId: updateDnsCustomRecord
      requestBody:
        $ref: '#/components/requestBodies/DNSCustomRecordRequest'
      x-codeSamples:
        - lang: curl
          source: |
            curl -x PUT "https://{host}/admin/dns/custom/<qname>/<rtype>" \
              -H "Content-Type: text/plain" \
              --data-raw "<string>" \
              -u "<email>:<password>"
      responses:
        200:
          description: Successful operation
          content:
            text/html:
              schema:
                $ref: '#/components/schemas/DNSCustomRecordUpsertResponse'
              example: 'updated DNS: example.com'
        400:
          description: Bad request
          content:
            text/html:
              schema:
                type: string
                example: "'badhostname' does not appear to be an IPv4 or IPv6 address"
        403:
          description: Forbidden
          content:
            text/html:
              schema:
                type: string
    delete:
      tags:
        - DNS
      summary: Remove DNS custom record
      description: Removes a DNS custom record for the specified domain, type & value.
      operationId: removeDnsCustomRecord
      requestBody:
        $ref: '#/components/requestBodies/DNSCustomRecordRequest'
      x-codeSamples:
        - lang: curl
          source: |
            curl -X DELETE "https://{host}/admin/dns/custom/<qname>/<rtype>" \
              -H "Content-Type: text/plain" \
              --data-raw "<string>" \
              -u "<email>:<password>"
      responses:
        200:
          description: Successful operation
          content:
            text/html:
              schema:
                $ref: '#/components/schemas/DNSCustomRecordRemoveResponse'
              example: 'updated DNS: example.com'
        400:
          description: Bad request
          content:
            text/html:
              schema:
                type: string
                example: badhostname is not a domain name or a subdomain of a domain name managed by this box
        403:
          description: Forbidden
          content:
            text/html:
              schema:
                type: string
  /dns/custom/{qname}:
    parameters:
      - in: path
        name: qname
        schema:
          $ref: '#/components/schemas/Hostname'
        required: true
        description: DNS query name.
    get:
      tags:
        - DNS
      summary: Get DNS custom A records
      description: Returns all custom A records for the specified query name.
      operationId: getDnsCustomARecordsForQName
      x-codeSamples:
        - lang: curl
          source: |
            curl -X GET "https://{host}/admin/dns/custom/<qname>" \
              -u "<email>:<password>"
      responses:
        200:
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DNSCustomRecordsResponse'
        403:
          description: Forbidden
          content:
            text/html:
              schema:
                type: string
    post:
      tags:
        - DNS
      summary: Add DNS custom A record
      description: Adds a custom DNS A record for the specified query name.
      operationId: addDnsCustomARecord
      requestBody:
        $ref: '#/components/requestBodies/DNSCustomRecordRequest'
      x-codeSamples:
        - lang: curl
          source: |
            curl -X POST "https://{host}/admin/dns/custom/<qname>" \
              -H "Content-Type: text/plain" \
              --data-raw "<string>" \
              -u "<email>:<password>"
      responses:
        200:
          description: Successful operation
          content:
            text/html:
              schema:
                $ref: '#/components/schemas/DNSCustomRecordUpsertResponse'
              example: 'updated DNS: example.com'
        400:
          description: Bad request
          content:
            text/html:
              schema:
                type: string
                example: "'badhostname' does not appear to be an IPv4 or IPv6 address"
        403:
          description: Forbidden
          content:
            text/html:
              schema:
                type: string
    put:
      tags:
        - DNS
      summary: Update DNS custom A record
      description: Updates an existing DNS custom A record value for the specified qname.
      operationId: updateDnsCustomARecord
      requestBody:
        $ref: '#/components/requestBodies/DNSCustomRecordRequest'
      x-codeSamples:
        - lang: curl
          source: |
            curl -x PUT "https://{host}/admin/dns/custom/<qname>" \
              -H "Content-Type: text/plain" \
              --data-raw "<string>" \
              -u "<email>:<password>"
      responses:
        200:
          description: Successful operation
          content:
            text/html:
              schema:
                $ref: '#/components/schemas/DNSCustomRecordUpsertResponse'
              example: 'updated DNS: example.com'
        400:
          description: Bad request
          content:
            text/html:
              schema:
                type: string
                example: "'badhostname' does not appear to be an IPv4 or IPv6 address"
        403:
          description: Forbidden
          content:
            text/html:
              schema:
                type: string
    delete:
      tags:
        - DNS
      summary: Remove DNS custom A record
      description: Removes a DNS custom A record for the specified domain & value.
      operationId: removeDnsCustomARecord
      requestBody:
        $ref: '#/components/requestBodies/DNSCustomRecordRequest'
      x-codeSamples:
        - lang: curl
          source: |
            curl -X DELETE "https://{host}/admin/dns/custom/<qname>" \
              -H "Content-Type: text/plain" \
              --data-raw "<string>" \
              -u "<email>:<password>"
      responses:
        200:
          description: Successful operation
          content:
            text/html:
              schema:
                $ref: '#/components/schemas/DNSCustomRecordRemoveResponse'
              example: 'updated DNS: example.com'
        400:
          description: Bad request
          content:
            text/html:
              schema:
                type: string
                example: badhostname is not a domain name or a subdomain of a domain name managed by this box
        403:
          description: Forbidden
          content:
            text/html:
              schema:
                type: string
  /dns/dump:
    get:
      tags:
        - DNS
      summary: Get DNS dump
      description: Returns all DNS records.
      operationId: getDnsDump
      x-codeSamples:
        - lang: curl
          source: |
            curl -X GET "https://{host}/admin/dns/dump" \
              -u "<email>:<password>"
      responses:
        200:
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DNSDumpResponse'
              example:
                - - example1.com
                  - - explanation: Required. Specifies the hostname (and priority) of the machine that handles @example.com mail.
                      qname: example1.com
                      rtype: MX
                      value: 10 box.example1.com.
                - - example2.com
                  - - explanation: Required. Specifies the hostname (and priority) of the machine that handles @example.com mail.
                      qname: example2.com
                      rtype: MX
                      value: 10 box.example2.com.
        403:
          description: Forbidden
          content:
            text/html:
              schema:
                type: string
  /mail/users:
    get:
      tags:
        - Mail
      summary: Get mail users
      description: Returns all mail users.
      operationId: getMailUsers
      parameters:
        - in: query
          name: format
          schema:
            $ref: '#/components/schemas/MailUsersResponseFormat'
          description: The format of the response.
      x-codeSamples:
        - lang: curl
          source: |
            curl -X GET "https://{host}/admin/mail/users?format=<string>" \
              -u "<email>:<password>"
      responses:
        200:
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MailUsersResponse'
            text/html:
              schema:
                $ref: '#/components/schemas/MailUsersSimpleResponse'
              example: |
                user1@example.com
                user2@example.com
        403:
          description: Forbidden
          content:
            text/html:
              schema:
                type: string
  /mail/users/add:
    post:
      tags:
        - Mail
      summary: Add mail user
      description: Adds a new mail user.
      operationId: addMailUser
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/MailUserAddRequest'
            examples:
              normal:
                summary: Normal user
                value:
                  email: user@example.com
                  password: s3curE_pa5Sw0rD
                  privileges: ''
              admin:
                summary: Admin user
                value:
                  email: user@example.com
                  password: s3curE_pa5Sw0rD
                  privileges: admin
      x-codeSamples:
        - lang: curl
          source: |
            curl -X POST "https://{host}/admin/mail/users/add" \
              -d "email=<email>" \
              -d "password=<password>" \
              -d "privileges=<string>" \
              -u "<email>:<password>"
      responses:
        200:
          description: Successful operation
          content:
            text/html:
              schema:
                $ref: '#/components/schemas/MailUserAddResponse'
              example: |
                mail user added
                updated DNS: OpenDKIM configuration
        400:
          description: Bad request
          content:
            text/html:
              schema:
                type: string
                example: Invalid email address
        403:
          description: Forbidden
          content:
            text/html:
              schema:
                type: string
  /mail/users/remove:
    post:
      tags:
        - Mail
      summary: Remove mail user
      description: Removes an existing mail user.
      operationId: removeMailUser
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/MailUserRemoveRequest'
            example:
              email: user@example.com
      x-codeSamples:
        - lang: curl
          source: |
            curl -X POST "https://{host}/admin/mail/users/remove" \
              -d "email=<email>" \
              -u "<email>:<password>"
      responses:
        200:
          description: Successful operation
          content:
            text/html:
              schema:
                $ref: '#/components/schemas/MailUserRemoveResponse'
              example: OK
        400:
          description: Bad request
          content:
            text/html:
              schema:
                type: string
                example: That's not a user (invalid@example.com)
        403:
          description: Forbidden
          content:
            text/html:
              schema:
                type: string
  /mail/users/privileges/add:
    post:
      tags:
        - Mail
      summary: Add mail user privilege
      description: Adds a privilege to an existing mail user.
      operationId: addMailUserPrivilege
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/MailUserAddPrivilegeRequest'
            example:
              email: user@example.com
              privilege: admin
      x-codeSamples:
        - lang: curl
          source: |
            curl -X POST "https://{host}/admin/mail/users/privileges/add" \
              -d "email=<email>" \
              -d "privilege=<string>" \
              -u "<email>:<password>"
      responses:
        200:
          description: Successful operation
          content:
            text/html:
              schema:
                $ref: '#/components/schemas/MailUserAddPrivilegeResponse'
              example: OK
        400:
          description: Bad request
          content:
            text/html:
              schema:
                type: string
                example: That's not a user (invalid@example.com)
        403:
          description: Forbidden
          content:
            text/html:
              schema:
                type: string
  /mail/users/privileges/remove:
    post:
      tags:
        - Mail
      summary: Remove mail user privilege
      description: Removes a privilege from an existing mail user.
      operationId: removeMailUserPrivilege
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/MailUserRemovePrivilegeRequest'
            example:
              email: user@example.com
              privilege: admin
      x-codeSamples:
        - lang: curl
          source: |
            curl -X POST "https://{host}/admin/mail/users/privileges/remove" \
              -d "email=<email>" \
              -d "privilege=<string>" \
              -u "<email>:<password>"
      responses:
        200:
          description: Successful operation
          content:
            text/html:
              schema:
                $ref: '#/components/schemas/MailUserRemovePrivilegeResponse'
              example: OK
        400:
          description: Bad request
          content:
            text/html:
              schema:
                type: string
                example: That's not a user (invalid@example.com)
        403:
          description: Forbidden
          content:
            text/html:
              schema:
                type: string
  /mail/users/password:
    post:
      tags:
        - Mail
      summary: Set mail user password
      description: Sets a password for an existing mail user.
      operationId: setMailUserPassword
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/MailUserSetPasswordRequest'
            example:
              email: user@example.com
              password: s3curE_pa5Sw0rD
      x-codeSamples:
        - lang: curl
          source: |
            curl -X POST "https://{host}/admin/mail/users/password" \
              -d "email=<email>" \
              -d "password=<password>" \
              -u "<email>:<password>" \
      responses:
        200:
          description: Successful operation
          content:
            text/html:
              schema:
                $ref: '#/components/schemas/MailUserSetPasswordResponse'
              example: OK
        400:
          description: Bad request
          content:
            text/html:
              schema:
                type: string
                example: Passwords must be at least eight characters
        403:
          description: Forbidden
          content:
            text/html:
              schema:
                type: string
  /mail/users/privileges:
    get:
      tags:
        - Mail
      summary: Get mail user privileges
      description: Returns all privileges for an existing mail user.
      operationId: getMailUserPrivileges
      parameters:
        - in: query
          name: email
          schema:
            $ref: '#/components/schemas/Email'
          description: The email you want to get privileges for.
      x-codeSamples:
        - lang: curl
          source: |
            curl -X GET "https://{host}/admin/mail/users/privileges?email=<email>" \
              -u "<email>:<password>"
      responses:
        200:
          description: Successful operation
          content:
            text/html:
              schema:
                $ref: '#/components/schemas/MailUserPrivilegesResponse'
              example: admin
        403:
          description: Forbidden
          content:
            text/html:
              schema:
                type: string
  /mail/domains:
    get:
      tags:
        - Mail
      summary: Get mail domains
      description: Returns all mail domains.
      operationId: getMailDomains
      x-codeSamples:
        - lang: curl
          source: |
            curl -X GET "https://{host}/admin/mail/domains" \
              -u "<email>:<password>"
      responses:
        200:
          description: Successful operation
          content:
            text/html:
              schema:
                $ref: '#/components/schemas/MailDomainsResponse'
              example: |
                example1.com
                example2.com
        403:
          description: Forbidden
          content:
            text/html:
              schema:
                type: string
  /mail/aliases:
    get:
      tags:
        - Mail
      summary: Get mail aliases
      description: Returns all mail aliases.
      operationId: getMailAliases
      parameters:
        - in: query
          name: format
          schema:
            $ref: '#/components/schemas/MailAliasesResponseFormat'
          description: The format of the response.
      x-codeSamples:
        - lang: curl
          source: |
            curl -X GET "https://{host}/admin/mail/aliases?format=<string>" \
              -u "<email>:<password>"
      responses:
        200:
          description: Successful operation
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/MailAliasByDomain'
            text/html:
              schema:
                $ref: '#/components/schemas/MailAliasesSimpleResponse'
                example: |
                  abuse@example.com	administrator@example.com
                  admin@example.com	administrator@example.com
        403:
          description: Forbidden
          content:
            text/html:
              schema:
                type: string
  /mail/aliases/add:
    post:
      tags:
        - Mail
      summary: Upsert mail alias
      description: |
        Adds or updates a mail alias. If updating, you need to set `update_if_exists: 1`.
      operationId: upsertMailAlias
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/MailAliasUpsertRequest'
            examples:
              regular:
                summary: Regular alias
                value:
                  update_if_exists: 0
                  address: user@example.com
                  forwards_to: user2@example.com
                  permitted_senders:
              catchall:
                summary: Catch-all
                value:
                  update_if_exists: 0
                  address: '@example.com'
                  forwards_to: user@otherexample.com
                  permitted_senders:
              domainalias:
                summary: Domain alias
                value:
                  update_if_exists: 0
                  address: '@example.com'
                  forwards_to: '@otherexample.com'
                  permitted_senders:
              update:
                summary: Update existing alias
                value:
                  update_if_exists: 1
                  address: user@example.com
                  forwards_to: user2@example.com
                  permitted_senders: user3@example.com, user4@example.com
      x-codeSamples:
        - lang: curl
          source: |
            curl -X POST "https://{host}/admin/mail/aliases/add" \
              -d "update_if_exists=<integer>" \
              -d "address=<email>" \
              -d "forwards_to=<string>" \
              -d "permitted_senders=<string>" \
              -u "<email>:<password>"
      responses:
        200:
          description: Successful operation
          content:
            text/html:
              schema:
                $ref: '#/components/schemas/MailAliasUpsertResponse'
              example: alias updated
        400:
          description: Bad request
          content:
            text/html:
              schema:
                type: string
                example: Invalid email address (invalid@example.com)
        403:
          description: Forbidden
          content:
            text/html:
              schema:
                type: string
  /mail/aliases/remove:
    post:
      tags:
        - Mail
      summary: Remove mail alias
      description: Removes a mail alias.
      operationId: removeMailAlias
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/MailAliasRemoveRequest'
            example:
              address: user@example.com
      x-codeSamples:
        - lang: curl
          source: |
            curl -X POST "https://{host}/admin/mail/aliases/remove" \
              -d "address=<email>" \
              -u "<email>:<password>"
      responses:
        200:
          description: Successful operation
          content:
            text/html:
              schema:
                $ref: '#/components/schemas/MailAliasRemoveResponse'
              example: alias removed
        400:
          description: Bad request
          content:
            text/html:
              schema:
                type: string
                example: That's not an alias (invalid@example)
        403:
          description: Forbidden
          content:
            text/html:
              schema:
                type: string
  /web/domains:
    get:
      tags:
        - Web
      summary: Get web domains
      description: Returns all static web domains.
      operationId: getWebDomains
      x-codeSamples:
        - lang: curl
          source: |
            curl -X GET "https://{host}/admin/web/domains" \
              -u "<email>:<password>"
      responses:
        200:
          description: Successful operation
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/WebDomain'
        403:
          description: Forbidden
          content:
            text/html:
              schema:
                type: string
  /web/update:
    post:
      tags:
        - Web
      summary: Update web
      description: Updates static websites, used for updating domain root directories.
      operationId: updateWeb
      x-codeSamples:
        - lang: curl
          source: |
            curl -X POST "https://{host}/admin/web/update" \
              -u "<email>:<password>"
      responses:
        200:
          description: Successful operation
          content:
            text/html:
              schema:
                $ref: '#/components/schemas/WebUpdateResponse'
              example: web updated
        403:
          description: Forbidden
          content:
            text/html:
              schema:
                type: string
  /mfa/status:
    post:
      tags:
        - MFA
      summary: Retrieve MFA status for you or another user
      description: Retrieves which type of MFA is used and configuration
      operationId: mfaStatus
      x-codeSamples:
        - lang: curl
          source: |
            curl -X POST "https://{host}/admin/mfa/status" \
              -u "<email>:<password>"
      responses:
        200:
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MfaStatusResponse'
        403:
          description: Forbidden
          content:
            text/html:
              schema:
                type: string
  /mfa/totp/enable:
    post:
      tags:
        - MFA
      summary: Enable TOTP authentication
      description: Enables TOTP authentication for the currently logged-in admin user
      operationId: mfaTotpEnable
      x-codeSamples:
        - lang: curl
          source: |
            curl -X POST "https://{host}/admin/mfa/totp/enable" \
              -d "code=123456" \
              -d "secret=<string>" \
              -u "<email>:<password>"
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/MfaEnableRequest'
      responses:
        200:
          description: Successful operation
          content:
            text/html:
              schema:
                $ref: '#/components/schemas/MfaEnableSuccessResponse'
        400:
          description: Bad request
          content:
            text/html:
              schema:
                type: string
        403:
          description: Forbidden
          content:
            text/html:
              schema:
                type: string
  /mfa/disable:
    post:
      tags:
        - MFA
      summary: Disable multi-factor authentication for you or another user
      description: Disables multi-factor authentication for the currently logged-in admin user or another user if a 'user' parameter is submitted. Either disables all multi-factor authentication methods or the method corresponding to the optional property `mfa_id`.
      operationId: mfaTotpDisable
      requestBody:
        required: false
        content:
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/MfaDisableRequest'
      x-codeSamples:
        - lang: curl
          source: |
            curl -X POST "https://{host}/admin/mfa/totp/disable" \
              -u "<email>:<user_key>"
      responses:
        200:
          description: Successful operation
          content:
            text/html:
              schema:
                $ref: '#/components/schemas/MfaDisableSuccessResponse'
        403:
          description: Forbidden
          content:
            text/html:
              schema:
                type: string
components:
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic
      description: |
        Credentials can be supplied using the `Authorization` header in
        format `Authorization: Basic {access-token}`.

        The `access-token` is comprised of the Base64 encoding of `username:password`.
        The `username` is the mail user's email address, and `password` can either be the mail user's
        password, or the `api_key` returned from the `login` operation.

        When using `curl`, you can supply user credentials using the `-u` or `--user` parameter.
  requestBodies:
    DNSCustomRecordRequest:
      required: true
      content:
        text/plain:
          schema:
            type: string
            example: '1.2.3.4'
            description: The value of the DNS record.
          example: '1.2.3.4'
  schemas:
    MailUsersResponseFormat:
      type: string
      enum:
        - text
        - json
      example: json
      description: Response format (`application/json` or `text/html`).
    MailAliasesResponseFormat:
      type: string
      enum:
        - text
        - json
      example: json
      description: Response format (`application/json` or `text/html`).
    MailUserSetPasswordResponse:
      type: string
      example: OK
      description: Mail user set password response.
    MailUserRemoveResponse:
      type: string
      example: OK
      description: Mail user remove response.
    MailUserAddResponse:
      type: string
      example: |
        mail user added
        updated DNS: OpenDKIM configuration
      description: |
        Mail user add response.

        Can include information about operations related to adding new users, like updating DNS.
    MailUserAddPrivilegeResponse:
      type: string
      example: OK
      description: Mail user add admin privilege response.
    MailUserRemovePrivilegeResponse:
      type: string
      example: OK
      description: Mail user remove admin privilege response.
    MailUsersSimpleResponse:
      type: string
      example: |
        user1@example.com
        user2@example.com
      description: Get mail users text format response.
    MailUserPrivilegesResponse:
      $ref: '#/components/schemas/MailUserPrivilege'
      description: Mail user privileges response.
      example: admin
    MailDomainsResponse:
      type: string
      example: |
        example1.com
        example2.com
      description: Mail domains response.
    MailUsersResponse:
      type: array
      items:
        $ref: '#/components/schemas/MailUserByDomain'
      description: Get mail aliases JSON format response.
    MailUserByDomain:
      type: object
      required:
        - domain
        - users
      properties:
        domain:
          $ref: '#/components/schemas/Hostname'
        users:
          type: array
          items:
            $ref: '#/components/schemas/MailUser'
      description: Mail users by domain.
    MailUser:
      type: object
      required:
        - email
        - privileges
        - status
      properties:
        email:
          $ref: '#/components/schemas/Email'
        privileges:
          type: array
          items:
            $ref: '#/components/schemas/MailUserPrivilege'
        status:
          $ref: '#/components/schemas/MailUserStatus'
        mailbox:
          type: string
          example: /home/user-data/mail/mailboxes/example.com/user
      description: Mail user details.
    MailAliasesSimpleResponse:
      type: string
      example: |
        abuse@example.com	administrator@example.com
        admin@example.com	administrator@example.com
      description: Get mail aliases text format response.
    MailAliasByDomain:
      type: object
      required:
        - domain
        - aliases
      properties:
        domain:
          $ref: '#/components/schemas/Hostname'
        aliases:
          type: array
          items:
            $ref: '#/components/schemas/MailAlias'
      description: Mail aliases by domain.
    MailAlias:
      type: object
      required:
        - address
        - address_display
        - forwards_to
        - permitted_senders
        - required
      properties:
        address:
          $ref: '#/components/schemas/Email'
        address_display:
          $ref: '#/components/schemas/Email'
        forwards_to:
          type: array
          items:
            $ref: '#/components/schemas/Email'
        permitted_senders:
          type: array
          nullable: true
          items:
            $ref: '#/components/schemas/Email'
        required:
          type: boolean
          example: true
      description: Mail alias details.
    MailAliasUpsertResponse:
      type: string
      example: alias updated
      description: Mail alias add/update response.
    MailAliasUpsertRequest:
      type: object
      required:
        - update_if_exists
        - address
        - forwards_to
        - permitted_senders
      properties:
        update_if_exists:
          type: integer
          format: int32
          minimum: 0
          maximum: 1
          example: 1
          description: Set to `1` when updating an alias.
        address:
          $ref: '#/components/schemas/Email'
        forwards_to:
          type: string
          example: user1@example.com, user2@example.com
          description: |
            If adding a regular or catch-all alias, the format needs to be `user@example.com`.
            Multiple address can be separated by newlines or commas.

            If adding a domain alias, the format needs to be `@example.com`.
        permitted_senders:
          type: string
          nullable: true
          example: user1@example.com, user2@example.com
          description: |
            Mail users that can send mail claiming to be from any address on the alias domain.
            Multiple address can be separated by newlines or commas.

            Leave empty to allow any mail user listed in `forwards_to` to send mail claiming to be from any address on the alias domain.
      description: Mail alias upsert request.
    MailAliasRemoveResponse:
      type: string
      example: alias removed
      description: Mail alias remove response.
    MailAliasRemoveRequest:
      type: object
      required:
        - address
      properties:
        address:
          $ref: '#/components/schemas/Email'
      description: Mail aliases remove request.
    DNSRecordType:
      enum:
        - A
        - AAAA
        - CAA
        - CNAME
        - TXT
        - MX
        - SRV
        - SSHFP
        - NS
      example: MX
      description: DNS record type.
    DNSDumpResponse:
      type: array
      items:
        $ref: '#/components/schemas/DNSDumpDomains'
      description: DNS dump response.
    DNSDumpDomains:
      type: array
      items:
        oneOf:
          - $ref: '#/components/schemas/Hostname'
          - $ref: '#/components/schemas/DNSDumpDomainRecords'
      description: |
        A list of records per domain.

        The first item in the list is the domain and the second item is the list of records.
    DNSDumpDomainRecords:
      type: array
      items:
        $ref: '#/components/schemas/DNSDumpDomainRecord'
      description: List of domain records.
    DNSDumpDomainRecord:
      type: object
      required:
        - explanation
        - qname
        - type
        - value
      properties:
        explanation:
          type: string
          example: Required. Specifies the hostname (and priority) of the machine that handles @example.com mail
        qname:
          $ref: '#/components/schemas/Hostname'
        rtype:
          $ref: '#/components/schemas/DNSRecordType'
        value:
          type: string
          example: 10 example.com.
      description: Domain DNS record details.
    DNSCustomRecord:
      type: object
      required:
        - qname
        - rtype
        - value
      properties:
        qname:
          $ref: '#/components/schemas/Hostname'
        rtype:
          $ref: '#/components/schemas/DNSRecordType'
        value:
          type: string
          example: 10 example.com.
      description: Custom DNS record detail detail.
    DNSCustomRecordsResponse:
      type: array
      items:
        $ref: '#/components/schemas/DNSCustomRecord'
      description: Custom DNS records response.
    DNSZonesResponse:
      type: array
      items:
        $ref: '#/components/schemas/Hostname'
      description: DNS zones response.
    DNSZonefileResponse:
      type: string
    DNSSecondaryNameserverResponse:
      type: object
      required:
        - hostnames
      properties:
        hostnames:
          type: array
          items:
            type: string
            example: ns1.example.com
      description: Secondary nameserver/s response.
    DNSCustomRecordRemoveResponse:
      type: string
      example: 'updated DNS: example.com'
      description: Custom DNS record remove response.
    DNSCustomRecordUpsertResponse:
      type: string
      example: 'updated DNS: example.com'
      description: Custom DNS record add response.
    DNSUpdateRequest:
      type: object
      required:
        - force
      properties:
        force:
          type: integer
          format: int32
          minimum: 0
          maximum: 1
          example: 1
          description: Force an update even if mailinabox detects no changes are required.
      description: DNS update request.
    DNSUpdateResponse:
      type: string
      example: |
        updated DNS: example1.com,example2.com
      description: DNS update response.
    DNSSecondaryNameserverAddRequest:
      type: object
      required:
        - hostnames
      properties:
        hostnames:
          type: string
          description: Hostnames separated with commas or spaces.
          example: ns2.hostingcompany.com, ns3.hostingcompany.com
      description: Secondary nameserver/s add request.
    DNSSecondaryNameserverAddResponse:
      type: string
      example: 'updated DNS: example.com'
      description: Secondary nameserver/s add response.
    SystemPrivacyUpdateRequest:
      type: object
      required:
        - value
      properties:
        value:
          $ref: '#/components/schemas/SystemPrivacyStatus'
      description: Update system privacy request.
    SystemPrivacyStatus:
      type: string
      enum:
        - private
        - 'off'
      example: private
      description: System privacy status.
    MailUserSetPasswordRequest:
      type: object
      required:
        - email
        - password
      properties:
        email:
          $ref: '#/components/schemas/Email'
        password:
          type: string
          format: password
      description: Mail user set password request.
    MailUserAddRequest:
      type: object
      required:
        - email
        - password
        - privileges
      properties:
        email:
          $ref: '#/components/schemas/Email'
        password:
          type: string
          format: password
        privileges:
          $ref: '#/components/schemas/MailUserPrivilege'
      description: Mail user add request.
    MailUserRemoveRequest:
      type: object
      required:
        - email
      properties:
        email:
          $ref: '#/components/schemas/Email'
      description: Mail user remove request.
    MailUserStatus:
      type: string
      enum:
        - active
        - inactive
      example: active
      description: Mail user status.
    MailUserPrivilege:
      type: string
      enum:
        - admin
        - ''
      example: admin
      description: Mail user privilege.
    MailUserAddPrivilegeRequest:
      type: object
      required:
        - email
        - privilege
      properties:
        email:
          $ref: '#/components/schemas/Email'
        privilege:
          $ref: '#/components/schemas/MailUserPrivilege'
      description: Mail user add privilege request.
    MailUserRemovePrivilegeRequest:
      type: object
      required:
        - email
        - privilege
      properties:
        email:
          $ref: '#/components/schemas/Email'
        privilege:
          $ref: '#/components/schemas/MailUserPrivilege'
      description: Mail user remove privilege request.
    SSLCSRGenerateRequest:
      type: object
      required:
        - countrycode
      properties:
        countrycode:
          type: string
          example: GB
      description: Generate SSL CSR request.
    SSLCSRGenerateResponse:
      type: string
      example: |
        -----BEGIN CERTIFICATE REQUEST-----
        MIICaDCCAVACAQAwIzELMAkGA1UEBhMCQlMxFDASBgNVBAMMC2V4YW1wbGUuY29t
        MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA3K6dwLM2Nk8kVhIBaZmp
        eY6y7O0T3jrexEKlW839TVYdcH+K35V1NxilbMFKMuHeowGwFyyiqOy/OUYNeq+T
        Rz3s4b1qG2p01dwlsXHHYmXLYTAhvqvY+CU5ksieuZbyHRTwbHViQ0xtRXwoVCnj
        CkN7kJVpkLfVN0/BG6NBFpv/JI8F+hwp+IHdkC1gUXRrLJNC79ERqFP8HoqdQWNw
        OGGFaOe2aQhvj2zt8wFncyKVc40UKVbSzGGzdL2MPiAJHgZ2lmeY1xDyX1lOt12R
        IFPwtxmbxaxYaVfe2hxl7m88xV3OjYcKgwVYDusk2XJ37cGew5g+NbBvzEeEUpF9
        5wIDAQABoAAwDQYJKoZIhvcNAQELBQADggEBAD7UPC3/Nkgpn53mT9puUonYdJg9
        SD8vvTK/N78CzoEgPNyq+bYbqlcvVPKIdItf9TMiqfOSvW3e3NvkRisYle8Qp+0C
        8pafXBvQ9eHt5CFeJn4sH9GnxeflOZT/P9Jnp71KtZQvOobirX4GgEWs79g+/NHb
        Zyf8rbadt9HruNhKA5nlP8cn7Rdc/iuJU8MVSQszI1s1DEcXMPxr6iqb2g87/ifH
        lWcK59kvRJkCcPhPzjpUy9NulucH4WFA/WqKeDNFS/oC+upV5w8EDEcfnenJFG+N
        JmFDQESSfUxLPHLC660Wnf3GmrP/duZHpPC+qTe8b1AlQ7zDT3cOaAQ+Mb0=
        -----END CERTIFICATE REQUEST-----
      description: Generate SSL CSR response.
    SSLCertificateInstallRequest:
      type: object
      required:
        - domain
        - cert
        - chain
      properties:
        domain:
          $ref: '#/components/schemas/Hostname'
        cert:
          type: string
          description: TLS/SSL certificate.
          example: |
            -----BEGIN CERTIFICATE-----
            MIICaDCCAVACAQAwIzELMAkGA1UEBhMCQlMxFDASBgNVBAMMC2V4YW1wbGUuY29t
            MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA3K6dwLM2Nk8kVhIBaZmp
            eY6y7O0T3jrexEKlW839TVYdcH+K35V1NxilbMFKMuHeowGwFyyiqOy/OUYNeq+T
            Rz3s4b1qG2p01dwlsXHHYmXLYTAhvqvY+CU5ksieuZbyHRTwbHViQ0xtRXwoVCnj
            CkN7kJVpkLfVN0/BG6NBFpv/JI8F+hwp+IHdkC1gUXRrLJNC79ERqFP8HoqdQWNw
            OGGFaOe2aQhvj2zt8wFncyKVc40UKVbSzGGzdL2MPiAJHgZ2lmeY1xDyX1lOt12R
            IFPwtxmbxaxYaVfe2hxl7m88xV3OjYcKgwVYDusk2XJ37cGew5g+NbBvzEeEUpF9
            5wIDAQABoAAwDQYJKoZIhvcNAQELBQADggEBAD7UPC3/Nkgpn53mT9puUonYdJg9
            SD8vvTK/N78CzoEgPNyq+bYbqlcvVPKIdItf9TMiqfOSvW3e3NvkRisYle8Qp+0C
            8pafXBvQ9eHt5CFeJn4sH9GnxeflOZT/P9Jnp71KtZQvOobirX4GgEWs79g+/NHb
            Zyf8rbadt9HruNhKA5nlP8cn7Rdc/iuJU8MVSQszI1s1DEcXMPxr6iqb2g87/ifH
            lWcK59kvRJkCcPhPzjpUy9NulucH4WFA/WqKeDNFS/oC+upV5w8EDEcfnenJFG+N
            JmFDQESSfUxLPHLC660Wnf3GmrP/duZHpPC+qTe8b1AlQ7zDT3cOaAQ+Mb0=
            -----END CERTIFICATE-----
        chain:
          type: string
          description: TLS/SSL intermediate chain (if provided, else empty string).
          example: |
            -----BEGIN CERTIFICATE-----
            MIICaDCCAVACAQAwIzELMAkGA1UEBhMCQlMxFDASBgNVBAMMC2V4YW1wbGUuY29t
            MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA3K6dwLM2Nk8kVhIBaZmp
            eY6y7O0T3jrexEKlW839TVYdcH+K35V1NxilbMFKMuHeowGwFyyiqOy/OUYNeq+T
            Rz3s4b1qG2p01dwlsXHHYmXLYTAhvqvY+CU5ksieuZbyHRTwbHViQ0xtRXwoVCnj
            CkN7kJVpkLfVN0/BG6NBFpv/JI8F+hwp+IHdkC1gUXRrLJNC79ERqFP8HoqdQWNw
            OGGFaOe2aQhvj2zt8wFncyKVc40UKVbSzGGzdL2MPiAJHgZ2lmeY1xDyX1lOt12R
            IFPwtxmbxaxYaVfe2hxl7m88xV3OjYcKgwVYDusk2XJ37cGew5g+NbBvzEeEUpF9
            5wIDAQABoAAwDQYJKoZIhvcNAQELBQADggEBAD7UPC3/Nkgpn53mT9puUonYdJg9
            SD8vvTK/N78CzoEgPNyq+bYbqlcvVPKIdItf9TMiqfOSvW3e3NvkRisYle8Qp+0C
            8pafXBvQ9eHt5CFeJn4sH9GnxeflOZT/P9Jnp71KtZQvOobirX4GgEWs79g+/NHb
            Zyf8rbadt9HruNhKA5nlP8cn7Rdc/iuJU8MVSQszI1s1DEcXMPxr6iqb2g87/ifH
            lWcK59kvRJkCcPhPzjpUy9NulucH4WFA/WqKeDNFS/oC+upV5w8EDEcfnenJFG+N
            JmFDQESSfUxLPHLC660Wnf3GmrP/duZHpPC+qTe8b1AlQ7zDT3cOaAQ+Mb0=
            -----END CERTIFICATE-----
      description: Install certificate request. `chain` can be an empty string.
    SSLCertificateInstallResponse:
      type: string
      example: OK
      description: Install certificate response.
    SSLCertificatesProvisionResponse:
      type: object
      required:
        - requests
      properties:
        requests:
          type: array
          items:
            type: object
            required:
              - log
              - result
              - domains
            properties:
              log:
                type: array
                items:
                  type: string
                example:
                  - 'The domain name does not resolve to this machine: [Not Set] (A), [Not Set] (AAAA).'
              result:
                type: string
                enum:
                  - installed
                  - error
                  - skipped
                example: installed
              domains:
                type: array
                items:
                  $ref: '#/components/schemas/Hostname'
      description: SSL certificates provision response.
    SystemPrivacyStatusResponse:
      type: boolean
      description: |
        System privacy status response.

          - `true`: Private, new-version checks will not be performed
          - `false`: Not private, new-version checks will be performed
      example: false
    SystemVersionResponse:
      type: string
      description: System version response.
      example: v0.46
    SystemVersionUpstreamResponse:
      type: string
      description: System version upstream response.
      example: v0.47
    SystemUpdatesResponse:
      type: string
      description: System updates response.
      example: |
        libgnutls30 (3.5.18-1ubuntu1.4)
        libxau6 (1:1.0.8-1ubuntu1)
    SystemUpdatePackagesResponse:
      type: string
      example: |
        Reading package lists...
        Building dependency tree...
        Reading state information...
        Calculating upgrade...
        The following packages will be upgraded:
          cloud-init grub-common grub-pc grub-pc-bin grub2-common libgnutls30
          libldap-2.4-2 libldap-common libxau6 linux-firmware python3-distupgrade
          qemu-guest-agent sosreport ubuntu-release-upgrader-core
        14 upgraded, 0 newly installed, 0 to remove and 0 not upgraded.
        Need to get 79.9 MB of archives.
        After this operation, 3893 kB of additional disk space will be used.
        Get:1 http://archive.ubuntu.com/ubuntu bionic-updates/main amd64 libgnutls30 amd64 3.5.18-1ubuntu1.4 [645 kB]
        Preconfiguring packages ...
        Fetched 79.9 MB in 2s (52.4 MB/s)
        (Reading database ... 48457 files and directories currently installed.)
      description: System update packages response.
    SystemPrivacyUpdateResponse:
      type: string
      example: OK
      description: System privacy update response.
    SystemRebootStatusResponse:
      type: boolean
      description: |
        System reboot status response.

          - `true`: A reboot is required
          - `false`: A reboot is not required
      example: true
    SystemRebootResponse:
      type: string
      example: No reboot is required, so it is not allowed.
      description: System reboot response.
    SystemStatusResponse:
      type: array
      items:
        $ref: '#/components/schemas/StatusEntry'
      description: System status response.
    StatusEntry:
      type: object
      required:
        - type
        - text
        - extra
      properties:
        type:
          $ref: '#/components/schemas/StatusEntryType'
        text:
          type: string
          example: This domain"s DNSSEC DS record is not set
        extra:
          type: array
          items:
            $ref: '#/components/schemas/StatusEntryExtra'
      description: System status entry.
    StatusEntryType:
      type: string
      enum:
        - heading
        - ok
        - warning
        - error
      example: warning
      description: System status entry type.
    StatusEntryExtra:
      type: object
      required:
        - monospace
        - text
      properties:
        monospace:
          type: boolean
          example: false
        text:
          type: string
          example: 'Digest Type: 2 / SHA-256'
      description: System entry extra information.
    SystemBackupConfigUpdateRequest:
      type: object
      required:
        - target
        - target_user
        - target_pass
        - min_age
      properties:
        target:
          type: string
          format: hostname
          example: s3://s3.eu-central-1.amazonaws.com/box-example-com
        target_user:
          type: string
          example: username
        target_pass:
          type: string
          example: password
          format: password
        min_age:
          type: integer
          format: int32
          minimum: 1
          example: 3
      description: Backup config update request.
    PerformBackupRequest:
      type: object
      required:
        - full
      properties:
        full:
          type: boolean
          example: false
      description: New backup type.
    PerformBackupResponse:
      type: string
      example: OK
      description: Backup creation response.
    SystemBackupConfigUpdateResponse:
      type: string
      example: OK
      description: Backup config update response.
    SystemBackupConfigResponse:
      type: object
      required:
        - enc_pw_file
        - file_target_directory
        - min_age_in_days
        - ssh_pub_key
        - target
      properties:
        enc_pw_file:
          type: string
          example: /home/user-data/backup/secret_key.txt
        file_target_directory:
          type: string
          example: /home/user-data/backup/encrypted
        min_age_in_days:
          type: integer
          format: int32
          minimum: 1
          example: 3
        ssh_pub_key:
          type: string
          example: ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQDb root@box.example.com\n
        target:
          type: string
          format: hostname
          example: s3://s3.eu-central-1.amazonaws.com/box-example-com
        target_user:
          type: string
        target_pass:
          type: string
      description: Backup config response.
    SystemBackupStatusResponse:
      type: object
      required:
        - unmatched_file_size
      properties:
        backups:
          type: array
          items:
            $ref: '#/components/schemas/SystemBackupStatus'
        unmatched_file_size:
          type: integer
          format: int32
          example: 0
        error:
          type: string
          example: Something is wrong with the backup
      description: Backup status response. Lists the status for all backups.
    SystemBackupStatus:
      type: object
      required:
        - date
        - date_delta
        - date_str
        - full
        - size
        - volumes
      properties:
        date:
          type: string
          format: date-time
          example: 20200801T023706Z
        date_delta:
          type: string
          example: 15 hours, 40 minutes
        date_str:
          type: string
          example: 2020-08-01 03:37:06 BST
        deleted_in:
          type: string
          example: approx. 6 days
        full:
          type: boolean
          example: false
        size:
          type: integer
          format: int32
          example: 125332
        volumes:
          type: integer
          format: int32
          example: 1
      description: Backup status details.
    SSLStatusResponse:
      type: object
      required:
        - can_provision
        - status
      properties:
        can_provision:
          type: array
          items:
            type: string
        status:
          type: array
          items:
            $ref: '#/components/schemas/SSLStatus'
      description: SSL status response for all relevant domains.
    SSLStatus:
      type: object
      required:
        - domain
        - status
        - text
      properties:
        domain:
          $ref: '#/components/schemas/Hostname'
        status:
          $ref: '#/components/schemas/SSLStatusType'
        text:
          type: string
          example: Signed & valid. The certificate expires in 87 days on 10/28/20.
      description: SSL status details for domain.
    SSLStatusType:
      type: string
      enum:
        - success
        - danger
        - not-applicable
      example: success
      description: SSL status type.
    Email:
      type: string
      format: email
      example: user@example.com
      description: Email format.
    Hostname:
      type: string
      format: hostname
      example: example.com
      description: Hostname format.
    MeResponse:
      type: object
      required:
        - status
      properties:
        api_key:
          type: string
          example: 12345abcde
        email:
          $ref: '#/components/schemas/Email'
        privileges:
          type: array
          items:
            $ref: '#/components/schemas/MailUserPrivilege'
        reason:
          type: string
          example: Incorrect username or password
        status:
          $ref: '#/components/schemas/MeAuthStatus'
      description: Me (user) response.
    MeAuthStatus:
      type: string
      enum:
        - ok
        - invalid
      example: invalid
      description: Me (user) authentication result.
    WebDomain:
      type: object
      required:
        - custom_root
        - domain
        - root
        - ssl_certificate
        - static_enabled
      properties:
        custom_root:
          type: string
          example: /home/user-data/www/example.com
        domain:
          $ref: '#/components/schemas/Hostname'
        root:
          type: string
          example: /home/user-data/www/default
        ssl_certificate:
          type: array
          minItems: 2
          maxItems: 2
          uniqueItems: true
          items:
            oneOf:
              - type: string
                example: No certificate installed.
              - type: string
                enum:
                  - danger
                  - success
                example: danger
        static_enabled:
          type: boolean
          example: true
      description: Web domain details.
    WebUpdateResponse:
      type: string
      example: web updated
      description: Web update response.
    SmtpRelayConfig:
      type: object
      required:
        - enabled
        - host
        - auth_enabled
        - user
      properties:
        enabled:
          type: boolean
          example: true
        host:
          type: string
          example: sendgrid.net
        auth_enabled:
          type: boolean
          example: true
        user:
          type: string
          example: someuser
      description: SMTP configuration details.
    SetSmtpRelayConfigRequest:
      type: object
      required:
        - enabled
        - host
        - auth_enabled
        - user
        - key
      properties:
        enabled:
          type: boolean
          example: true
        host:
          type: string
          example: sendgrid.net
        auth_enabled:
          type: boolean
          example: true
        user:
          type: string
          example: apikey
        key:
          type: string
          example: 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
      description: SMTP Configuration form
    PgpKey:
      type: object
      required:
        - ids
        - master_fpr
        - revoked
        - subkeys
      properties:
        ids:
          type: array
          items:
            type: string
        ids_emails:
          type: array
          items:
            $ref: '#/components/schemas/Email'
        master_fpr:
          type: string
        revoked:
          type: boolean
        subkeys:
          type: array
          items:
            type: object
            required:
              - algorithm
              - auth
              - cert
              - encr
              - sign
              - bits
              - expired
              - expires
              - expires_date
              - expires_days
              - fpr
              - master
            properties:
              algorithm:
                type: string
              auth:
                type: boolean
              cert:
                type: boolean
              encr:
                type: boolean
              sign:
                type: boolean
              bits:
                type: integer
                format: int32
              expired:
                type: boolean
              expires:
                type: integer
                format: int32
              expires_days:
                type: string
                format: date-time
                example: "01/15/2099"
              fpr:
                type: string
              master:
                type: boolean
      description: Parseable, human-friendly information about a PGP key
    PgpKeyring:
      type: object
      required:
        - daemon
        - imported
      properties:
        daemon:
          $ref: '#/components/schemas/PgpKey'
        imported:
          type: array
          items:
            $ref: '#/components/schemas/PgpKey'
      description: Describes all PGP keys in the keyring
    PgpKeyExport:
      type: string
      example: |
        -----BEGIN PGP PUBLIC KEY BLOCK-----

        mQINBF957dABEADz7P2flznzRq5wuUhxDS+wytdn8yQhMXZr7kvcpwbRl9f7+dx3
        mH8kH7owN9u8yBDsA9iW7fFNJnbSJNtPIFdOB08AeeIUGx6jsvWFd08+WdDulu1l
        wyR/UPvmYDYPwI5fqMy/Edne0qqgg6mzVk30cr8xDxaE1RNf3rVAWVdfbAUNF35M
        NhzjsrHZPKqpgvTLbsrV+87mc83FUwSgHQITY/E/04kJE2IbnNj3+5zYMlkhwEd/
        1afI9OFNTtIk5zYdoLPa8o/sNZZTjCgSp7pLI/2/o1CzI/NL2CEKjJgo5uwg9gHu
        e6vcUxez8uWAMOBwF3ogptr5mioT0ewbBto5Lbkv5jn8WbcpifbrDXqws1PZO+ZJ
        jUdhnrEWxE7DV1tM3CMYq5IzgbrhBPRUYhPX196HMRTRa2PwM1a8tPeilzM7NyrM
        MTYV3TO11kTKJcRr8/iSt/XpAQsV9EqI1ecUcDFX+U5LVEImHD3+BmQCT713LBRK
        HWWmY/oHumxxVjS0OQZyik8tIOOK5sy8JZr2A+p6qiLGs0SU6yUCPUonSjuc98ky
        rByV2GcVaxzT4qk1RiReDXkjIlGIXE4SzVUPHyYYoRvJVrRkQDN6fegvyQqszEAH
        7OTXgNZ55BB+WWKCzhAoO2IJiwJXWLp3xqHni86gXSGrXi5RbmprGNHkwQARAQAB
        tERQb3dlciBNYWlsLWluLWEtQm94IE1hbmFnZW1lbnQgRGFlbW9uIDxhZG1pbmlz
        dHJhdG9yQG1haWxpbmFib3gubGFuPokCVAQTAQoAPhYhBGIDe4i3Q2Jpl+Y+/iRp
        OU+8DPjaBQJfee3QAhsvBQkA7U4ABQsJCAcCBhUKCQgLAgQWAgMBAh4BAheAAAoJ
        ECRpOU+8DPjaagYP/0nJyYG3ELcmqleJxSe6CuDrhNHTNyrJROqCTkeJmsWDxePK
        tRjuSZSkK7ZCjxthTwo4Yi5ylSh7a8Qt7OzvwaFcK78JvYYAz08tErDa7+t+Gj3T
        32M00Wa/DykzBJqDlmTtAYVlmfPOegF30XOYQ8e7IGMOETZQClJE37g00Gz32QKi
        zf8ONje924xRU3PETySQjHtc5Zoio0Av8mARB2hiGQScNoQU3qzELX85x4qjKUJe
        mdIuSlf8NRwZ2Df2kBYBLzuX2lAKiIxY63V0j/a87OLViHdOQwb5SaV5s/3R/qf7
        NSaVRsbxYuRO638K402tVffvl1jH9hvooRfsc7lj5XkxKAkMIDTJmBAVcXy4+n77
        J20ZEz22ko87AwmHU6ZFh+RJiueOsqx09nnGOwmp7IXB47EDips1uVwPQ7GbkM1K
        69CiS2K90X4WCaJhgLd7Saj8hCvfEUaHvUk/XoOGPjxj9iPzxFZgEb/2osSjqkJ5
        9vQt31NbWpFJThHPXjixwIiWcn4m5yqcXjSNaHISvAZPtK55FXLp7uAOgiCygonK
        onuboXh6AK6cT0cdtOgWsz3AQ2mTkhKbK6hW7eIVwEs8SFPb5qNSxWxlssF5/QQi
        vo4j/rEYuOuqVo+TwsO0XNCfsA8as/UPLA9CgIxXXoIFmy2rL298lPQg5HgJ
        =via/
        -----END PGP PUBLIC KEY BLOCK-----
      description: ASCII-Armored export of one or more public PGP key(s).
    PgpKeyImportResult:
      type: object
      required:
        - keys_read
        - keys_added
        - keys_unchanged
        - uids_added
        - sigs_added
        - revs_added
      properties:
        keys_read:
          type: integer
          format: int32
          description: Keys in the import
        keys_added:
          type: integer
          format: int32
          description: New keys
        keys_unchanged:
          type: integer
          format: int32
          description: Keys that were not modified
        uids_added:
          type: integer
          format: int32
          description: New user ID's
        sigs_added:
          type: integer
          format: int32
          description: New key signatures
        revs_added:
          type: integer
          format: int32
          description: New revocation certificates
      description: The result of the key import operation
    MfaStatusResponse:
      type: object
      properties:
        enabled_mfa:
          type: object
          properties:
            id:
              type: string
            type:
              type: string
            label:
              type: string
          nullable: true
        new_mfa:
          type: object
          properties:
            type:
              type: string
            secret:
              type: string
            qr_code_base64:
              type: string
    MfaEnableRequest:
      type: object
      required:
        - secret
        - code
      properties:
        secret:
          type: string
        code:
          type: string
        label:
          type: string
    MfaEnableSuccessResponse:
      type: string
    MfaDisableRequest:
      type: object
      properties:
        mfa_id:
          type: string
          nullable: true
    MfaDisableSuccessResponse:
      type: string
    LogoutResponse:
      type: object
      properties:
        status:
          type: string