Mail-in-a-Box Web API

openapi: 3.2.0
info:
  title: Mail-in-a-Box Web 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: Web
  description: Static web hosting operations, which include getting domain information and updating domain root directories.
paths:
  /web/domains:
    get:
      tags:
      - Web
      summary: Get web domains
      description: Returns all static web domains.
      operationId: getWebDomains
      x-codeSamples:
      - lang: curl
        source: "curl -X GET \"https://{host}/admin/web/domains\" \\\n  -u \"<email>:<password>\"\n"
      responses:
        200:
          description: Successful operation
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/WebDomain'
        403:
          description: Forbidden
          content:
            text/html:
              schema:
                type: string
  /web/update:
    post:
      tags:
      - Web
      summary: Update web
      description: Updates static websites, used for updating domain root directories.
      operationId: updateWeb
      x-codeSamples:
      - lang: curl
        source: "curl -X POST \"https://{host}/admin/web/update\" \\\n  -u \"<email>:<password>\"\n"
      responses:
        200:
          description: Successful operation
          content:
            text/html:
              schema:
                $ref: '#/components/schemas/WebUpdateResponse'
              example: web updated
        403:
          description: Forbidden
          content:
            text/html:
              schema:
                type: string
components:
  schemas:
    WebDomain:
      type: object
      required:
      - custom_root
      - domain
      - root
      - ssl_certificate
      - static_enabled
      properties:
        custom_root:
          type: string
          example: /home/user-data/www/example.com
        domain:
          $ref: '#/components/schemas/Hostname'
        root:
          type: string
          example: /home/user-data/www/default
        ssl_certificate:
          type: array
          minItems: 2
          maxItems: 2
          uniqueItems: true
          items:
            oneOf:
            - type: string
              example: No certificate installed.
            - type: string
              enum:
              - danger
              - success
              example: danger
        static_enabled:
          type: boolean
          example: true
      description: Web domain details.
    Hostname:
      type: string
      format: hostname
      example: example.com
      description: Hostname format.
    WebUpdateResponse:
      type: string
      example: web updated
      description: Web update 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/