Mail-in-a-Box (0.47.0)

Mail-in-a-Box API HTTP specification.

Introduction

This API is documented in OpenAPI format. (View the full HTTP specification.)

All endpoints are relative to https://{host}/admin and are secured with Basic Access authentication.

Authentication

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 getMe operation.

When using curl, you can supply user credentials using the -u or --user parameter.

Security Scheme Type HTTP
HTTP Authorization Scheme basic

User

Endpoints related to user authentication.

Get user information

Returns user information. Used for user authentication.

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.

Authorizations:

Responses

Request samples

curl -X GET "https://{host}/admin/me" \
  -u "<email>:<password>"

Response samples

Content type
application/json
Example
{
  • "reason": "Incorrect username or password",
  • "status": "invalid"
}

Mail

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 -X GET "https://{host}/admin/mail/users?format=<string>" \
  -u "<email>:<password>"

Response samples

Content type
[
  • {
    • "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

Content type
application/x-www-form-urlencoded
Example
email=user%40example.com&password=s3curE_pa5Sw0rD&privileges=

Response samples

Content type
text/html
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

Content type
application/x-www-form-urlencoded
email=user%40example.com

Response samples

Content type
text/html
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

Content type
application/x-www-form-urlencoded
email=user%40example.com&privilege=admin

Response samples