Mail-in-a-Box

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.

GitHub OpenAPI

Operations 11

GET /mail/users Get mail users #
POST /mail/users/add Add mail user #
POST /mail/users/remove Remove mail user #
POST /mail/users/privileges/add Add mail user privilege #
POST /mail/users/privileges/remove Remove mail user privilege #
POST /mail/users/password Set mail user password #
GET /mail/users/privileges Get mail user privileges #
GET /mail/domains Get mail domains #
GET /mail/aliases Get mail aliases #
POST /mail/aliases/add Upsert mail alias #
POST /mail/aliases/remove Remove mail alias #

Specifications

⚙
OpenAPI
https://artifacts.apis.io/mail-in-a-box/openapi/mail-in-a-box-mail-api-openapi.yml

Schemas & Data

📊
JSONSchema
https://artifacts.apis.io/mail-in-a-box/json-schema/mail-in-a-box-sslcertificate-install-request-schema.json
📊
JSONSchema
https://artifacts.apis.io/mail-in-a-box/json-schema/mail-in-a-box-mail-alias-upsert-request-schema.json
📊
JSONSchema
https://artifacts.apis.io/mail-in-a-box/json-schema/mail-in-a-box-sslcsrgenerate-response-schema.json
📊
JSONSchema
https://artifacts.apis.io/mail-in-a-box/json-schema/mail-in-a-box-system-update-packages-response-schema.json
📊
JSONSchema
https://artifacts.apis.io/mail-in-a-box/json-schema/mail-in-a-box-system-backup-config-response-schema.json
📊
JSONSchema
https://artifacts.apis.io/mail-in-a-box/json-schema/mail-in-a-box-web-domain-schema.json

Work with this as data

Every API here is available over the APIs.io API and to AI agents over MCP.

MCP server

One button, every client — Claude, Cursor, VS Code and the rest.

https://apis.io/mcp

Tools for apis

7 MCP tools reach this
  • 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.
All 92 tools →

Call it yourself

curl for this page
This API 
curl "https://apis.io/api/v1/apis/mail-in-a-box:mail-in-a-box-mail-api"
All apis 
curl "https://apis.io/api/v1/apis?limit=25"

Discovery needs no key. Ratings and market analysis are Pro.

Get an API 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. See our Privacy Policy and Terms.

GitHub Google LinkedIn

A second provider on the same verified email joins the account you already have.

OpenAPI Specification

mail-in-a-box-mail-api-openapi.yml Raw ↑ 
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/