Aliases plugin

This plugin allows one to configure aliases that may perform an action or change the RCPT address in a number of ways. All aliases are specified in a JSON formatted configuration file, and must have at very least an action. Any syntax error found in the JSON format config file will stop the server from running.

IMPORTANT: this plugin must appear in config/plugins before other plugins that run on hook_rcpt

WARNING: DO NOT USE THIS PLUGIN WITH queue/smtp_proxy.

Configuration

  • aliases
    JSON formatted configuration file that must contain, at very least, a key to match against RCPT address, and a value that is an associative array with an "action" : "" key, value pair. An example:
      { "test1" : { "action" : "drop" } }

    In the above example the "test1" alias will drop any message that matches test1, or test1-* or test1+* (wildcard '-' or '+', see below). Actions may in turn have 0 or more options listed with them like so:
      { "test3" : { "action" : "alias", "to" : "test3-works" } }

    In the above example the "test3" alias has an action of "alias", and a required "to" field. If this "to" field were missing the alias would fail to run, and an error would be printed in the logs.
    Now aliases of 'user', '@host' and 'user@host' possible:
      { "demo" : { "action" : "drop" } }
  or
  { "@example.com" : { "action" : "drop" } } 
  or
  { "demo@example.com" : { "action" : "drop" } }

    Aliases may also be exploded to multiple recipients:
      { "sales@example.com": { "action": "alias", "to": ["alice@example.com", "bob@example.com"] } }
    • wildcard notation
      In an effort to match some of the functionality of other alias parsers we've allowed wildcard matching of the alias against the right most string of a RCPT address. The characters '-' and '+' are commonly used for subaddressing and this plugin has built-in support to alias the "user" part of the email address.
      That is, if our address were test2-testing@example.com (or test2+testing@example.com), the below alias would match:
        { "test2" : { "action" : "drop" } }

      The larger, and more specific alias, should always match first when using wildcard '-' notation. So if the above RCPT were put up against this alias config, it would not drop, but rather map to another address:
        {
      "test2" : { "action" : "drop" },
      "test2-testing" : { "action" : "alias", "to" : "test@foo.com" }
  }
    • chaining and circuits
      In short, we do not allow chaining of aliases at this time. As a side-effect, we enjoy protections against alias circuits.
    • optional one line formatting
      Any valid JSON will due, however, please consider keeping each alias on its own line so that others that wish to grep the aliases file have an easier time finding the full configuration for an alias.
    • nondeterministic duplicate matches
      This plugin was written with speed in mind. That means every lookup hashes into the alias file for its match. While the act of doing so is fast, it does mean that any duplicate alias entries will match nondeterministically. That is, we cannot predict what will happen here:
        {
      "coinflip" : { "action" : "alias", "to" : "heads@coin.com" },
      "coinflip" : { "action" : "alias", "to" : "tails@coin.com" }
  }

      Truth be told, one result will likely always be chosen over the other, so this is not exactly a coinflip. We simply cannot say what the language implementation will do here, it could change tomorrow.
  • action (required)
    The following is a list of supported actions, and the options they require.
    • drop
      This action simply drops a message, while pretending everything was okay to the sender. This acts much like an alias to /dev/null in other servers.
    • alias
      This action will map the alias key to the address specified in the "to" option. A note about matching in addition to the note about wildcard '-' above. When we match an alias, we store the hostname of the match for a shortcut substitution syntax later.
      • to (required)
        This option is the full address, or local part at matched hostname that the RCPT address will be re-written to. For an example of an alias to a full address consider the following:
          { "test5" : { "action" : "alias", "to" : "test5@foo.com" } }

        This will map RCPT matches for "test5" to "test5-works@foo.com". This would map "test5@somedomain.com" to "test5-works@foo.com" every time. Now compare this notation with its shortcut counterpart, best used when the "to" address is at the same domain as the match:
          { "test4" : { "action" : "alias", "to" : "test4" } }

        Clearly, this notation is more compact, but what does it do. Well, mail to "test4-foo@anydomain.com" will map to "test4@anydomain.com". One can see the clear benefit of using this notation with lots of aliases on a single domain that map to other local parts at the same domain.

Example Configuration

{ "test1" : { "action" : "drop" }, "test2" : { "action" : "drop" }, "test3" : { "action" : "alias", "to" : "test3-works" }, "test4" : { "action" : "alias", "to" : "test4" }, "test5" : { "action" : "alias", "to" : "test5-works@success.com" }, "test6" : { "action" : "alias", "to" : "test6-works@success.com" } }

Edit this page on GitHub
Table of Contents