101 lines
4.4 KiB
Markdown
101 lines
4.4 KiB
Markdown
# mailcow-admin-aliases
|
||
|
||
[](https://nogithub.codeberg.page)
|
||
|
||
## Introduction
|
||
Many mail administrators (me included) want to have some specific email addresses (like postmaster@..., security@..., abuse@..., etc.) always point to a dedicated administrator mailbox, so that e.g. mails regarding abuse or security issues will always be at one central management point.
|
||
|
||
If you are using [Mailcow](https://docs.mailcow.email/) as your mail server, you'd have to manually add those mail addresses as _aliases_ by hand. I'm also hosting my own Mailcow instance, and by now I have enough (sub)domains that manually adding aliases gets tedious _very quickly_. Thats why I created `mailcow-admin-aliases`.
|
||
|
||
With `mailcow-admin-aliases` you can (automatically) create the mail aliases you want, e.g. if you configure a new domain. In the [examples](examples/) folder you can find _systemd_ service and timer files to automate the creation of your aliases. `mailcow-admin-aliases` will check which ones already exist and will skip those.
|
||
|
||
This application is successfully tested with mailcow `2023-03` to `2024-06c`, but it should work with older versions too.
|
||
|
||
## Quick Start
|
||
|
||
Installation of the required Mailcow instance is way out of scope of this documentation. For detailed instructions regarding Mailcow, please visit [it's documentation](https://docs.mailcow.email/)
|
||
|
||
|
||
To quickly get started with `mailcow-admin-aliases`, just download the binary from [the mailcow-admin-aliases Release page](https://code.lila.network/adoralaura/mailcow-admin-aliases/releases)...
|
||
|
||
... fill out the config file...
|
||
```shell
|
||
vi config.yaml
|
||
```
|
||
```yaml
|
||
---
|
||
# Base-Url of your Mailcow instance.
|
||
# format: "https://mail.example.com"
|
||
api_endpoint:
|
||
|
||
# Read/Write API Key from your Mailcow instance
|
||
# See the [+] API Section at <your-instance>/admin
|
||
# format: "XXXXXX-XXXXXX-XXXXXX-XXXXXX-XXXXXX"
|
||
api_key:
|
||
|
||
# The mail address the aliases should point to
|
||
# Should be a mailbox on your Mailcow instance
|
||
# format: "admin-mail@your-domain.com"
|
||
admin_email:
|
||
|
||
# Local part of your important aliases you want created
|
||
# Example: if you want security@<your-domains.tld>, one entry should be - security
|
||
mail_prefixes:
|
||
- abuse
|
||
- admin
|
||
- postmaster
|
||
- security
|
||
- webadmin
|
||
- webmaster
|
||
```
|
||
|
||
... and run it!
|
||
```shell
|
||
mailcow-admin-aliases --config /path/to/config.yaml
|
||
```
|
||
|
||
## `mailcow-admin-aliases` CLI flags
|
||
when using `mailcow-admin-aliases`, you have the following CLI flag options:
|
||
```
|
||
-c, --config string Path to config file (default: $WorkDir/config.yaml)
|
||
--debug Enable debug logging (beats --quiet)
|
||
-d, --dry-run Show what this application *would* do
|
||
-q, --quiet Disable logging
|
||
-v, --version Show version information
|
||
-h, --help Show this overview
|
||
```
|
||
|
||
You can also see the list of CLI options with `--help`
|
||
|
||
## How it works
|
||
|
||
`mailcow-admin-aliases` queries the API of the configured Mailcow instance to
|
||
- get the currently configured Mailcow domains
|
||
- get the list of currently configured aliases
|
||
- create missing aliases
|
||
|
||
## Scaling
|
||
As this is a Go application, performance shsould generally be pretty good. **However**, I currently do not have access to a big Mailcow test instance. Should you run into scaling/performance issues, please don't hesitate to contact me!
|
||
|
||
## Contributing
|
||
|
||
I use my own [Forgejo Instance](https://code.lila.network) to manage issues and pull requests.
|
||
|
||
* If you have a trivial fix or improvement, go ahead and create a pull request,
|
||
addressing (with `@...`) the maintainer of this repository (see
|
||
[MAINTAINERS.md](MAINTAINERS.md)) in the description of the pull request.
|
||
|
||
* If you plan to do something more involved, first please [send me a mail]( mailto:dev@lauka.net?subject=%5Bmailcow-admin-aliases%5D).
|
||
|
||
### What to contribute
|
||
|
||
The best way to help without speaking a lot of Go would be to share your
|
||
configuration, alerts, dashboards, and recording rules. If you have something
|
||
that works and is not in the repository, please pay it forward and
|
||
share what works.
|
||
|
||
## Changelog
|
||
You can find the Changelog here: [Changelog](https://code.lila.network/adoralaura/mailcow-admin-aliases/src/branch/main/CHANGELOG.md)
|
||
|
||
## License
|
||
`mailcow-admin-aliases` is available under the MIT license. See the [LICENSE](https://code.lila.network/adoralaura/mailcow-admin-aliases/src/branch/main/LICENSE) file for more info.
|