Mail-in-a-Box (0.51.0)
Mail-in-a-Box API HTTP specification.
This API is documented in OpenAPI format. (View the full HTTP specification.)
All endpoints are relative to https://{host}/admin and are secured with Basic Access authentication. If you have multi-factor authentication enabled, authentication with a user:password combination will fail unless a valid OTP is supplied via the x-auth-token header. Authentication via a user:user_key pair is possible without the header being present.
basicAuth
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.
| Security Scheme Type | HTTP |
|---|---|
| HTTP Authorization Scheme | basic |
Exchange a username and password for a session API key.
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.
Authorizations:
Responses
Request samples
- curl
curl -X GET "https://{host}/admin/login" \ -u "<email>:<password>"
Response samples
- 200
{- "reason": "Incorrect username or password",
- "status": "invalid"
}Mail operations, which include getting all users, getting all aliases, adding/updating/removing users and aliases and getting all mail domains.
Get mail users
Returns all mail users.
Authorizations:
query Parameters
| format | string (MailUsersResponseFormat) Enum: "text" "json" Example: format=json The format of the response. |
Responses
Request samples
- curl
curl -X GET "https://{host}/admin/mail/users?format=<string>" \ -u "<email>:<password>"
Response samples
- 200
[- {
- "domain": "example.com",
- "users": [
- {
- "email": "user@example.com",
- "privileges": [
- "admin"
], - "status": "active",
- "mailbox": "/home/user-data/mail/mailboxes/example.com/user"
}
]
}
]Add mail user
Adds a new mail user.
Authorizations:
Request Body schema: application/x-www-form-urlencoded
| email required | string <email> (Email) Email format. |
| password required | string <password> |
| privileges required | string (MailUserPrivilege) Enum: "admin" "" Mail user privilege. |
Responses
Request samples
- Payload
- curl
email=user%40example.com&password=s3curE_pa5Sw0rD&privileges=
Response samples
- 200
mail user added
updated DNS: OpenDKIM configuration
Remove mail user
Removes an existing mail user.
Authorizations:
Request Body schema: application/x-www-form-urlencoded
| email required | string <email> (Email) Email format. |
Responses
Request samples
- Payload
- curl
email=user%40example.com
Response samples
- 200
OK
Add mail user privilege
Adds a privilege to an existing mail user.
Authorizations:
Request Body schema: application/x-www-form-urlencoded
| email required | string <email> (Email) Email format. |
| privilege required | string (MailUserPrivilege) Enum: "admin" "" Mail user privilege. |
Responses
Request samples
- Payload
- curl
email=user%40example.com&privilege=admin
Response samples
- 200
OK
Remove mail user privilege
Removes a privilege from an existing mail user.
Authorizations:
Request Body schema: application/x-www-form-urlencoded
| email required | string <email> (Email) Email format. |
| privilege required | string (MailUserPrivilege) Enum: "admin" "" Mail user privilege. |
Responses
Request samples
- Payload
- curl
email=user%40example.com&privilege=admin
Response samples
- 200
OK
Set mail user password
Sets a password for an existing mail user.
Authorizations:
Request Body schema: application/x-www-form-urlencoded
| email required | string <email> (Email) Email format. |
| password required | string <password> |
Responses
Request samples
- Payload
- curl
email=user%40example.com&password=s3curE_pa5Sw0rD
Response samples
- 200
OK
Get mail user privileges
Returns all privileges for an existing mail user.
Authorizations:
query Parameters
string <email> (Email) Example: email=user@example.com The email you want to get privileges for. |
Responses
Request samples
- curl
curl -X GET "https://{host}/admin/mail/users/privileges?email=<email>" \ -u "<email>:<password>"
Response samples
- 200
admin
Request samples
- curl
curl -X GET "https://{host}/admin/mail/domains" \ -u "<email>:<password>"
Response samples
- 200
example1.com example2.com
Get mail aliases
Returns all mail aliases.
Authorizations:
query Parameters
| format | string (MailAliasesResponseFormat) Enum: "text" "json" Example: format=json The format of the response. |
Responses
Request samples
- curl
curl -X GET "https://{host}/admin/mail/aliases?format=<string>" \ -u "<email>:<password>"
Response samples
- 200
[- {
- "domain": "example.com",
- "aliases": [
- {
- "address": "user@example.com",
- "address_display": "user@example.com",
- "forwards_to": [
- "user@example.com"
], - "permitted_senders": [
- "user@example.com"
], - "required": true
}
]
}
]Upsert mail alias
Adds or updates a mail alias. If updating, you need to set update_if_exists: 1.
Authorizations:
Request Body schema: application/x-www-form-urlencoded
| update_if_exists required | integer <int32> [ 0 .. 1 ] Set to |
| address required | string <email> (Email) Email format. |
| forwards_to required | string If adding a regular or catch-all alias, the format needs to be If adding a domain alias, the format needs to be |
| permitted_senders required | string or null 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 |
Responses
Request samples
- Payload
- curl
update_if_exists=0&address=user%40example.com&forwards_to=user2%40example.com&
Response samples
- 200
alias updated
Remove mail alias
Removes a mail alias.
Authorizations:
Request Body schema: application/x-www-form-urlencoded
| address required | string <email> (Email) Email format. |
Responses
Request samples
- Payload
- curl
address=user%40example.com
Response samples
- 200
alias removed
DNS operations, which include adding custom records, adding a secondary nameserver and viewing all DNS records.
Add DNS secondary nameserver
Adds one or more secondary nameservers.
Authorizations:
Request Body schema: application/x-www-form-urlencoded
| hostnames required | string Hostnames separated with commas or spaces. |
Responses
Request samples
- Payload
- curl
hostnames=ns2.hostingcompany.com%2C%20ns3.hostingcompany.com
Response samples
- 200
updated DNS: example.com
Request samples
- curl
curl -X GET "https://{host}/admin/dns/zones" \ -u "<email>:<password>"
Response samples
- 200
[- "example.com"
]Get DNS zonefile
Returns a DNS zone file for a hostname.
Authorizations:
path Parameters
| zone required | string <hostname> (Hostname) Example: example.com Hostname |
Responses
Request samples
- curl
curl -X GET "https://{host}/admin/dns/zonefile/<zone>" \ -u "<email>:<password>"
Response samples
- 200
"string"Update DNS
Updates the DNS. Involves creating zone files and restarting nsd.
Authorizations:
Request Body schema: application/x-www-form-urlencoded
| force required | integer <int32> [ 0 .. 1 ] Force an update even if mailinabox detects no changes are required. |
Responses
Request samples
- Payload
- curl
force=1
Response samples
- 200
"updated DNS: example1.com,example2.com\n"Request samples
- curl
curl -X GET "https://{host}/admin/dns/custom" \ -u "<email>:<password>"
Response samples
- 200
[- {
- "qname": "example.com",
- "rtype": "MX",
- "value": "10 example.com."
}
]Get DNS custom records
Returns all custom records for the specified query name and type.
Authorizations:
path Parameters
| qname required | string <hostname> (Hostname) Example: example.com DNS record query name |
| rtype required | any (DNSRecordType) Enum: "A" "AAAA" "CAA" "CNAME" "TXT" "MX" "SRV" "SSHFP" "NS" Example: MX Record type |
Responses
Request samples
- curl
curl -X GET "https://{host}/admin/dns/custom/<qname>/<rtype>" \ -u "<email>:<password>"
Response samples
- 200
[- {
- "qname": "example.com",
- "rtype": "MX",
- "value": "10 example.com."
}
]Add DNS custom record
Adds a custom DNS record for the specified query name and type.
Authorizations:
path Parameters
| qname required | string <hostname> (Hostname) Example: example.com DNS record query name |
| rtype required | any (DNSRecordType) Enum: "A" "AAAA" "CAA" "CNAME" "TXT" "MX" "SRV" "SSHFP" "NS" Example: MX Record type |
Request Body schema: text/plain
The value of the DNS record.
Responses
Request samples
- Payload
- curl
1.2.3.4
Response samples
- 200
updated DNS: example.com
Update DNS custom record
Updates an existing DNS custom record value for the specified qname and type.
Authorizations:
path Parameters
| qname required | string <hostname> (Hostname) Example: example.com DNS record query name |
| rtype required | any (DNSRecordType) Enum: "A" "AAAA" "CAA" "CNAME" "TXT" "MX" "SRV" "SSHFP" "NS" Example: MX Record type |
Request Body schema: text/plain
The value of the DNS record.
Responses
Request samples
- Payload
- curl
1.2.3.4
Response samples
- 200
updated DNS: example.com
Remove DNS custom record
Removes a DNS custom record for the specified domain, type & value.
Authorizations:
path Parameters
| qname required | string <hostname> (Hostname) Example: example.com DNS record query name |
| rtype required | any (DNSRecordType) Enum: "A" "AAAA" "CAA" "CNAME" "TXT" "MX" "SRV" "SSHFP" "NS" Example: MX Record type |
Request Body schema: text/plain
The value of the DNS record.
Responses
Request samples
- Payload
- curl
1.2.3.4
Response samples
- 200
updated DNS: example.com
Get DNS custom A records
Returns all custom A records for the specified query name.
Authorizations:
path Parameters
| qname required | string <hostname> (Hostname) Example: example.com DNS query name. |
Responses
Request samples
- curl
curl -X GET "https://{host}/admin/dns/custom/<qname>" \ -u "<email>:<password>"
Response samples
- 200
[- {
- "qname": "example.com",
- "rtype": "MX",
- "value": "10 example.com."
}
]Add DNS custom A record
Adds a custom DNS A record for the specified query name.
Authorizations:
path Parameters
| qname required | string <hostname> (Hostname) Example: example.com DNS query name. |
Request Body schema: text/plain
The value of the DNS record.
Responses
Request samples
- Payload
- curl
1.2.3.4
Response samples
- 200
updated DNS: example.com
Update DNS custom A record
Updates an existing DNS custom A record value for the specified qname.
Authorizations:
path Parameters
| qname required | string <hostname> (Hostname) Example: example.com DNS query name. |
Request Body schema: text/plain
The value of the DNS record.
Responses
Request samples
- Payload
- curl
1.2.3.4
Response samples
- 200
updated DNS: example.com
Remove DNS custom A record
Removes a DNS custom A record for the specified domain & value.
Authorizations:
path Parameters
| qname required | string <hostname> (Hostname) Example: example.com DNS query name. |
Request Body schema: text/plain
The value of the DNS record.
Responses
Request samples
- Payload
- curl
1.2.3.4
Response samples
- 200
updated DNS: example.com
Request samples
- curl
curl -X GET "https://{host}/admin/dns/dump" \ -u "<email>:<password>"
Response samples
- 200
[- [
- "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."
}
]
]
]TLS (SSL) Certificates operations, which include checking certificate status and installing custom certificates.
Request samples
- curl
curl -X GET "https://{host}/admin/ssl/status" \ -u "<email>:<password>"
Response samples
- 200
{- "can_provision": [
- "string"
], - "status": [
- {
- "domain": "example.com",
- "status": "success",
- "text": "Signed & valid. The certificate expires in 87 days on 10/28/20."
}
]
}Generate SSL CSR
Generates a Certificate Signing Request (CSR) for a domain & country code.
Authorizations:
path Parameters
| domain required | string <hostname> (Hostname) Example: example.com Domain to generate CSR for. |
Request Body schema: application/x-www-form-urlencoded
| countrycode required | string |
Responses
Request samples
- Payload
- curl
countrycode=GBResponse samples
- 200
-----BEGIN CERTIFICATE REQUEST----- MIICaDCCAVACAQAwIzELMAkGA1UEBhMCQlMxFDASBgNVBAMMC2V4YW1wbGUuY29t ... JmFDQESSfUxLPHLC660Wnf3GmrP/duZHpPC+qTe8b1AlQ7zDT3cOaAQ+Mb0= -----END CERTIFICATE REQUEST-----
Install SSL certificate
Installs a custom certificate. The chain certificate is optional.
Authorizations:
Request Body schema: application/x-www-form-urlencoded
| domain required | string <hostname> (Hostname) Hostname format. |
| cert required | string TLS/SSL certificate. |
| chain required | string TLS/SSL intermediate chain (if provided, else empty string). |
Responses
Request samples
- Payload
- curl
domain=example.com&cert=CERT_STRING&chain=CHAIN_STRING
Response samples
- 200
OK
Request samples
- curl
curl -X POST "https://{host}/admin/ssl/provision" \ -u "<email>:<password>"
Response samples
- 200
{- "requests": [
- {
- "log": [
- "The domain name does not resolve to this machine: [Not Set] (A), [Not Set] (AAAA)."
], - "result": "installed",
- "domains": [
- "example.com"
]
}
]
}Static web hosting operations, which include getting domain information and updating domain root directories.
Request samples
- curl
curl -X GET "https://{host}/admin/web/domains" \ -u "<email>:<password>"
Response samples
- 200
[- {
- "custom_root": "/home/user-data/www/example.com",
- "domain": "example.com",
- "root": "/home/user-data/www/default",
- "ssl_certificate": [
- "No certificate installed.",
- "No certificate installed."
], - "static_enabled": true
}
]Retrieve MFA status for you or another user
Retrieves which type of MFA is used and configuration
Authorizations:
Responses
Request samples
- curl
curl -X POST "https://{host}/admin/mfa/status" \ -u "<email>:<password>"
Response samples
- 200
{- "enabled_mfa": {
- "id": "string",
- "type": "string",
- "label": "string"
}, - "new_mfa": {
- "type": "string",
- "secret": "string",
- "qr_code_base64": "string"
}
}Enable TOTP authentication
Enables TOTP authentication for the currently logged-in admin user
Authorizations:
Request Body schema: application/x-www-form-urlencoded
| secret required | string |
| code required | string |
| label | string |
Responses
Request samples
- curl
curl -X POST "https://{host}/admin/mfa/totp/enable" \ -d "code=123456" \ -d "secret=<string>" \ -u "<email>:<password>"
Disable multi-factor authentication for you or another user
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.
Authorizations:
Request Body schema: application/x-www-form-urlencoded
| mfa_id | string or null |
Responses
Request samples
- curl
curl -X POST "https://{host}/admin/mfa/totp/disable" \ -u "<email>:<user_key>"
Get system status
Returns an array of statuses which can include headings.
Authorizations:
Responses
Request samples
- curl
curl -X POST "https://{host}/admin/system/status" \ -u "<email>:<password>"
Response samples
- 200
[- {
- "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"
}
]
}
]Request samples
- curl
curl -X GET "https://{host}/admin/system/version" \ -u "<email>:<password>"
Response samples
- 200
v0.46
Request samples
- curl
curl -X GET "https://{host}/admin/system/updates" \ -u "<email>:<password>"
Response samples
- 200
libgnutls30 (3.5.18-1ubuntu1.4) libxau6 (1:1.0.8-1ubuntu1)
Request samples
- curl
curl -X POST "https://{host}/admin/system/update-packages" \ -u "<email>:<password>"
Response samples
- 200
Calculating upgrade... The following packages will be upgraded: cloud-init grub-common
Get system privacy status
Returns system privacy (new-version check) status.
Response:
true: Private, new-version checks will not be performedfalse: Not private, new-version checks will be performed
Authorizations:
Responses
Request samples
- curl
curl -X GET "https://{host}/admin/system/privacy" \ -u "<email>:<password>"
Response samples
- 200
falseUpdate system privacy
Updates system privacy (new-version checks).
Request:
value: private: Disable new version checksvalue: off: Enable new version checks
Authorizations:
Request Body schema: application/x-www-form-urlencoded
| value required | string (SystemPrivacyStatus) Enum: "private" "off" System privacy status. |
Responses
Request samples
- Payload
- curl
value=offResponse samples
- 200
OK
Get system reboot status
Returns the system reboot status.
Response:
true: A reboot is requiredfalse: A reboot is not required
Authorizations:
Responses
Request samples
- curl
curl -X GET "https://{host}/admin/system/reboot" \ -u "<email>:<password>"
Response samples
- 200
trueRequest samples
- curl
curl -X POST "https://{host}/admin/system/reboot" \ -u "<email>:<password>"
Response samples
- 200
No reboot is required, so it is not allowed.
Get system backup status
Returns the system backup status.
If the list of backups is empty, this implies no backups have been made yet.
Authorizations:
Responses
Request samples
- curl
curl -X GET "https://{host}/admin/system/backup/status" \ -u "<email>:<password>"
Response samples
- 200
{- "backups": [
- {
- "date": "20200801T023706Z",
- "date_delta": "15 hours, 40 minutes",
- "date_str": "2020-08-01 03:37:06 BST",
- "deleted_in": "approx. 6 days",
- "full": false,
- "size": 125332,
- "volumes": 1
}
], - "unmatched_file_size": 0,
- "error": "Something is wrong with the backup"
}Request samples
- curl
curl -X GET "https://{host}/admin/system/backup/config" \ -u "<email>:<password>"
Response samples
- 200
{- "enc_pw_file": "/home/user-data/backup/secret_key.txt",
- "file_target_directory": "/home/user-data/backup/encrypted",
- "min_age_in_days": 3,
- "ssh_pub_key": "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQDb root@box.example.com\\n",
- "target": "s3://s3.eu-central-1.amazonaws.com/box-example-com",
- "target_user": "string",
- "target_pass": "string"
}Update system backup config
Updates the system backup config.
Authorizations:
Request Body schema: application/x-www-form-urlencoded
| target required | string <hostname> |
| target_user required | string |
| target_pass required | string <password> |
| min_age required | integer <int32> >= 1 |
Responses
Request samples
- Payload
- curl
target=s3%3A%2F%2Fs3.eu-central-1.amazonaws.com%2Fbox-example-com&target_user=ACCESS_KEY&target_pass=SECRET_ACCESS_KEY&minAge=3
Response samples
- 200
OK