# mailinabox

Python client library and CLI for the [Mail-in-a-Box](https://mailinabox.email/) admin DNS API.

Licensed under the [MIT License](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

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

### Install from git

```sh
pip install git+https://gitea.koszewscy.waw.pl/koszewscy/mailinabox.git@main
```

`python-helpers` is declared as a git direct reference, so pip clones it rather than looking it
up on an index.

### Running without installing

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

```sh
python3 -m mailinabox.cli.miab --help
```

From outside the checkout, point `PYTHONPATH` at it:

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


## Library

```python
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

```sh
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.

```sh
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.

```sh
# 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:

```sh
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.