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: 56.2 x-logo: url: https://mailinabox.email/static/logo.png altText: Mail-in-a-Box logo externalDocs: description: Find out more about Mail-in-a-box. url: https://mailinabox.email/ servers: - url: https://{host}/admin variables: host: default: box.example.com description: The API hostname. security: - basicAuth: [] tags: - name: User description: Endpoints related to user authentication. - name: Mail description: | Mail operations, which include getting all users, getting all aliases, adding/updating/removing users and aliases and getting all mail domains. - name: DNS description: | DNS operations, which include adding custom records, adding a secondary nameserver and viewing all DNS records. - name: SSL description: | TLS (SSL) Certificates operations, which include checking certificate status and installing custom certificates. - name: Web description: | Static web hosting operations, which include getting domain information and updating domain root directories. - name: MFA description: | Manage multi-factor authentication schemes. Currently, only TOTP is supported. - name: System description: | System operations, which include system status checks, new version checks and reboot status. - name: PGP description: | PGP Key operations, which include key management and publishing. - name: WKD description: | WKD (Web Key Directory) operations, which include publishing public PGP keys on the internet. paths: /login: post: tags: - User summary: Exchange a username and password for a session API key. description: | Returns user information and a session API key. Authenticate a user by supplying the auth token as a base64 encoded string in format `email:password` using basic authentication headers. If successful, a long-lived `api_key` is returned which can be used for subsequent requests to the API in place of the password. operationId: login x-codeSamples: - lang: curl source: | curl -X POST "https://{host}/admin/login" \ -u ":" 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 ":" 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 ":" 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 ":" 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 ":" 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 ":" 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 ":" 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 ":" 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=" \ -u ":" 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 ":" 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 ":" 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 ":" 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 ":" 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=" \ -d "target_user=" \ -d "target_pass=" \ -d "min_age=" \ -u ":" responses: 200: description: Successful operation content: text/html: schema: $ref: '#/components/schemas/SystemBackupConfigUpdateResponse' example: OK 400: description: Bad request content: text/html: schema: type: string 403: description: Forbidden content: text/html: schema: type: string /system/backup/new: post: tags: - System summary: Perform system backup description: Performs a system backup. operationId: performSystemBackup requestBody: required: true content: application/x-www-form-urlencoded: schema: $ref: '#/components/schemas/PerformBackupRequest' examples: incremental: summary: Perform incremental backup. value: full: false full: summary: Force a full backup. value: full: true x-codeSamples: - lang: curl source: | curl -X POST "https://{host}/admin/system/backup/new" \ -d "full=" \ -u ":" responses: 200: description: Successful operation content: text/html: schema: $ref: '#/components/schemas/PerformBackupResponse' 403: description: Forbidden content: text/plain: schema: type: string /system/smtp/relay: get: tags: - System summary: Get SMTP relay configuration description: Gets basic configuration on how the box should use third-party relay services to deliver mail. operationId: getRelayConfig x-codeSamples: - lang: curl source: | curl -X GET "https://{host}/admin/system/smtp/relay" \ -u ":" responses: 200: description: Successful operation content: application/json: schema: $ref: '#/components/schemas/SmtpRelayConfig' 403: description: Forbidden content: text/html: schema: type: string post: tags: - System summary: Set SMTP relay configuration description: Sets the configuration on how the box should use third-party relays to deliver mail. operationId: setRelayConfig requestBody: required: true content: application/x-www-form-urlencoded: schema: $ref: '#/components/schemas/SetSmtpRelayConfigRequest' examples: disable: summary: Do not use relays. value: enabled: false host: "" auth_enabled: false user: "" key: "" no_auth: summary: Use a relay that does not require authentication. value: enabled: true host: smtp.relay.net auth_enabled: false user: "" key: "" auth: summary: Use a relay that requires authentication. value: enabled: true host: smtp.relay.net auth_enabled: true user: someuser key: key-or-password-here responses: 200: description: Successful operation content: text/plain: schema: type: string 403: description: Forbidden content: text/html: schema: type: string /system/pgp/: get: tags: - PGP summary: Get all PGP keys description: Gets a JSON summary of all public PGP keys in the keyring. operationId: getPGPKeys x-codeSamples: - lang: curl source: | curl -X GET "https://{host}/admin/system/pgp/" \ -u ":" responses: 200: description: Successful operation content: application/json: schema: $ref: '#/components/schemas/PgpKeyring' example: daemon: ids: - Power Mail-in-a-Box Management Daemon master_fpr: 62037B88B743626997E63EFE2469394FBC0CF8DA revoked: false subkeys: - algorithm: RSA auth: true cert: true encr: true sign: true bits: 4096 expired: false expires: 1617378256 expires_date: 04/02/21 expires_days: 179 fpr: 62037B88B743626997E63EFE2469394FBC0CF8DA master: true imported: - ids: - Someone You Used To Know master_fpr: B9BD7309D18784392D812050A174D33254CC2820 revoked: false subkeys: - algorithm: RSA auth: true cert: true encr: true sign: true bits: 4096 expired: false expires: 1615290372 expires_date: 03/09/21 expires_days: 155 fpr: B9BD7309D18784392D812050A174D33254CC2820 master: true - ids: - Linus Torvalds - Linus Torvalds master_fpr: ABAF11C65A2970B130ABE3C479BE3E4300411886 revoked: false subkeys: - algorithm: RSA auth: false cert: true encr: false sign: true bits: 2048 expired: false expires: null expires_date: null expires_days: null fpr: ABAF11C65A2970B130ABE3C479BE3E4300411886 master: true - algorithm: RSA auth: false cert: false encr: true sign: false bits: 2048 expired: false expires: null expires_date: null expires_days: null fpr: AEE416F7DCCB753BB3D5609D88BCE80F012F54CA master: false 403: description: Forbidden content: text/html: schema: type: string /system/pgp/{fpr}: get: tags: - PGP summary: Get a specific PGP key description: Gets a JSON summary of the PGP key with the given fingerprint. operationId: getPGPKey x-codeSamples: - lang: curl source: | curl -X GET "https://{host}/admin/system/pgp/" \ -u ":" responses: 200: description: Successful operation content: application/json: schema: $ref: '#/components/schemas/PgpKey' example: ids: - Power Mail-in-a-Box Management Daemon master_fpr: 62037B88B743626997E63EFE2469394FBC0CF8DA revoked: false subkeys: - algorithm: RSA auth: true cert: true encr: true sign: true bits: 4096 expired: false expires: 1617378256 expires_date: 04/02/21 expires_days: 179 fpr: 62037B88B743626997E63EFE2469394FBC0CF8DA master: true 403: description: Forbidden content: text/html: schema: type: string 404: description: Key not found in public keyring content: text/html: schema: type: string delete: tags: - PGP summary: Remove a PGP key description: Removes the PGP key with the given fingerprint from the keyring operationId: removePGPKey x-codeSamples: - lang: curl source: | curl -X DELETE "https://{host}/admin/system/pgp/" \ -u ":" responses: 200: description: Operation successful content: text/plain: schema: type: string example: OK 403: description: Forbidden content: text/html: schema: type: string 404: description: Key not found in public keyring content: text/html: schema: type: string /system/pgp/{fpr}/export: get: tags: - PGP summary: Export a PGP key description: Exports the PGP key with the given fingerprint. operationId: exportPGPKey x-codeSamples: - lang: curl source: | curl -X GET "https://{host}/admin/system/pgp//export" \ -u ":" responses: 200: description: Successful operation content: text/plain: schema: $ref: '#/components/schemas/PgpKeyExport' example: | -----BEGIN PGP PUBLIC KEY BLOCK----- mQINBF957dABEADz7P2flznzRq5wuUhxDS+wytdn8yQhMXZr7kvcpwbRl9f7+dx3 ... vo4j/rEYuOuqVo+TwsO0XNCfsA8as/UPLA9CgIxXXoIFmy2rL298lPQg5HgJ =via/ -----END PGP PUBLIC KEY BLOCK----- 403: description: Forbidden content: text/html: schema: type: string 404: description: Key not found in public keyring content: text/html: schema: type: string /system/pgp/import: post: tags: - PGP summary: Import a PGP key description: Imports a PGP key block into the keyring. Only public keys are accepted. operationId: importPGPKey x-codeSamples: - lang: curl source: | curl -X POST "https://{host}/admin/system/pgp/import" \ --data-urlencode "key=$(gpg --export --armor )" \ -u ":" responses: 200: description: Successful operation content: text/plain: schema: $ref: '#/components/schemas/PgpKeyImportResult' example: keys_read: 1 keys_added: 1 keys_unchanged: 0 uids_added: 0 sigs_added: 0 revs_added: 0 400: description: Import refused content: text/plain: schema: type: string examples: private_key: value: Import cannot contain private keys! invalid_format: value: Import is not a valid PGP key block! 403: description: Forbidden content: text/html: schema: type: string /system/pgp/wkd: get: tags: - WKD summary: Get WKD status description: Gets the current configuration applied to the Web Key Directory for each email hosted in the box, along with a JSON summary of all public PGP keys in the keyring. operationId: getWKDstatus x-codeSamples: - lang: curl source: | curl -X GET "https://{host}/admin/system/pgp/wkd" \ -u ":" responses: 200: description: Successful operation content: application/json: schema: type: object required: - keys - wkd properties: keys: type: array items: $ref: '#/components/schemas/PgpKey' wkd: type: object # Because keys are dynamic (emails), there's not a lot we can do here :( example: keys: - ids: - Power Mail-in-a-Box Management Daemon master_fpr: 62037B88B743626997E63EFE2469394FBC0CF8DA revoked: false subkeys: - algorithm: RSA auth: true cert: true encr: true sign: true bits: 4096 expired: false expires: 1617378256 expires_date: 04/02/21 expires_days: 179 fpr: 62037B88B743626997E63EFE2469394FBC0CF8DA master: true - ids: - Someone You Used To Know master_fpr: B9BD7309D18784392D812050A174D33254CC2820 revoked: false subkeys: - algorithm: RSA auth: true cert: true encr: true sign: true bits: 4096 expired: false expires: 1615290372 expires_date: 03/09/21 expires_days: 155 fpr: B9BD7309D18784392D812050A174D33254CC2820 master: true - ids: - Linus Torvalds - Linus Torvalds master_fpr: ABAF11C65A2970B130ABE3C479BE3E4300411886 revoked: false subkeys: - algorithm: RSA auth: false cert: true encr: false sign: true bits: 2048 expired: false expires: null expires_date: null expires_days: null fpr: ABAF11C65A2970B130ABE3C479BE3E4300411886 master: true - algorithm: RSA auth: false cert: false encr: true sign: false bits: 2048 expired: false expires: null expires_date: null expires_days: null fpr: AEE416F7DCCB753BB3D5609D88BCE80F012F54CA master: false wkd: me@mailinabox.lan: selection: null options: [] administrator@mailinabox.lan: selection: 62037B88B743626997E63EFE2469394FBC0CF8DA options: - 62037B88B743626997E63EFE2469394FBC0CF8DA 403: description: Forbidden content: text/html: schema: type: string /ssl/status: get: tags: - SSL summary: Get SSL status description: Returns the SSL status for all domains. operationId: getSSLStatus x-codeSamples: - lang: curl source: | curl -X GET "https://{host}/admin/ssl/status" \ -u ":" 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/" \ -d "countrycode=" \ -u ":" 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=" \ -d "cert=" \ -d "chain=" \ -u ":" 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 ":" 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 ":" 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=" \ -u ":" 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 ":" 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/" \ -u ":" 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=" \ -u ":" 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 ":" 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//" \ -u ":" 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//" \ -H "Content-Type: text/plain" \ --data-raw "" \ -u ":" 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//" \ -H "Content-Type: text/plain" \ --data-raw "" \ -u ":" 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//" \ -H "Content-Type: text/plain" \ --data-raw "" \ -u ":" 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/" \ -u ":" 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/" \ -H "Content-Type: text/plain" \ --data-raw "" \ -u ":" 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/" \ -H "Content-Type: text/plain" \ --data-raw "" \ -u ":" 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/" \ -H "Content-Type: text/plain" \ --data-raw "" \ -u ":" 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 ":" 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=" \ -u ":" 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=" \ -d "password=" \ -d "privileges=" \ -u ":" 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=" \ -u ":" 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=" \ -d "privilege=" \ -u ":" 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=" \ -d "privilege=" \ -u ":" 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=" \ -d "password=" \ -u ":" \ 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=" \ -u ":" 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 ":" 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=" \ -u ":" 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=" \ -d "address=" \ -d "forwards_to=" \ -d "permitted_senders=" \ -u ":" 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=" \ -u ":" 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 ":" 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 ":" 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 ":" 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=" \ -u ":" 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 ":" responses: 200: description: Successful operation content: text/html: schema: $ref: '#/components/schemas/MfaDisableSuccessResponse' 403: description: Forbidden content: text/html: schema: type: string components: securitySchemes: basicAuth: type: http scheme: basic description: | Credentials can be supplied using the `Authorization` header in format `Authorization: Basic {access-token}`. The `access-token` is comprised of the Base64 encoding of `username:password`. The `username` is the mail user's email address, and `password` can either be the mail user's password, or the `api_key` returned from the `login` operation. When using `curl`, you can supply user credentials using the `-u` or `--user` parameter. requestBodies: DNSCustomRecordRequest: required: true content: text/plain: schema: type: string example: '1.2.3.4' description: The value of the DNS record. example: '1.2.3.4' schemas: MailUsersResponseFormat: type: string enum: - text - json example: json description: Response format (`application/json` or `text/html`). MailAliasesResponseFormat: type: string enum: - text - json example: json description: Response format (`application/json` or `text/html`). MailUserSetPasswordResponse: type: string example: OK description: Mail user set password response. MailUserRemoveResponse: type: string example: OK description: Mail user remove response. MailUserAddResponse: type: string example: | mail user added updated DNS: OpenDKIM configuration description: | Mail user add response. Can include information about operations related to adding new users, like updating DNS. MailUserAddPrivilegeResponse: type: string example: OK description: Mail user add admin privilege response. MailUserRemovePrivilegeResponse: type: string example: OK description: Mail user remove admin privilege response. MailUsersSimpleResponse: type: string example: | user1@example.com user2@example.com description: Get mail users text format response. MailUserPrivilegesResponse: $ref: '#/components/schemas/MailUserPrivilege' description: Mail user privileges response. example: admin MailDomainsResponse: type: string example: | example1.com example2.com description: Mail domains response. MailUsersResponse: type: array items: $ref: '#/components/schemas/MailUserByDomain' description: Get mail aliases JSON format response. MailUserByDomain: type: object required: - domain - users properties: domain: $ref: '#/components/schemas/Hostname' users: type: array items: $ref: '#/components/schemas/MailUser' description: Mail users by domain. MailUser: type: object required: - email - privileges - status properties: email: $ref: '#/components/schemas/Email' privileges: type: array items: $ref: '#/components/schemas/MailUserPrivilege' status: $ref: '#/components/schemas/MailUserStatus' mailbox: type: string example: /home/user-data/mail/mailboxes/example.com/user description: Mail user details. MailAliasesSimpleResponse: type: string example: | abuse@example.com administrator@example.com admin@example.com administrator@example.com description: Get mail aliases text format response. MailAliasByDomain: type: object required: - domain - aliases properties: domain: $ref: '#/components/schemas/Hostname' aliases: type: array items: $ref: '#/components/schemas/MailAlias' description: Mail aliases by domain. MailAlias: type: object required: - address - address_display - forwards_to - permitted_senders - required properties: address: $ref: '#/components/schemas/Email' address_display: $ref: '#/components/schemas/Email' forwards_to: type: array items: $ref: '#/components/schemas/Email' permitted_senders: type: array nullable: true items: $ref: '#/components/schemas/Email' required: type: boolean example: true description: Mail alias details. MailAliasUpsertResponse: type: string example: alias updated description: Mail alias add/update response. MailAliasUpsertRequest: type: object required: - update_if_exists - address - forwards_to - permitted_senders properties: update_if_exists: type: integer format: int32 minimum: 0 maximum: 1 example: 1 description: Set to `1` when updating an alias. address: $ref: '#/components/schemas/Email' forwards_to: type: string example: user1@example.com, user2@example.com description: | If adding a regular or catch-all alias, the format needs to be `user@example.com`. Multiple address can be separated by newlines or commas. If adding a domain alias, the format needs to be `@example.com`. permitted_senders: type: string nullable: true example: user1@example.com, user2@example.com description: | Mail users that can send mail claiming to be from any address on the alias domain. Multiple address can be separated by newlines or commas. Leave empty to allow any mail user listed in `forwards_to` to send mail claiming to be from any address on the alias domain. description: Mail alias upsert request. MailAliasRemoveResponse: type: string example: alias removed description: Mail alias remove response. MailAliasRemoveRequest: type: object required: - address properties: address: $ref: '#/components/schemas/Email' description: Mail aliases remove request. DNSRecordType: enum: - A - AAAA - CAA - CNAME - TXT - MX - SRV - SSHFP - NS example: MX description: DNS record type. DNSDumpResponse: type: array items: $ref: '#/components/schemas/DNSDumpDomains' description: DNS dump response. DNSDumpDomains: type: array items: oneOf: - $ref: '#/components/schemas/Hostname' - $ref: '#/components/schemas/DNSDumpDomainRecords' description: | A list of records per domain. The first item in the list is the domain and the second item is the list of records. DNSDumpDomainRecords: type: array items: $ref: '#/components/schemas/DNSDumpDomainRecord' description: List of domain records. DNSDumpDomainRecord: type: object required: - explanation - qname - type - value properties: explanation: type: string example: Required. Specifies the hostname (and priority) of the machine that handles @example.com mail qname: $ref: '#/components/schemas/Hostname' rtype: $ref: '#/components/schemas/DNSRecordType' value: type: string example: 10 example.com. description: Domain DNS record details. DNSCustomRecord: type: object required: - qname - rtype - value properties: qname: $ref: '#/components/schemas/Hostname' rtype: $ref: '#/components/schemas/DNSRecordType' value: type: string example: 10 example.com. description: Custom DNS record detail detail. DNSCustomRecordsResponse: type: array items: $ref: '#/components/schemas/DNSCustomRecord' description: Custom DNS records response. DNSZonesResponse: type: array items: $ref: '#/components/schemas/Hostname' description: DNS zones response. DNSZonefileResponse: type: string DNSSecondaryNameserverResponse: type: object required: - hostnames properties: hostnames: type: array items: type: string example: ns1.example.com description: Secondary nameserver/s response. DNSCustomRecordRemoveResponse: type: string example: 'updated DNS: example.com' description: Custom DNS record remove response. DNSCustomRecordUpsertResponse: type: string example: 'updated DNS: example.com' description: Custom DNS record add response. DNSUpdateRequest: type: object required: - force properties: force: type: integer format: int32 minimum: 0 maximum: 1 example: 1 description: Force an update even if mailinabox detects no changes are required. description: DNS update request. DNSUpdateResponse: type: string example: | updated DNS: example1.com,example2.com description: DNS update response. DNSSecondaryNameserverAddRequest: type: object required: - hostnames properties: hostnames: type: string description: Hostnames separated with commas or spaces. example: ns2.hostingcompany.com, ns3.hostingcompany.com description: Secondary nameserver/s add request. DNSSecondaryNameserverAddResponse: type: string example: 'updated DNS: example.com' description: Secondary nameserver/s add response. SystemPrivacyUpdateRequest: type: object required: - value properties: value: $ref: '#/components/schemas/SystemPrivacyStatus' description: Update system privacy request. SystemPrivacyStatus: type: string enum: - private - 'off' example: private description: System privacy status. MailUserSetPasswordRequest: type: object required: - email - password properties: email: $ref: '#/components/schemas/Email' password: type: string format: password description: Mail user set password request. MailUserAddRequest: type: object required: - email - password - privileges properties: email: $ref: '#/components/schemas/Email' password: type: string format: password privileges: $ref: '#/components/schemas/MailUserPrivilege' description: Mail user add request. MailUserRemoveRequest: type: object required: - email properties: email: $ref: '#/components/schemas/Email' description: Mail user remove request. MailUserStatus: type: string enum: - active - inactive example: active description: Mail user status. MailUserPrivilege: type: string enum: - admin - '' example: admin description: Mail user privilege. MailUserAddPrivilegeRequest: type: object required: - email - privilege properties: email: $ref: '#/components/schemas/Email' privilege: $ref: '#/components/schemas/MailUserPrivilege' description: Mail user add privilege request. MailUserRemovePrivilegeRequest: type: object required: - email - privilege properties: email: $ref: '#/components/schemas/Email' privilege: $ref: '#/components/schemas/MailUserPrivilege' description: Mail user remove privilege request. SSLCSRGenerateRequest: type: object required: - countrycode properties: countrycode: type: string example: GB description: Generate SSL CSR request. SSLCSRGenerateResponse: type: string example: | -----BEGIN CERTIFICATE REQUEST----- MIICaDCCAVACAQAwIzELMAkGA1UEBhMCQlMxFDASBgNVBAMMC2V4YW1wbGUuY29t MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA3K6dwLM2Nk8kVhIBaZmp eY6y7O0T3jrexEKlW839TVYdcH+K35V1NxilbMFKMuHeowGwFyyiqOy/OUYNeq+T Rz3s4b1qG2p01dwlsXHHYmXLYTAhvqvY+CU5ksieuZbyHRTwbHViQ0xtRXwoVCnj CkN7kJVpkLfVN0/BG6NBFpv/JI8F+hwp+IHdkC1gUXRrLJNC79ERqFP8HoqdQWNw OGGFaOe2aQhvj2zt8wFncyKVc40UKVbSzGGzdL2MPiAJHgZ2lmeY1xDyX1lOt12R IFPwtxmbxaxYaVfe2hxl7m88xV3OjYcKgwVYDusk2XJ37cGew5g+NbBvzEeEUpF9 5wIDAQABoAAwDQYJKoZIhvcNAQELBQADggEBAD7UPC3/Nkgpn53mT9puUonYdJg9 SD8vvTK/N78CzoEgPNyq+bYbqlcvVPKIdItf9TMiqfOSvW3e3NvkRisYle8Qp+0C 8pafXBvQ9eHt5CFeJn4sH9GnxeflOZT/P9Jnp71KtZQvOobirX4GgEWs79g+/NHb Zyf8rbadt9HruNhKA5nlP8cn7Rdc/iuJU8MVSQszI1s1DEcXMPxr6iqb2g87/ifH lWcK59kvRJkCcPhPzjpUy9NulucH4WFA/WqKeDNFS/oC+upV5w8EDEcfnenJFG+N JmFDQESSfUxLPHLC660Wnf3GmrP/duZHpPC+qTe8b1AlQ7zDT3cOaAQ+Mb0= -----END CERTIFICATE REQUEST----- description: Generate SSL CSR response. SSLCertificateInstallRequest: type: object required: - domain - cert - chain properties: domain: $ref: '#/components/schemas/Hostname' cert: type: string description: TLS/SSL certificate. example: | -----BEGIN CERTIFICATE----- MIICaDCCAVACAQAwIzELMAkGA1UEBhMCQlMxFDASBgNVBAMMC2V4YW1wbGUuY29t MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA3K6dwLM2Nk8kVhIBaZmp eY6y7O0T3jrexEKlW839TVYdcH+K35V1NxilbMFKMuHeowGwFyyiqOy/OUYNeq+T Rz3s4b1qG2p01dwlsXHHYmXLYTAhvqvY+CU5ksieuZbyHRTwbHViQ0xtRXwoVCnj CkN7kJVpkLfVN0/BG6NBFpv/JI8F+hwp+IHdkC1gUXRrLJNC79ERqFP8HoqdQWNw OGGFaOe2aQhvj2zt8wFncyKVc40UKVbSzGGzdL2MPiAJHgZ2lmeY1xDyX1lOt12R IFPwtxmbxaxYaVfe2hxl7m88xV3OjYcKgwVYDusk2XJ37cGew5g+NbBvzEeEUpF9 5wIDAQABoAAwDQYJKoZIhvcNAQELBQADggEBAD7UPC3/Nkgpn53mT9puUonYdJg9 SD8vvTK/N78CzoEgPNyq+bYbqlcvVPKIdItf9TMiqfOSvW3e3NvkRisYle8Qp+0C 8pafXBvQ9eHt5CFeJn4sH9GnxeflOZT/P9Jnp71KtZQvOobirX4GgEWs79g+/NHb Zyf8rbadt9HruNhKA5nlP8cn7Rdc/iuJU8MVSQszI1s1DEcXMPxr6iqb2g87/ifH lWcK59kvRJkCcPhPzjpUy9NulucH4WFA/WqKeDNFS/oC+upV5w8EDEcfnenJFG+N JmFDQESSfUxLPHLC660Wnf3GmrP/duZHpPC+qTe8b1AlQ7zDT3cOaAQ+Mb0= -----END CERTIFICATE----- chain: type: string description: TLS/SSL intermediate chain (if provided, else empty string). example: | -----BEGIN CERTIFICATE----- MIICaDCCAVACAQAwIzELMAkGA1UEBhMCQlMxFDASBgNVBAMMC2V4YW1wbGUuY29t MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA3K6dwLM2Nk8kVhIBaZmp eY6y7O0T3jrexEKlW839TVYdcH+K35V1NxilbMFKMuHeowGwFyyiqOy/OUYNeq+T Rz3s4b1qG2p01dwlsXHHYmXLYTAhvqvY+CU5ksieuZbyHRTwbHViQ0xtRXwoVCnj CkN7kJVpkLfVN0/BG6NBFpv/JI8F+hwp+IHdkC1gUXRrLJNC79ERqFP8HoqdQWNw OGGFaOe2aQhvj2zt8wFncyKVc40UKVbSzGGzdL2MPiAJHgZ2lmeY1xDyX1lOt12R IFPwtxmbxaxYaVfe2hxl7m88xV3OjYcKgwVYDusk2XJ37cGew5g+NbBvzEeEUpF9 5wIDAQABoAAwDQYJKoZIhvcNAQELBQADggEBAD7UPC3/Nkgpn53mT9puUonYdJg9 SD8vvTK/N78CzoEgPNyq+bYbqlcvVPKIdItf9TMiqfOSvW3e3NvkRisYle8Qp+0C 8pafXBvQ9eHt5CFeJn4sH9GnxeflOZT/P9Jnp71KtZQvOobirX4GgEWs79g+/NHb Zyf8rbadt9HruNhKA5nlP8cn7Rdc/iuJU8MVSQszI1s1DEcXMPxr6iqb2g87/ifH lWcK59kvRJkCcPhPzjpUy9NulucH4WFA/WqKeDNFS/oC+upV5w8EDEcfnenJFG+N JmFDQESSfUxLPHLC660Wnf3GmrP/duZHpPC+qTe8b1AlQ7zDT3cOaAQ+Mb0= -----END CERTIFICATE----- description: Install certificate request. `chain` can be an empty string. SSLCertificateInstallResponse: type: string example: OK description: Install certificate response. SSLCertificatesProvisionResponse: type: object required: - requests properties: requests: type: array items: type: object required: - log - result - domains properties: log: type: array items: type: string example: - 'The domain name does not resolve to this machine: [Not Set] (A), [Not Set] (AAAA).' result: type: string enum: - installed - error - skipped example: installed domains: type: array items: $ref: '#/components/schemas/Hostname' description: SSL certificates provision response. SystemPrivacyStatusResponse: type: boolean description: | System privacy status response. - `true`: Private, new-version checks will not be performed - `false`: Not private, new-version checks will be performed example: false SystemVersionResponse: type: string description: System version response. example: v0.46 SystemVersionUpstreamResponse: type: string description: System version upstream response. example: v0.47 SystemUpdatesResponse: type: string description: System updates response. example: | libgnutls30 (3.5.18-1ubuntu1.4) libxau6 (1:1.0.8-1ubuntu1) SystemUpdatePackagesResponse: type: string example: | Reading package lists... Building dependency tree... Reading state information... Calculating upgrade... The following packages will be upgraded: cloud-init grub-common grub-pc grub-pc-bin grub2-common libgnutls30 libldap-2.4-2 libldap-common libxau6 linux-firmware python3-distupgrade qemu-guest-agent sosreport ubuntu-release-upgrader-core 14 upgraded, 0 newly installed, 0 to remove and 0 not upgraded. Need to get 79.9 MB of archives. After this operation, 3893 kB of additional disk space will be used. Get:1 http://archive.ubuntu.com/ubuntu bionic-updates/main amd64 libgnutls30 amd64 3.5.18-1ubuntu1.4 [645 kB] Preconfiguring packages ... Fetched 79.9 MB in 2s (52.4 MB/s) (Reading database ... 48457 files and directories currently installed.) description: System update packages response. SystemPrivacyUpdateResponse: type: string example: OK description: System privacy update response. SystemRebootStatusResponse: type: boolean description: | System reboot status response. - `true`: A reboot is required - `false`: A reboot is not required example: true SystemRebootResponse: type: string example: No reboot is required, so it is not allowed. description: System reboot response. SystemStatusResponse: type: array items: $ref: '#/components/schemas/StatusEntry' description: System status response. StatusEntry: type: object required: - type - text - extra properties: type: $ref: '#/components/schemas/StatusEntryType' text: type: string example: This domain"s DNSSEC DS record is not set extra: type: array items: $ref: '#/components/schemas/StatusEntryExtra' description: System status entry. StatusEntryType: type: string enum: - heading - ok - warning - error example: warning description: System status entry type. StatusEntryExtra: type: object required: - monospace - text properties: monospace: type: boolean example: false text: type: string example: 'Digest Type: 2 / SHA-256' description: System entry extra information. SystemBackupConfigUpdateRequest: type: object required: - target - target_user - target_pass - min_age properties: target: type: string format: hostname example: s3://s3.eu-central-1.amazonaws.com/box-example-com target_user: type: string example: username target_pass: type: string example: password format: password min_age: type: integer format: int32 minimum: 1 example: 3 description: Backup config update request. PerformBackupRequest: type: object required: - full properties: full: type: boolean example: false description: New backup type. PerformBackupResponse: type: string example: OK description: Backup creation response. SystemBackupConfigUpdateResponse: type: string example: OK description: Backup config update response. SystemBackupConfigResponse: type: object required: - enc_pw_file - file_target_directory - min_age_in_days - ssh_pub_key - target properties: enc_pw_file: type: string example: /home/user-data/backup/secret_key.txt file_target_directory: type: string example: /home/user-data/backup/encrypted min_age_in_days: type: integer format: int32 minimum: 1 example: 3 ssh_pub_key: type: string example: ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQDb root@box.example.com\n target: type: string format: hostname example: s3://s3.eu-central-1.amazonaws.com/box-example-com target_user: type: string target_pass: type: string description: Backup config response. SystemBackupStatusResponse: type: object required: - unmatched_file_size properties: backups: type: array items: $ref: '#/components/schemas/SystemBackupStatus' unmatched_file_size: type: integer format: int32 example: 0 error: type: string example: Something is wrong with the backup description: Backup status response. Lists the status for all backups. SystemBackupStatus: type: object required: - date - date_delta - date_str - full - size - volumes properties: date: type: string format: date-time example: 20200801T023706Z date_delta: type: string example: 15 hours, 40 minutes date_str: type: string example: 2020-08-01 03:37:06 BST deleted_in: type: string example: approx. 6 days full: type: boolean example: false size: type: integer format: int32 example: 125332 volumes: type: integer format: int32 example: 1 description: Backup status details. SSLStatusResponse: type: object required: - can_provision - status properties: can_provision: type: array items: type: string status: type: array items: $ref: '#/components/schemas/SSLStatus' description: SSL status response for all relevant domains. SSLStatus: type: object required: - domain - status - text properties: domain: $ref: '#/components/schemas/Hostname' status: $ref: '#/components/schemas/SSLStatusType' text: type: string example: Signed & valid. The certificate expires in 87 days on 10/28/20. description: SSL status details for domain. SSLStatusType: type: string enum: - success - danger - not-applicable example: success description: SSL status type. Email: type: string format: email example: user@example.com description: Email format. Hostname: type: string format: hostname example: example.com description: Hostname format. MeResponse: type: object required: - status properties: api_key: type: string example: 12345abcde email: $ref: '#/components/schemas/Email' privileges: type: array items: $ref: '#/components/schemas/MailUserPrivilege' reason: type: string example: Incorrect username or password status: $ref: '#/components/schemas/MeAuthStatus' description: Me (user) response. MeAuthStatus: type: string enum: - ok - invalid example: invalid description: Me (user) authentication result. WebDomain: type: object required: - custom_root - domain - root - ssl_certificate - static_enabled properties: custom_root: type: string example: /home/user-data/www/example.com domain: $ref: '#/components/schemas/Hostname' root: type: string example: /home/user-data/www/default ssl_certificate: type: array minItems: 2 maxItems: 2 uniqueItems: true items: oneOf: - type: string example: No certificate installed. - type: string enum: - danger - success example: danger static_enabled: type: boolean example: true description: Web domain details. WebUpdateResponse: type: string example: web updated description: Web update response. SmtpRelayConfig: type: object required: - enabled - host - auth_enabled - user properties: enabled: type: boolean example: true host: type: string example: sendgrid.net auth_enabled: type: boolean example: true user: type: string example: someuser description: SMTP configuration details. SetSmtpRelayConfigRequest: type: object required: - enabled - host - auth_enabled - user - key properties: enabled: type: boolean example: true host: type: string example: sendgrid.net auth_enabled: type: boolean example: true user: type: string example: apikey key: type: string example: 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 description: SMTP Configuration form PgpKey: type: object required: - ids - master_fpr - revoked - subkeys properties: ids: type: array items: type: string ids_emails: type: array items: $ref: '#/components/schemas/Email' master_fpr: type: string revoked: type: boolean subkeys: type: array items: type: object required: - algorithm - auth - cert - encr - sign - bits - expired - expires - expires_date - expires_days - fpr - master properties: algorithm: type: string auth: type: boolean cert: type: boolean encr: type: boolean sign: type: boolean bits: type: integer format: int32 expired: type: boolean expires: type: integer format: int32 expires_days: type: string format: date-time example: "01/15/2099" fpr: type: string master: type: boolean description: Parseable, human-friendly information about a PGP key PgpKeyring: type: object required: - daemon - imported properties: daemon: $ref: '#/components/schemas/PgpKey' imported: type: array items: $ref: '#/components/schemas/PgpKey' description: Describes all PGP keys in the keyring PgpKeyExport: type: string example: | -----BEGIN PGP PUBLIC KEY BLOCK----- mQINBF957dABEADz7P2flznzRq5wuUhxDS+wytdn8yQhMXZr7kvcpwbRl9f7+dx3 mH8kH7owN9u8yBDsA9iW7fFNJnbSJNtPIFdOB08AeeIUGx6jsvWFd08+WdDulu1l wyR/UPvmYDYPwI5fqMy/Edne0qqgg6mzVk30cr8xDxaE1RNf3rVAWVdfbAUNF35M NhzjsrHZPKqpgvTLbsrV+87mc83FUwSgHQITY/E/04kJE2IbnNj3+5zYMlkhwEd/ 1afI9OFNTtIk5zYdoLPa8o/sNZZTjCgSp7pLI/2/o1CzI/NL2CEKjJgo5uwg9gHu e6vcUxez8uWAMOBwF3ogptr5mioT0ewbBto5Lbkv5jn8WbcpifbrDXqws1PZO+ZJ jUdhnrEWxE7DV1tM3CMYq5IzgbrhBPRUYhPX196HMRTRa2PwM1a8tPeilzM7NyrM MTYV3TO11kTKJcRr8/iSt/XpAQsV9EqI1ecUcDFX+U5LVEImHD3+BmQCT713LBRK HWWmY/oHumxxVjS0OQZyik8tIOOK5sy8JZr2A+p6qiLGs0SU6yUCPUonSjuc98ky rByV2GcVaxzT4qk1RiReDXkjIlGIXE4SzVUPHyYYoRvJVrRkQDN6fegvyQqszEAH 7OTXgNZ55BB+WWKCzhAoO2IJiwJXWLp3xqHni86gXSGrXi5RbmprGNHkwQARAQAB tERQb3dlciBNYWlsLWluLWEtQm94IE1hbmFnZW1lbnQgRGFlbW9uIDxhZG1pbmlz dHJhdG9yQG1haWxpbmFib3gubGFuPokCVAQTAQoAPhYhBGIDe4i3Q2Jpl+Y+/iRp OU+8DPjaBQJfee3QAhsvBQkA7U4ABQsJCAcCBhUKCQgLAgQWAgMBAh4BAheAAAoJ ECRpOU+8DPjaagYP/0nJyYG3ELcmqleJxSe6CuDrhNHTNyrJROqCTkeJmsWDxePK tRjuSZSkK7ZCjxthTwo4Yi5ylSh7a8Qt7OzvwaFcK78JvYYAz08tErDa7+t+Gj3T 32M00Wa/DykzBJqDlmTtAYVlmfPOegF30XOYQ8e7IGMOETZQClJE37g00Gz32QKi zf8ONje924xRU3PETySQjHtc5Zoio0Av8mARB2hiGQScNoQU3qzELX85x4qjKUJe mdIuSlf8NRwZ2Df2kBYBLzuX2lAKiIxY63V0j/a87OLViHdOQwb5SaV5s/3R/qf7 NSaVRsbxYuRO638K402tVffvl1jH9hvooRfsc7lj5XkxKAkMIDTJmBAVcXy4+n77 J20ZEz22ko87AwmHU6ZFh+RJiueOsqx09nnGOwmp7IXB47EDips1uVwPQ7GbkM1K 69CiS2K90X4WCaJhgLd7Saj8hCvfEUaHvUk/XoOGPjxj9iPzxFZgEb/2osSjqkJ5 9vQt31NbWpFJThHPXjixwIiWcn4m5yqcXjSNaHISvAZPtK55FXLp7uAOgiCygonK onuboXh6AK6cT0cdtOgWsz3AQ2mTkhKbK6hW7eIVwEs8SFPb5qNSxWxlssF5/QQi vo4j/rEYuOuqVo+TwsO0XNCfsA8as/UPLA9CgIxXXoIFmy2rL298lPQg5HgJ =via/ -----END PGP PUBLIC KEY BLOCK----- description: ASCII-Armored export of one or more public PGP key(s). PgpKeyImportResult: type: object required: - keys_read - keys_added - keys_unchanged - uids_added - sigs_added - revs_added properties: keys_read: type: integer format: int32 description: Keys in the import keys_added: type: integer format: int32 description: New keys keys_unchanged: type: integer format: int32 description: Keys that were not modified uids_added: type: integer format: int32 description: New user ID's sigs_added: type: integer format: int32 description: New key signatures revs_added: type: integer format: int32 description: New revocation certificates description: The result of the key import operation MfaStatusResponse: type: object properties: enabled_mfa: type: object properties: id: type: string type: type: string label: type: string nullable: true new_mfa: type: object properties: type: type: string secret: type: string qr_code_base64: type: string MfaEnableRequest: type: object required: - secret - code properties: secret: type: string code: type: string label: type: string MfaEnableSuccessResponse: type: string MfaDisableRequest: type: object properties: mfa_id: type: string nullable: true MfaDisableSuccessResponse: type: string LogoutResponse: type: object properties: status: type: string