Mail-in-a-Box System API
System operations, which include system status checks, new version checks and reboot status.
System operations, which include system status checks, new version checks and reboot status.
Every API here is available over the APIs.io API and to AI agents over MCP.
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
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.curl "https://apis.io/api/v1/apis/mail-in-a-box:mail-in-a-box-system-api"
curl "https://apis.io/api/v1/apis?limit=25"
Calls without X-API-Key need no key. Calls with it need a paid plan — get a 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. By signing up you are subscribing to the APIs.io and API Evangelist newsletters — you can unsubscribe from any issue. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.
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/