Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.
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. 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.
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/