From f66cc5f73f1d8796646b3e1e036ef388609e0957 Mon Sep 17 00:00:00 2001
From: Martin Kamerbeek <martin@martintwee.oqapi.nl>
Date: Fri, 5 Nov 2010 11:28:34 +0100
Subject: [PATCH] Rewrite mail commands documentation.

---
 docs/mail_commands_setup.pod | 101 +++++++++++++++++++++++++++++++++++
 docs/postfix_configuration   |  17 ------
 2 files changed, 101 insertions(+), 17 deletions(-)
 create mode 100644 docs/mail_commands_setup.pod
 delete mode 100644 docs/postfix_configuration

diff --git a/docs/mail_commands_setup.pod b/docs/mail_commands_setup.pod
new file mode 100644
index 0000000..10e0e1f
--- /dev/null
+++ b/docs/mail_commands_setup.pod
@@ -0,0 +1,101 @@
+=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.
diff --git a/docs/postfix_configuration b/docs/postfix_configuration
deleted file mode 100644
index b6ee775..0000000
--- a/docs/postfix_configuration
+++ /dev/null
@@ -1,17 +0,0 @@
-Add to /etc/postfix/main.cf:
-    smtpd_reject_unlisted_recipient = no
-    transport_maps = regexp:/etc/postfix/wg_mailer_transport
-    wgml_destination_recipient_limit = 1
-
-Add to /etc/postfix/master.cf:
-    wgml      unix  -       n       n       -       -       pipe
-        flags=FR user=martin argv=/data/custom/webgui_newsletter/sbin/newsletter-transport.pl ${domain} ${user}
-
-
-Create /etc/postfix/wg_mailer_transport:
-    /^[a-zA-Z0-9]+-bounce@/         wgml:
-
-And run:
-    postmap /etc/postfix/wg_mailer_transport
-
-Finally restart postfix.