find_apisBrowse and filter every API in the catalog.
get_api_artifactsOne API's artifacts, grouped by type.
get_openapiThe primary OpenAPI for this API.
find_similar_apisAPIs that look like this one.
apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.
resolveTurn a domain, URL or GitHub org into the provider it belongs to.
find_cohortsEvery scored population of providers in the catalog.

All 92 tools →

Call it yourself

curl for this page

This API

curl "https://apis.io/api/v1/apis/mail-in-a-box:mail-in-a-box-system-api"

All apis

curl "https://apis.io/api/v1/apis?limit=25"

Discovery needs no key. Ratings and market analysis are Pro.

Get an API key

Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.

GitHub Google LinkedIn

A second provider on the same verified email joins the account you already have.

OpenAPI Specification

openapi: 3.2.0
info:
  title: Mail-in-a-Box System API
  description: 'Mail-in-a-Box API HTTP specification.


    # Introduction

    This API is documented in **OpenAPI format**.

    (View the full HTTP specification.)


    All endpoints are relative to `https://{host}/admin` and are secured with `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: 0.51.0
  x-logo:
    url: https://mailinabox.email/static/logo.png
    altText: Mail-in-a-Box logo
servers:
- url: https://{host}/admin
  variables:
    host:
      default: box.example.com
      description: The API hostname.
security:
- basicAuth: []
tags:
- name: System
  description: 'System operations, which include system status checks, new version checks

    and reboot status.'
paths:
  /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\" \\\n  -u \"<email>:<password>\"\n"
      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\" \\\n  -u \"<email>:<password>\"\n"
      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\" \\\n  -u \"<email>:<password>\"\n"
      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\" \\\n  -u \"<email>:<password>\"\n"
      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\" \\\n  -u \"<email>:<password>\"\n"
      responses:
        200:
          description: Successful operation
          content:
            text/html:
              schema:
                $ref: '#/components/schemas/SystemUpdatePackagesResponse'
              example: "Calculating upgrade...\nThe following packages will be upgraded:\n  cloud-init grub-common\n"
        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\" \\\n  -u \"<email>:<password>\"\n"
      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\" \\\n  -d \"value=<string>\" \\\n  -u \"<email>:<password>\"\n"
      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\" \\\n  -u \"<email>:<password>\"\n"
      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\" \\\n  -u \"<email>:<password>\"\n"
      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\" \\\n  -u \"<email>:<password>\"\n"
      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\" \\\n  -u \"<email>:<password>\"\n"
      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\" \\\n  -d \"target=<hostname>\" \\\n  -d \"target_user=<string>\" \\\n  -d \"target_pass=<password>\" \\\n  -d \"min_age=<integer>\" \\\n  -u \"<email>:<password>\"\n"
      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
components:
  schemas:
    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.
    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.
    SystemRebootResponse:
      type: string
      example: No reboot is required, so it is not allowed.
      description: System reboot response.
    SystemRebootStatusResponse:
      type: boolean
      description: "System reboot status response.\n\n  - `true`: A reboot is required\n  - `false`: A reboot is not required\n"
      example: true
    SystemVersionResponse:
      type: string
      description: System version response.
      example: v0.46
    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.
    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.
    SystemVersionUpstreamResponse:
      type: string
      description: System version upstream response.
      example: v0.47
    SystemPrivacyStatusResponse:
      type: boolean
      description: "System privacy status response.\n\n  - `true`: Private, new-version checks will not be performed\n  - `false`: Not private, new-version checks will be performed\n"
      example: false
    SystemStatusResponse:
      type: array
      items:
        $ref: '#/components/schemas/StatusEntry'
      description: System status 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.
    SystemPrivacyStatus:
      type: string
      enum:
      - private
      - 'off'
      example: private
      description: System privacy status.
    SystemUpdatesResponse:
      type: string
      description: System updates response.
      example: 'libgnutls30 (3.5.18-1ubuntu1.4)

        libxau6 (1:1.0.8-1ubuntu1)

        '
    StatusEntryType:
      type: string
      enum:
      - heading
      - ok
      - warning
      - error
      example: warning
      description: System status entry type.
    SystemPrivacyUpdateRequest:
      type: object
      required:
      - value
      properties:
        value:
          $ref: '#/components/schemas/SystemPrivacyStatus'
      description: Update system privacy request.
    SystemUpdatePackagesResponse:
      type: string
      example: "Reading package lists...\nBuilding dependency tree...\nReading state information...\nCalculating upgrade...\nThe following packages will be upgraded:\n  cloud-init grub-common grub-pc grub-pc-bin grub2-common libgnutls30\n  libldap-2.4-2 libldap-common libxau6 linux-firmware python3-distupgrade\n  qemu-guest-agent sosreport ubuntu-release-upgrader-core\n14 upgraded, 0 newly installed, 0 to remove and 0 not upgraded.\nNeed to get 79.9 MB of archives.\nAfter this operation, 3893 kB of additional disk space will be used.\nGet:1 http://archive.ubuntu.com/ubuntu bionic-updates/main amd64 libgnutls30 amd64 3.5.18-1ubuntu1.4 [645 kB]\nPreconfiguring packages ...\nFetched 79.9 MB in 2s (52.4 MB/s)\n(Reading database ... 48457 files and directories currently installed.)\n"
      description: System update packages response.
    SystemPrivacyUpdateResponse:
      type: string
      example: OK
      description: System privacy update response.
    SystemBackupConfigUpdateResponse:
      type: string
      example: OK
      description: Backup config update 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.
  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.

        '
externalDocs:
  description: Find out more about Mail-in-a-box.
  url: https://mailinabox.email/