Mail-in-a-Box User API

openapi: 3.2.0
info:
  title: Mail-in-a-Box User 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: User
  description: Endpoints related to user authentication.
paths:
  /login:
    post:
      tags:
      - User
      summary: Exchange a username and password for a session API key
      description: 'Returns user information and a session API key.


        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 in place of the password.'
      operationId: login
      x-codeSamples:
      - lang: curl
        source: "curl -X POST \"https://{host}/admin/login\" \\\n  -u \"<email>:<password>\"\n"
      responses:
        200:
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MeResponse'
              examples:
                invalid:
                  value:
                    reason: Incorrect username or password
                    status: invalid
                ok:
                  value:
                    api_key: 1a2b3c4d5e6f7g8h9i0j
                    email: user@example.com
                    privileges:
                    - admin
                    status: ok
  /logout:
    post:
      tags:
      - User
      summary: Invalidates a session API key
      description: Invalidates a session API key so that it cannot be used after this API call.
      operationId: logout
      x-codeSamples:
      - lang: curl
        source: "curl -X POST \"https://{host}/admin/logout\" \\\n  -u \"<email>:<session_key>\"\n"
      responses:
        200:
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LogoutResponse'
components:
  schemas:
    MailUserPrivilege:
      type: string
      enum:
      - admin
      - ''
      example: admin
      description: Mail user privilege.
    MeAuthStatus:
      type: string
      enum:
      - ok
      - invalid
      example: invalid
      description: Me (user) authentication result.
    LogoutResponse:
      type: object
      properties:
        status:
          type: string
    Email:
      type: string
      format: email
      example: user@example.com
      description: Email format.
    MeResponse:
      type: object
      required:
      - status
      properties:
        api_key:
          type: string
          example: 12345abcde
        email:
          $ref: '#/components/schemas/Email'
        privileges:
          type: array
          items:
            $ref: '#/components/schemas/MailUserPrivilege'
        reason:
          type: string
          example: Incorrect username or password
        status:
          $ref: '#/components/schemas/MeAuthStatus'
      description: Me (user) 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/