Mail-in-a-Box Mail API
Mail operations, which include getting all users, getting all aliases, adding/updating/removing users and aliases and getting all mail domains.
Mail operations, which include getting all users, getting all aliases, adding/updating/removing users and aliases and getting all mail domains.
Every API here is available over the APIs.io API and to AI agents over MCP.
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.curl "https://apis.io/api/v1/apis/mail-in-a-box:mail-in-a-box-mail-api"
curl "https://apis.io/api/v1/apis?limit=25"
Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. By signing up you are subscribing to the APIs.io and API Evangelist newsletters — you can unsubscribe from any issue. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.
openapi: 3.2.0
info:
title: in-a-Box Mail API
description: '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. If you have multi-factor authentication enabled, authentication with a `user:password` combination will fail unless a valid OTP is supplied via the `x-auth-token` header. Authentication via a `user:user_key` pair is possible without the header being present.'
contact:
name: Mail-in-a-Box support
url: https://mailinabox.email/
license:
name: CC0 1.0 Universal
url: https://creativecommons.org/publicdomain/zero/1.0/legalcode
version: 0.51.0
x-logo:
url: https://mailinabox.email/static/logo.png
altText: Mail-in-a-Box logo
servers:
- url: https://{host}/admin
variables:
host:
default: box.example.com
description: The API hostname.
security:
- basicAuth: []
tags:
- name: Mail
description: Mail operations, which include getting all users, getting all aliases, adding/updating/removing users and aliases and getting all mail domains.
paths:
/mail/users:
get:
tags:
- Mail
summary: Get mail users
description: Returns all mail users.
operationId: getMailUsers
parameters:
- in: query
name: format
schema:
$ref: '#/components/schemas/MailUsersResponseFormat'
description: The format of the response.
x-codeSamples:
- lang: curl
source: "curl -X GET \"https://{host}/admin/mail/users?format=<string>\" \\\n -u \"<email>:<password>\"\n"
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\" \\\n -d \"email=<email>\" \\\n -d \"password=<password>\" \\\n -d \"privileges=<string>\" \\\n -u \"<email>:<password>\"\n"
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\" \\\n -d \"email=<email>\" \\\n -u \"<email>:<password>\"\n"
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\" \\\n -d \"email=<email>\" \\\n -d \"privilege=<string>\" \\\n -u \"<email>:<password>\"\n"
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\" \\\n -d \"email=<email>\" \\\n -d \"privilege=<string>\" \\\n -u \"<email>:<password>\"\n"
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\" \\\n -d \"email=<email>\" \\\n -d \"password=<password>\" \\\n -u \"<email>:<password>\" \\\n"
responses:
200:
description: Successful operation
content:
text/html:
schema:
$ref: '#/components/schemas/MailUserSetPasswordResponse'
example: OK
400:
description: Bad request
content:
text/html:
schema:
type: string
example: Passwords must be at least eight characters
403:
description: Forbidden
content:
text/html:
schema:
type: string
/mail/users/privileges:
get:
tags:
- Mail
summary: Get mail user privileges
description: Returns all privileges for an existing mail user.
operationId: getMailUserPrivileges
parameters:
- in: query
name: email
schema:
$ref: '#/components/schemas/Email'
description: The email you want to get privileges for.
x-codeSamples:
- lang: curl
source: "curl -X GET \"https://{host}/admin/mail/users/privileges?email=<email>\" \\\n -u \"<email>:<password>\"\n"
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\" \\\n -u \"<email>:<password>\"\n"
responses:
200:
description: Successful operation
content:
text/html:
schema:
$ref: '#/components/schemas/MailDomainsResponse'
example: 'example1.com
example2.com
'
403:
description: Forbidden
content:
text/html:
schema:
type: string
/mail/aliases:
get:
tags:
- Mail
summary: Get mail aliases
description: Returns all mail aliases.
operationId: getMailAliases
parameters:
- in: query
name: format
schema:
$ref: '#/components/schemas/MailAliasesResponseFormat'
description: The format of the response.
x-codeSamples:
- lang: curl
source: "curl -X GET \"https://{host}/admin/mail/aliases?format=<string>\" \\\n -u \"<email>:<password>\"\n"
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\tadministrator@example.com\nadmin@example.com\tadministrator@example.com\n"
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: null
catchall:
summary: Catch-all
value:
update_if_exists: 0
address: '@example.com'
forwards_to: user@otherexample.com
permitted_senders: null
domainalias:
summary: Domain alias
value:
update_if_exists: 0
address: '@example.com'
forwards_to: '@otherexample.com'
permitted_senders: null
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\" \\\n -d \"update_if_exists=<integer>\" \\\n -d \"address=<email>\" \\\n -d \"forwards_to=<string>\" \\\n -d \"permitted_senders=<string>\" \\\n -u \"<email>:<password>\"\n"
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\" \\\n -d \"address=<email>\" \\\n -u \"<email>:<password>\"\n"
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
components:
schemas:
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
- 'null'
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.
MailUserPrivilegesResponse:
$ref: '#/components/schemas/MailUserPrivilege'
description: Mail user privileges response.
example: admin
MailUsersSimpleResponse:
type: string
example: 'user1@example.com
user2@example.com
'
description: Get mail users text format response.
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.
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
- 'null'
items:
$ref: '#/components/schemas/Email'
required:
type: boolean
example: true
description: Mail alias details.
MailUserRemovePrivilegeResponse:
type: string
example: OK
description: Mail user remove admin privilege response.
MailAliasUpsertResponse:
type: string
example: alias updated
description: Mail alias add/update response.
MailUserSetPasswordRequest:
type: object
required:
- email
- password
properties:
email:
$ref: '#/components/schemas/Email'
password:
type: string
format: password
description: Mail user set password request.
MailUsersResponse:
type: array
items:
$ref: '#/components/schemas/MailUserByDomain'
description: Get mail aliases JSON format response.
MailAliasRemoveRequest:
type: object
required:
- address
properties:
address:
$ref: '#/components/schemas/Email'
description: Mail aliases remove request.
MailAliasesResponseFormat:
type: string
enum:
- text
- json
example: json
description: Response format (`application/json` or `text/html`).
MailUserRemovePrivilegeRequest:
type: object
required:
- email
- privilege
properties:
email:
$ref: '#/components/schemas/Email'
privilege:
$ref: '#/components/schemas/MailUserPrivilege'
description: Mail user remove privilege request.
MailAliasesSimpleResponse:
type: string
example: "abuse@example.com\tadministrator@example.com\nadmin@example.com\tadministrator@example.com\n"
description: Get mail aliases text 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.
MailAliasRemoveResponse:
type: string
example: alias removed
description: Mail alias remove response.
MailUserRemoveResponse:
type: string
example: OK
description: Mail user remove response.
Hostname:
type: string
format: hostname
example: example.com
description: Hostname format.
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.
Email:
type: string
format: email
example: user@example.com
description: Email format.
MailUserStatus:
type: string
enum:
- active
- inactive
example: active
description: Mail user status.
MailUserSetPasswordResponse:
type: string
example: OK
description: Mail user set password response.
MailDomainsResponse:
type: string
example: 'example1.com
example2.com
'
description: Mail domains response.
MailUserPrivilege:
type: string
enum:
- admin
- ''
example: admin
description: Mail user privilege.
MailUsersResponseFormat:
type: string
enum:
- text
- json
example: json
description: Response format (`application/json` or `text/html`).
MailUserRemoveRequest:
type: object
required:
- email
properties:
email:
$ref: '#/components/schemas/Email'
description: Mail user remove request.
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.
'
MailUserAddPrivilegeRequest:
type: object
required:
- email
- privilege
properties:
email:
$ref: '#/components/schemas/Email'
privilege:
$ref: '#/components/schemas/MailUserPrivilege'
description: Mail user add privilege request.
MailUserAddPrivilegeResponse:
type: string
example: OK
description: Mail user add admin privilege response.
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.
'
externalDocs:
description: Find out more about Mail-in-a-box.
url: https://mailinabox.email/