maddy/docs/tutorials/multiple-domains.md

Multiple domains configuration

Separate account namespaces

Given two domains, example.org and example.com. foo@example.org and foo@example.com are different and completely independent accounts.

All changes needed to make it work is to make sure all domains are specified in the $(local_domains) macro in the main configuration file. Note that you need to pick one domain as a "primary" for use in auto-generated messages.

$(primary_domain) = example.org
$(local_domains) = $(primary_domain) example.com

The base configuration is done. You can create accounts using maddyctl using both domains in the name, send and receive messages and so on. Do not forget to configure corresponding SPF, DMARC and MTA-STS records as was recommended in the introduction tutorial.

DKIM

However, one thing needs special attention since at the moment maddy lacks the ability to automatically select the corresponding DKIM key. Without additional changes with the above configuration it will sign all messages using the key for the primary domain. So you should configure corresponding mappings to make it use the proper key depending on the sender domain.

To do so, open your configuration and look for the submission endpoint block. Then take a look at default_destination directive that is responsible for handling deliveries to non-local addresses there.

You will notice it referes to the local_modifiers block which uses sign_dkim $(primary_domain) default. It is kinda obvious what is happening here.

First, remove the deliver_to &remote_queue line from here and replace it with the following:

reroute {
  source example.com {
    modify { sign_dkim example.com default }
    deliver_to &remote_queue
  }
  source example.org {
    modify { sign_dkim example.org default }
    deliver_to &remote_queue
  }
  default_source {
    reject 501 5.1.8 "Non-local sender domain"
  }
}

Replace example.com and example.org with your domains. Add more source blocks if you need to handle more domains.

This whole block tells maddy to take a look at the sender domain after deciding that the message should be sent to the Internet and apply the corresponding set of modifiers. Each set of modifiers consequently contains the sign_dkim module reference that is responsible for DKIM signature creation using domain-specific key. After that the message ends up in the outbound queue as usual.

Single account namespace

Lets say you want to handle messages for domains example.org and example.com and make that foo@example.org and foo@example.com are the same accounts. Sadly, this case is not very well-supported by maddy, but it still can be implemented.

You already should have the primary domain set for autogenerated messages and so on. The idea is to redirect all messages from non-primary domains to the primary one.

For each handled domain, the following line should be added to the local_modifiers block:

replace_rcpt /(.+)@example.com/ $1@$(primary_domain)

It does regexp replacement, turning anything@example.com into anything@$(primary_domain) where $(primary_domain) in our case is example.org.

E.g.

$(primary_domain) = example.org

modifiers local_modifiers {
    replace_rcpt /(.+)@example.net/ $1@$(primary_domain)
    replace_rcpt /(.+)@example.com/ $1@$(primary_domain)
}

With that configuration, all messages for foo@example.net and foo@example.com will end up in the foo@example.org mailbox.

Note, however, no account credentials aliasing is done. Users should always use the account name with the primary domain to access IMAP mailboxes.

Note 1: All domains should still be listed in the $(local_domains) macro. Note 2: Section about DKIM key selection still applies.