1 files changed, 124 insertions, 0 deletions
diff --git a/README.org b/README.org
new file mode 100644
index 0000000..f7dc217
--- /dev/null
+++ b/README.org
@@ -0,0 +1,124 @@
+# -*- mode: org -*-
+
+Something like spamgourmet.
+
+* WHY THIS EXISTS
+Having a public email address is an invitation to spam. Private email
+addresses allow you to filter your spam based on how much you receive
+and from whom it came. Instead of giving your main email address to
+every web site you run across, you can give a private email address to
+each web site (e.g., "facebook@myspam.example.com" for Facebook). That
+way if you no longer want to receive email from a given sender, you
+can easily filter it out.
+
+Additionally, by having site-specific email addresses you can also
+tell when a breach of security happened. If I tell Home Depot my email
+address is home-depot@myspam.example.com and I start receiving spam
+from Nigeria on that address I know that Home Depot has had a security
+breach. I can use that to inform Home Depot, Twitter, my friends that
+there's been a breach, in addition to checking credit cards for
+possible fraudulent charges.
+
+In short, having private email addresses per organization allows you
+to keep tabs on your private life and help keep you more secure.
+
+It would be remiss to not mention spamgourmet.com, a wonderful service
+that was the inspiration for this code. I've been a happy spamgourmet
+user for many years, but unfortunately it has some problems this
+software attempts to address:
+
+1) spamgourmet.com and its various addresses are too well known. By
+   hosting this on your own domain you can prevent, for instance,
+   Facebook from filtering your email address.
+2) spamgourmet addresses are very long and hard to communicate over
+   the phone or when filling out forms at, say, a doctor's
+   office. This is attempting to provide much shorter addresses that
+   will raise fewer eyebrows and can be communicated more easily.
+
+* HOW IT WORKS
+Once the software is installed (see INSTALLATION, below), it will
+start receiving all email directed at it (such as by procmail or
+sieve), and it will examine the destination address (i.e., "To"
+header) to determine whether it should deliver the email to the final
+recipient or not.
+
+SpamCat relies on your MTA delivering mail from your spam domain to a
+real email address that can be used for IMAP/POP/etc. This can be
+accomplished in any number of ways based on your MTA/LMTP/LDA setup;
+an example for Postfix/Dovecot is below.
+
+When SpamCat receives a message it looks at the username (the
+left-hand of the "@" in an email address) to determine the
+sender. Thus, "foo@bar.com"'s sender is "foo".
+
+Once the sender is determined SpamCat will see how many messages are
+remaining for that sender, and if the sender has no remaining messages
+then the message is thrown away.
+
+If the sender has messages remaining then the message is delivered
+as-is with the exception that the Subject header shows how many
+messages are remaining and the total number of messages available
+(e.g., "Subject: XANAX FOR NIGERIA - [19/20]" shows that there are 20
+total messages from this sender, and there are 19 remaining).
+
+* RECOMMENDED USAGE
+1) Create your own spam-handling domain (e.g., "spam.example.com")
+2) Use private email addresses in that domain anywhere you're asked
+   for an email address (e.g., giving ShopRite an address of
+   "shoprite@spam.example.com")
+
+* PREREQUISITES
+1) Perl 5
+2) Email::Simple
+3) SQLite 3
+4) DBD::SQLite
+
+* INSTALLATION
+1) See INSTALL to install the library and spamcat executable.
+2) Once the spamcat executable is installed you'll need to add it to
+   your procmail, sieve, or some other similar device that writes
+   email to standard input and receives the transformed email on
+   standard output.
+3) You will also need to create a config file for spamcat (see
+   config/spamcat.conf for an example) somewhere that can be read by
+   spamcat.
+4) Make sure you pass in the spamcat.conf file to spamcat via the "-c"
+   argument (e.g., "spamcat -c /home/me/etc/spamcat.conf").
+
+* EXAMPLES
+** Postfix
+*** main.cf
+Postfix needs to know that the spam domain should be handled locally.
+
+#+begin_example
+  Virtual_mailbox_domains = spamcat.domain somewhere.else
+#+end_example
+
+*** virtual aliases table
+Make sure postfix can route the spam domain to the user who should
+receive it.
+
+#+begin_example
+  @spamcat.domain  hidden-address@somewhere.else
+#+end_example
+
+** Dovecot/Sieve
+The sieve file for the user which receives mail for the spam domain
+should pipe the email into spamcat, which will handle final delivery
+for the spam domain.
+
+#+begin_example
+  require ["fileinto", "envelope", "vnd.dovecot.filter"];
+
+  if address :contains "to" "@spamcat.domain" {
+    filter "spamcat" ["-c", "/path/to/spamcat.conf"];
+  }
+#+end_example
+
+** DNS
+The MX record for your spam domain should point to the MTA that hosts
+spamcat.
+
+#+begin_example
+  spamcat.domain MX 10 yourmta.domain.
+#+end_example