=head1 Configuring WebGUI mail commands

This document discusses the steps required to tie WebGUI mal command into
postfix.

=head2 Setting up WebGUI

The mappings between To adress in the incoming emails and WebGUI instances is
defined in /data/WebGUI/etc/mailing_dispatch.config. This is a JSON file
containing a hash with domain to instance config file mappings:

    {
        "mailing.domain1.com" : "www_domain1_com.conf",
        "newsletter.foo.com"  : "www_foo_com.conf"
    }

Note that any domain can be tied to any config file: domains don't have to
match. The only requirement is that the server can receive mail on the given
domain. Eg. the following is a valid mapping

    {
        "newsletter.bar.com"  : "www_xyzzy_com.conf"
    }

It is also possible to map multiple domains to a single config file, eg.

    {
        "mailing.example.com" : "example_com.conf",
        "mailing.foobar.org"  : "example_com.conf"
    }

However it is not allowed to map a single domain to multiple config files. If
you do the instance that is used, is not defined. Eg. the following is NOT
allowed.

    {
        "mailing.example.com" : "example_com.conf",
        "mailing.example.com" : "foobar_org.conf"
    }


=head2 Setting up Postfix

The newsletter-transport.pl script in the webgui_newsletter sbin directory
acts as a bridge between postfix and WebGUI. It is intended to be invoked
by postfix's pipe command.

=head3 Configuring master.cf

We need a  queue that processes mail intended for WebGUI. To do so add the
following to /etc/postfix/master.cf:

    wgml      unix  -       n       n       -       -       pipe
        flags=FR user=webgui argv=/data/custom/webgui_newsletter/sbin/newsletter-transport.pl \
        --domain=${domain} --user=${user} --sender=${sender} --senderIp=${client_address}

This creates a queue called wgml that pipes all mail in it through the
newsletter-transport.pl script. Make sure that the user parameter is set correctly and argv
contains the full path to the newsletter-transport.pl script.


=head3 Setup a transport map

In order to determine which emails should go to the wgml queue, create a
mapping in /etc/postfix/wg_mailer_transport. There are more ways to do this.

If you use a dedicated maildomain used solely for receiving WebGUI mail
commands add a line like the following for each mail domain in your
/date/WebGUI/etc/mailing_dispatch.config:

    /@mailing.foo.com$/             wgml:
    /@newsletter.example.com$/      wgml:

If you use a domain that is not solely dedicated to receiving WebGUI mail
commands, you can match on individual commands:

    /^[a-zA-Z0-9_-]+-bounce@/         wgml:
    /^[a-zA-Z0-9_-]+-subscribe@/      wgml:


Afterwards complile the mapping into a postfix lookup table

    postmap /etc/postfix/wg_mailer_transport

You have to do this everytime you change the mapping.

=head3 Configuring main.cf

Now we need to tell postfix to use the mapping, and how to use the wgml
queue. To do this add the following to /etc/postfix/main.cf: 

    smtpd_reject_unlisted_recipient = no
    transport_maps = regexp:/etc/postfix/wg_mailer_transport
    wgml_destination_recipient_limit = 1

Make sure you add the domains in your mailing_dispatch.config to the
mydestination directlive in main.cf:

    mydestination = mailing.foo.com, newsletter.example.org, some.other.domain

Finally restart postfix.