Mail-in-a-Box (0.47.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.
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 |
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
curl -X GET "https://{host}/admin/me" \ -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