M README.md → README.md

@@ -3,22 +3,34 @@
 Listfix
 =======
 
-Listfix is a simple email list manager built with python for the postfix email
-server. It is intended to be simple to set up and administer. Listfix simply 
-receives email from postfix that is addressesed to a configured email list and
-replicates that email to all list recipients in it's database.
+Listfix is a simple email list manager for the postfix email server. It is
+designed with minimal features to be quick to set up, easy to integrate with
+postfix, and simple to create and administer lists.
 
-Most of the origninal email headers are stripped and replaced such that the
-replicated email is properly addressed as having been generated and sent by your
-email server, with the "From" field having the same user@domain as the email
-list itself. This is necessary to avoid the email being flagged as spam.
+Listfix allows you to create and manage multiple email lists through a simple
+command line interface (CLI). Integration with the postfix email server is
+generally only a matter of a couple simple configuration changes (this assumes
+you already have postfix installed and configured to send and receive email).
 
-Listfix allows you to create multiple email lists, add and remove recipients,
-and review the contents of lists through a simple command line interface (CLI).
-As an alternative to the CLI, the Listfix database is stored in json format
-allowing for simple viewing and manipulating of the list data via your preferred
-text editor. This json format also allows for easy plugin capaibility via
-custom written scripts or other software.
+When integrated, postfix will hand off emails to listfix that are addressed to
+email addresses that you have configured for listfix. Listfix will then
+replicate the email by modifying the headers (most importantly, the 'To' header)
+and resubmitting a copy back to postfix for each recipient stored in its
+database. Postfix will then deliver the email to each recipient.
+
+Listfix does some rewriting of the headers before it replicates an email to the
+recipients. Since it is creating a new email, most of the original email
+headers are no longer useful and are stripped away. Some of the original headers
+are kept, such as 'To', 'Cc', 'Subject', and certain content related headers
+that are required to maintain the integrity of a multipart email body. The
+'From' header is readdresses so that the it contains the same user@domain as the
+email list itself. This is necessary to avoid emails being flagged as spam, 
+because it is almost a certainty that your email server is not listed as an
+official sender for the domain name of the original 'From' address.
+
+Listfix uses a json database which allows for simple viewing and direct
+manipulation via your preferred text editor. This json format also allows for
+easy plugin compatibility via custom written scripts or other software.
 
 Table of Contents
 -----------------
@@ -144,12 +156,13 @@ virtual_alias_maps = hash:/etc/postfix/virtual
 ```
 
 Next add your email list(s) to the file (or resource) that if configured for
-virtual_alias_maps. Open this file and add a new line for each email list you
-want to manage via listfix. Each new line should consist of two parts. The first
+virtual_alias_maps. If it is configured similarly to the above example, Open
+this file and add a new line for each email list you want to manage via listfix.
+Each new line should consist of two parts separated by a space. The first
 part is the email address for the list. The second part is a unique id. You can
 make the unique id anything you want, but each list must have its own unique id
-and it must conform to system userid character standards. It also can not match
-any userid on the system. See the below example:
+and it must conform to system userid character requirements. It also can not
+match any userid on the system. See the below example:
 
 ```
 everyone@smith-family.com list-smith-family
@@ -167,8 +180,8 @@ #### Configure /etc/aliases
 
 Next you need to add an entry to the /etc/aliases file for each unique id you
 added to the postfix virtual_alias_maps file. Each entry should start with the
-unique id, followed by a colon and space, and the a command that pipes data
-to listfix. You should be sure to use the 'filter' command for listfix followed
+unique id, followed by a colon and space, and then a command that pipes data
+to listfix. Be sure to use the 'filter' command for listfix followed
 by the email address of the list that corresponds to the unique id. See the
 example below: