# mailcow-admin-aliases
![status-badge](https://ci.lila.network/api/badges/24/status.svg)
[![Please don't upload to GitHub](https://nogithub.codeberg.page/badge.svg)](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.