mirror of
https://github.com/mail-in-a-box/mailinabox.git
synced 2024-11-27 03:07:04 +00:00
646f971d8b
The examples for login and logout use GET instead of POST. GET gives me an error when using it, while POST seems to work.
2733 lines
81 KiB
YAML
2733 lines
81 KiB
YAML
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: 0.51.0
|
|
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.
|
|
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
|
|
/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.
|
|
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.
|
|
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
|