3 dot-qmail \- control the delivery of mail messages
7 program delivers each incoming message to your system mailbox,
8 .IR homedir\fB/Mailbox ,
11 is your home directory.
14 write the mail to a different file or directory,
15 forward it to another address,
16 distribute it to a mailing list,
17 or even execute programs,
18 all under your control.
24 file in your home directory.
27 contains one or more lines.
28 Each line is a delivery instruction.
30 follows each instruction in turn.
31 There are five types of delivery instructions:
32 (1) comment; (2) program; (3) forward; (4) mbox; (5) maildir.
35 A comment line begins with a number sign:
42 ignores the line. However,
43 .BR qmail-valid-addresses (8)
44 interprets some markers in comments. If the first line of a
46 file begins `#!' then the address (or addresses) controlled by the file
47 are considered invalid, and any attempt to send to them is refused by
49 (Note: This doesn't prevent local users sending mail directly. This
50 feature can therefore be used to experiment with mail rules before
51 allowing the entire Internet to break them.) If the first line of a
55 will consult a Userv service
57 to decide whether addresses matched by the extension
59 are valid. The service is passed many arguments, though the first two
60 are the most interesting. The first is the local-part tail (i.e., the
63 and the second is the envelope sender.
66 A program line begins with a vertical bar:
69 |preline /usr/ucb/vacation djb
73 takes the rest of the line as a command to supply to
77 for further information.
80 A forward line begins with an ampersand:
87 takes the rest of the line as a mail address;
90 to forward the message to that address.
91 The address must contain a fully qualified domain name;
92 it must not contain extra spaces, angle brackets, or comments:
95 # the following examples are WRONG
103 &me@new.job.com (New Address)
106 If the address begins with a letter or number,
107 you may leave out the ampersand:
117 line when forwarding messages.
122 line begins with a slash or dot,
123 and does not end with a slash:
126 /home/djb/Mailbox.sos
130 takes the entire line as a filename.
131 It appends the mail message to that file,
134 file locking if possible.
136 stores the mail message in
138 format, as described in
143 anyone who can read a file can
148 Do not deliver mail to a publicly accessible file!
152 is able to lock the file, but has trouble writing to it
153 (because, for example, the disk is full),
154 it will truncate the file back to its original length.
155 However, it cannot prevent mailbox corruption if the system
156 crashes during delivery.
161 line begins with a slash or dot,
162 and ends with a slash:
169 takes the entire line as the name of a directory in
172 It reliably stores the incoming message in that directory.
180 line begins with a less-than-sign `<'. The remainder of the line is set
181 as the new envelope sender for any forwarding done through this file.
186 line begins with an exclamation mark `!'. If the remainder of the line
189 then the environment variable
193 for the following program deliveries. If there is no equals sign, the
194 named environment variable is deleted.
198 has the execute bit set,
199 it must not contain any
209 it will stop and indicate a temporary failure.
213 is completely empty (0 bytes long), or does not exist,
217 instructions set by your system administrator;
224 appends the mail message to
231 may contain extra spaces and tabs at the end of a line.
232 Blank lines are allowed, but not for the first line of
237 is world-writable or group-writable,
239 stops and indicates a temporary failure.
240 .SH "SAFE QMAIL EDITING"
241 Incoming messages can arrive at any moment.
242 If you want to safely edit your
244 file, first set the sticky bit on your home directory:
251 will temporarily defer delivery of any message to you
252 if your home directory is sticky
253 (or group-writable or other-writable,
254 which should never happen).
262 It's a good idea to test your new
267 qmail-local -n $USER ~ $USER '' '' '' '' ./Mailbox
269 .SH "EXTENSION ADDRESSES"
273 you control all local addresses of the form
274 .IR user\fBBREAK\fIanything ,
275 as well as the address
280 is your account name.
282 .I user\fBBREAK\fIanything
283 is controlled by the file
284 .IR homedir/\fB.qmail\-\fIanything .
285 (These rules may be changed by the system administrator;
287 .BR qmail-users (5).)
291 user controls all other addresses.
294 is controlled by the file
295 .IR homedir/\fB.qmail\-\fIlocal ,
302 In the following description,
304 is handling a message addressed to
310 Here is what it does.
318 instructions set by your system administrator.
324 will try some default
336 .BR .qmail-foo-default ,
339 If none of these exist,
341 will bounce the message.
342 (Exception: for the basic
356 with colons before checking
360 converts any uppercase letters in
366 forwards a message as instructed in
369 .BR .qmail-default ),
371 .B .qmail\-\fIext\fB-owner\fP
375 .I local\fB-owner@\fIdomain
376 as the envelope sender for the forwarded message.
377 Otherwise it retains the envelope sender of the original message.
380 always retains the original envelope sender
381 if it is the empty address or
383 i.e., if this is a bounce message.
387 .B variable envelope return paths
390 .B .qmail\-\fIext\fB-owner\fP
392 .B .qmail\-\fIext\fB-owner-default\fP
394 .I local\fB\-owner\-@\fIdomain\fB-@[]
395 as the envelope sender.
396 This will cause a recipient
397 .I recip\fB@\fIreciphost
398 to see an envelope sender of
399 .IR local\fB\-owner\-\fIrecip\fB=\fIreciphost\fB@\fIdomain .
401 If a delivery instruction fails,
403 stops immediately and reports failure.
405 handles forwarding after all other instructions,
406 so any error in another type of delivery will prevent all forwarding.
408 If a program returns exit code 99,
410 ignores all succeeding lines in
412 but it still pays attention to previous forward lines.
414 To set up independent instructions,
415 where a temporary or permanent failure in one instruction
416 does not affect the others,
417 move each instruction into a separate
419 file, and set up a central
421 file that forwards to all of the
422 .BR .qmail\-\fIext s.
425 can handle any number of forward lines simultaneously.