mailinabox

Python client library and CLI for the Mail-in-a-Box admin DNS API.

Licensed under the MIT License.

Installation

The miab command is installed into the active virtual environment by any of the methods below. The package depends on python-helpers 1.0.0 or later, which provides the python_helpers package.

Local install

pip install -e .   # editable, for development: picks up source changes without reinstalling
pip install .      # normal install: copies the package in

Install from git

pip install git+<repository-url>@main

Running without installing

From a repo checkout, run the command as a module with -m instead of installing the package:

python3 -m mailinabox.cli.miab --help

From outside the checkout, point PYTHONPATH at it:

PYTHONPATH=/path/to/mailinabox python3 -m mailinabox.cli.miab --help

Library

from mailinabox.dns import Client

# Explicit credentials:
client = Client("box.example.com", "admin@example.com", "password")

# From environment variables (MIAB_* or MAILINABOX_* style):
client = Client()

client.set_record("foo.example.com", "TXT", "v=spf1 ~all")
client.add_record("foo.example.com", "A", "1.2.3.4")
client.delete_record("foo.example.com", "A", "1.2.3.4")

records = client.list_records("TXT")

list_records returns a list of DNSRecord named tuples with name, type and value fields. Every method raises mailinabox.dns.MailInABoxError if credentials are missing or the API rejects the request.

CLI

miab [--env-file FILE] list   [--type TYPE]
miab [--env-file FILE] set    [--type TYPE] <name> <value>
miab [--env-file FILE] add    [--type TYPE] <name> <value>
miab [--env-file FILE] delete [--type TYPE] <name> [value]

--type defaults to A for set, add and delete; list shows every record type unless one is given. Omitting the value for delete removes all records of that type for the name.

miab list --type TXT
miab set --type TXT foo.example.com "v=spf1 ~all"
miab add --type A foo.example.com 1.2.3.4
miab delete --type A foo.example.com 1.2.3.4

Credentials

Credentials are read from the environment; either naming style is accepted, with MIAB_* taking precedence.

# MIAB style
export MIAB_HOST=box.example.com
export MIAB_USERNAME=admin@example.com
export MIAB_PASSWORD=password

# Mail-in-a-Box style
export MAILINABOX_BASE_URL=https://box.example.com
export MAILINABOX_EMAIL=admin@example.com
export MAILINABOX_PASSWORD=password

The hostname is parsed out of MAILINABOX_BASE_URL when MIAB_HOST is not set.

Environment file

--env-file|-E reads the same variables from a file in docker run --env-file syntax, overriding any inherited from the shell. It is a global option and goes before the command name:

miab --env-file box.env list --type TXT

# Mail-in-a-Box credentials
MIAB_HOST=box.example.com
MIAB_USERNAME=admin@example.com
MIAB_PASSWORD=password

Parsing is done by python_helpers.env.load_env_file, which documents the full syntax.

AI Disclaimer

This project was generated with the assistance of AI tools. While efforts have been made to ensure the accuracy and reliability of the code, users should review and test the code thoroughly before using it in production environments. The author is not responsible for any issues arising from the use of this code.

3.4 KiB Raw Blame History