129 lines
3.5 KiB
Markdown
129 lines
3.5 KiB
Markdown
# 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.
|