noted the new URL for git repository
[attachcheck] / README.rst
1 AttachCheck
2 =============
3
4 :Author: Benjamin Mako Hill <mako@atdot.cc>
5 :Date: Sun, 12 Apr 2009 17:51:04 -0400
6 :Copyright: GNU General Public License version 3
7
8 How many times have you said, "I've attached the file below," and then
9 failed to actually attach the file? It happens to even the best of us.
10
11 AtttachCheck is a program that seeks to end this forever. AttachCheck
12 looks through all outgoing mail. If it expects an attachment and doesn't
13 see one, it refuses to send it until you confirm that you really want to
14 send the message sans attachment. 
15
16 AttachCheck It was written in Benjamin Mako Hill. You can find the
17 latest version of this program, more information, and some of Mako's
18 sometime accidentally insightful or useful ideas at his eponymous
19 homepage at: http://mako.cc
20
21 The AttachCheck website with the latest version of the program is always
22 available here: http://mako.cc/projects/attachcheck/
23
24 The latest version of source code is kepted in a Git repository at
25 http://projects.mako.cc/source/?p=attachcheck and can be checked out or
26 branched with the command::
27
28   git clone git://projects.mako.cc/attachcheck
29
30 Prerequisites
31 --------------
32
33 * AttachCheck is written in Python. You will need to have Python
34   installed in our system.
35
36 * You will need to deliver mail to locally (i.e., not over SMTP to
37   another machine).
38
39 * You will need to be able to configure you mail client to deliver to a
40   differnet location on your system. 
41
42 If you use OutLook and Windows, I found a similar program for that
43 setup: http://www.danevans.co.uk/vba/
44
45
46 How AttachCheck Works
47 ----------------------
48
49 AttachCheck monitors outgoing mail for keywords. It expects attachment
50 if it finds a text-based attachment if it finds one of the following
51 words:
52
53 * Attach
54 * Attached
55 * Attaching
56 * Attachment
57
58 If you can think of other words (in any language) that are indicative of
59 attachments, please contact the author of the program so others can
60 benefit as well.
61
62 AttachCheck is basically just a wrapper for your mail transfer agent
63 (MTA). It takes mail on STDIN, checks it, and then passes it on to your
64 *real* MTA or exits with an error if there is no attachment and it
65 expects.
66
67 Sometimes you may talk about attachments when you don't include any.
68 AttachCheck will stop you in these cases but you'll need to
69 confirm/override it by hand. This can be one in one of two ways:
70
71 1. Adding the word "CONFIRM" in all capital letters in the beginning of
72    the subject line of your outgoing mail. AttachCheck will remove
73    the word when the mail is sent.
74
75 2. Adding a special header that like this: ``X-AttachCheck-Override:
76    Yes``
77
78
79 Enabling AttachCheck in Mutt
80 -----------------------------
81
82 AttachCheck was written for and tested with Mutt and it works great
83 under that client. I got AttachCheck working by adding the following two
84 lines to my muttrc file::
85
86  set sendmail='~/bin/attachcheck'
87  macro compose \e0 ':set editor="~/bin/attachcheck_add_override"<enter>e:set editor=vim<enter>'
88
89 This will set up the sendmail wrapper so that attachcheck is used and
90 then set up a macro bound to a key (in this case `META`-0) that will add
91 the override line into your mail with a single keystroke.
92
93 You'll of course want to customize these lines to include your editor
94 choice and to include the actual path of ``attachcheck`` and the
95 ``attachcheck_add_override``.
96
97 Copyright / Information
98 -------------------------
99
100 copyright (c) 2004-2009 Benjamin Mako Hill <mako@atdot.cc>
101
102   This program is free software: you can redistribute it and/or modify
103   it under the terms of the GNU General Public License as published by
104   the Free Software Foundation, either version 3 of the License, or (at
105   your option) any later version.
106
107   This program is distributed in the hope that it will be useful, but
108   WITHOUT ANY WARRANTY; without even the implied warranty of
109   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
110   General Public License for more details.
111
112   You should have received a copy of the GNU General Public License
113   along with this program.  If not, see <http://www.gnu.org/licenses/>.
114
115 On Debian systems, the complete text of the GNU General Public License
116 can be found in /usr/share/common-licenses/GPL. It is also distributed
117 in full with AttachCheck in the ``COPYING`` file.
118
119

Benjamin Mako Hill || Want to submit a patch?