1MAILDROPFILTER(7) Double Precision, Inc. MAILDROPFILTER(7)
2
3
4
6 maildropfilter - maildrop's filtering language
7
9 /etc/maildroprc, $HOME/.mailfilter, $HOME/.mailfilters/*, and
10 friends...
11
13 This manual page describes the language used by maildrop to filter
14 E-mail messages. The mail filtering instructions are read from a file.
15 The language is loosely structured, it is based on pattern matching.
16 The language has a distinct lexical and syntactical structure, very
17 similar to Perl's, but it is important to note that it is not Perl, and
18 is very different from Perl, in certain cases.
19
20 If the filtering instructions do not exist, maildrop delivers the
21 message to the default mailbox without doing any additional processing,
22 making it indistinguishable from the usual mail delivery agent.
23
24 It is important to note that maildrop reads and parses the filter file
25 before doing anything. If there are any errors maildrop prints an error
26 message, and terminates with the exit code set to EX_TEMPFAIL. A
27 compliant mail transport agent should re-queue the message for a later
28 delivery attempt. Hopefully, most simple syntax errors will not cause
29 mail to be bounced back if the error is caught and fixed quickly.
30
31 Environment
32 maildrop uses variables to access and manipulate messages. Variables
33 are arbitrary text accessed by referring to the name of the variable,
34 such as HOME, or DEFAULT. Text is placed into a variable by using an
35 assignment statement, such as:
36
37 FILE="IN.junk"
38
39
40 This statement puts the text "IN.junk" (without the quotes) into a
41 variable whose name is FILE. Later, the contents of a variable are
42 accessed by using the $ symbol and the name for the variable. For
43 example:
44
45 to $FILE
46
47
48 This will deliver the current message to the mailbox file (or a maildir
49 directory) named "IN.junk".
50
51 maildrop initially creates variables from the environment variables of
52 the operating system, UNLESS maildrop runs in delivery mode. Each
53 operating system environment variable becomes a maildrop variable. When
54 running in delivery mode, maildrop does not import the environment for
55 security reasons, except for the environment variables that define the
56 process locale (LANG, LANGUAGE, and LC_*), which are still imported.
57
58 In all cases maildrop resets the following variables to their default
59 values: HOME, DEFAULT, SHELL, PATH, LOCKEXT, LOCKREFRESH, LOCKSLEEP,
60 LOCKTIMEOUT, MAILDIRQUOTA, SENDMAIL and LOGNAME.
61
62 There's one exception to this rule which applies to the version of
63 maildrop that comes with the Courier mail server[1]. The following does
64 not apply to the standalone version of maildrop: when running in
65 delivery mode, if the -d flag was not used, or if it specifies the same
66 userid as the one that's running maildrop: the following variables are
67 automatically imported from the environment: HOME, SHELL, LOGNAME and
68 MAILDIRQUOTA. These environment variables are initialized by the
69 Courier mail server prior to running maildrop. Additionally, the
70 initial value for the DEFAULT maildrop variable is imported from the
71 MAILDROPDEFAULT environment variable. This is because the Courier mail
72 server overloads the DEFAULT environment variable to store the
73 defaulted portion of the local mailbox address. See the
74 dot-courier(5)[2] man page in the Courier mail server distribution. You
75 can get the Courier mail server's DEFAULT value by using the import
76 command. Note, however, that this will clobber the old contents of
77 DEFAULT, which is probably not what you want. The right way to do this
78 would be something like this:
79
80 SAVEDEFAULT=$DEFAULT
81 import DEFAULT
82 LOCALDEFAULT=$DEFAULT
83 DEFAULT=$SAVEDEFAULT
84
85
86 All internal variables are exported back as environment variables when
87 maildrop runs an external command. Changes to internal variables, made
88 by the filter file, are reflected in the exported environment.
89
90 Lexical structure
91 Most whitespace is generally ignored. The # character introduces a
92 comment running to the end of the line, which is also ignored. Unlike
93 other mail filters, maildrop parses the filter file before taking any
94 action with the message. If there are syntax errors in the file,
95 maildrop displays an error message, and returns EX_TEMPFAIL. That
96 should cause the mail message to remain in the queue, and, hopefully
97 allow the problem to be corrected, without bouncing any mail.
98
99 Note
100 In maildrop, the end of line is a lexical token. In order to
101 continue a long statement on the next line, terminate the line with
102 a backslash character.
103
104 Literal text
105 Literal text in the maildrop filtering language is surrounded by either
106 single or double quotes. In order to enter a single quote into a text
107 literal surrounded by single quotes, or a double quote into a literal
108 surrounded by double quotes, prefix it with a backslash character. Use
109 two backslash characters characters to enter one backslash character in
110 the text literal.
111
112 Note
113 A backslash followed by either a backslash, or a matching quote, is
114 the only situation where the backslash character is actually
115 removed, leaving only the following character in the actual text
116 literal. If a backslash character is followed by any other
117 character, the backslash is NOT removed.
118
119 Multiple text literals in a row are automatically concatenated, even if
120 they use different quotes. For example:
121
122 FOOBAR="Foo"'bar'
123
124
125 This sets the variable FOOBAR to the text "Foobar".
126
127 Variable substitution
128 Variable substitution is performed on text literals that's surrounded
129 by double quotation marks. The "$" character, followed by a variable
130 name, is replaced by that variable's contents.
131
132 MAILBOX="$HOME/Mailbox"
133
134
135 This sets the variable MAILBOX to the contents of the variable HOME
136 followed by "/Mailbox". Variable names must begin with an uppercase
137 letter, a lowercase letter, or an underscore. Following that, all
138 letters, digits, and underscores are taken as a variable name, and its
139 contents replace the $ sign, and the variable name. It is possible to
140 access variables whose name includes other characters, by using braces
141 as follows:
142
143 MAILBOX="${HOME-WORD}/Mailbox"
144
145
146 Inserts the contents of the HOME-WORD variable. If the variable does
147 not exist, the empty text literal is used to replace the variable name.
148 It is not possible to access variables whose names include the }
149 character.
150
151 If the $ character is not followed by a left brace, letter, or an
152 underscore, the $ character remains unmolested in the text literal. A
153 backslash followed by the $ character results in a $ character in the
154 text literal, without doing any variable substitution.
155
156 Variable substitution is not done in text literals which are surrounded
157 by single quotes (apostrophes).
158
159 Command line arguments
160 maildrop initializes special variables: $1, $2, and so on, with
161 additional parameters specified on the maildrop command line. A filter
162 file may use those variables just like any other variables.
163
164 Predefined variables
165 The following variables are automatically defined by maildrop. The
166 default values for the following variables may be changed by the system
167 administrator. For security reasons, the values of the following
168 variables are always reset to their default values, and are never
169 imported from the environment:
170
171 DEFAULT
172 The default mailbox to deliver the message to. If the filter file
173 does not indicate a mailbox to deliver this message to, the message
174 is delivered to this mailbox. The default mailbox is defined by the
175 system administrator.
176
177 FROM
178 Message envelope sender. This is usually the same address as what
179 appears in the From: header, but may not be. This information may
180 or may not be available to maildrop on your system. The message
181 envelope sender is usually specified with the -f option to
182 maildrop. If the -f option is not given, maildrop looks for the
183 Return-Path: header in the message. As the last resort, FROM
184 defaults to “MAILER-DAEMON”. Note that FROM may be empty - the
185 message envelope sender is empty for bounce messages.
186
187 HOME
188 Home directory of the user running maildrop.
189
190 HOSTNAME
191 Network name of the machine running maildrop. Obtained from
192 gethostname(3).
193
194 LOCKEXT
195 Extension for dot-lock files (default: .lock).
196
197 LOCKREFRESH
198 Refresh interval, in seconds, for dot-locks (default: 15). When
199 maildrop dot-locks a mailbox, maildrop tries to refresh the lock
200 periodically in order to keep other programs from removing a stale
201 dot-lock. This is only required if a dot-lock exists for a
202 prolonged period of time, which should be discouraged anyway.
203
204 LOCKSLEEP
205 Number of seconds to wait to try again to create a dot-lock file,
206 if one already exists (default: 5).
207
208 LOCKTIMEOUT
209 Number of seconds to wait before removing a stale dot-lock file
210 (default: 60). If a dot-lock file still exists after LOCKTIMEOUT
211 seconds, maildrop assumes that the process holding the lock no
212 longer exists, and the dot-lock file can be safely removed. After
213 removing the dot-lock file, maildrop waits LOCKSLEEP seconds before
214 trying to create its own dot-lock file, in order to avoid a race
215 condition with another process which is also trying to remove the
216 same stale dot-lock, at the same time.
217
218 LOGNAME
219 Name of the user to who the message is being delivered.
220
221 MAILDROP_OLD_REGEXP
222 Revert to using the old legacy pattern matching engine. Versions of
223 maildrop prior to version 2.0 (included in the Courier mail server
224 0.51, and earlier), used a built-in pattern matching engine,
225 instead of using the PCRE library (see the section called
226 “Patterns”). maildrop 1.x used a different syntax for patterns,
227 which is no longer described in this manual page. The old pattern
228 matching engine is still available, by setting MAILDROP_OLD_REGEXP
229 to “1”. Setting this variable will use the legacy pattern matching
230 engine for the rest of the maildrop recipe file.
231
232 The pattern matching engine will be removed completely in a future
233 version of maildrop. This setting provides for a transitional
234 period of converting old recipes. MAILDROP_OLD_REGEXP can be set
235 to “1” in the global maildroprc file, then reset to “0” in each
236 individual maildrop recipe file, after it gets converted to the new
237 syntax.
238
239 MAILFILTER
240 This is the name of the original filter file that was given to
241 maildrop on the command line. This is mostly useful to -default
242 filter files, it allows them to obtain the value of the -M
243 option[3] specified on the command line.
244
245 PATH
246 Command execution path. maildrop resets PATH to the system default
247 (usually /bin:/usr/bin:/usr/local/bin).
248
249 SENDMAIL
250 The mail delivery agent. When maildrop is instructed to deliver the
251 message to a mailbox whose name begins with the ! character, this
252 is interpreted as a request to forward the message. The SENDMAIL
253 command is executed to forward the message.
254
255 SHELL
256 The login shell. The shell is used to execute all commands invoked
257 by maildrop.
258
259 VERBOSE
260 Current Debug level (default: 0). Setting VERBOSE to progressive
261 higher values, between 1 and 9, produces debugging output on
262 standard error. maildrop ignores the VERBOSE variable in delivery
263 mode (in order not to confuse the mail transport agent).
264
265 UMASK
266 The file creation mode mask, in octal. The default setting of 077
267 creates mailboxes that are readable and writable by the owner only.
268 Use 007 to create mailboxes that are readable/writable by both
269 owner and the group. Use 037 to create mailboxes that are readable
270 by both owner and group, but writable by owner only. Permissions on
271 existing mailboxes are not changed, this setting affects only new
272 mailboxes. When delivering to maildirs this setting sets the
273 permissions on new messages only. Access permissions on messages in
274 maildirs are also affected by the permissions on the maildir
275 directories.
276
277 Other special variables
278 The following variables are automatically used by maildrop when the
279 filter file is being processed:
280
281 EXITCODE
282 Return code for maildrop. When maildrop successfully delivers a
283 message, it terminates with this exit code, which defaults to 0.
284 When the to or the cc command is used to deliver the message to an
285 external process, via a pipe, maildrop will set this variable to
286 the exit code of the external process. Since maildrop immediately
287 terminates after completing the to command this means that
288 maildrop's exit code will be the exit code of the external process.
289 If the to command does not deliver the message to a process you
290 must set EXITCODE before the to command, since maildrop terminates
291 immediately after finishing the delivery.
292
293 FLAGS
294 The FLAGS variable is used only when delivering a message to a
295 maildir, and may contain only the following letters: “D”, “F”, “R”,
296 and “S”. They may appear in any order. When the message gets
297 delivered to the maildir, the message will be marked with a draft,
298 flag, replied, or seen, attribute, correspondingly.
299
300 FLAGS must be set before the message is delivered to a maildir. The
301 contents of FLAGS are ignored, when delivering on an mbox folder.
302
303 KEYWORDS
304 The KEYWORDS variable is used only when delivering a message to a
305 maildir, and implements the optional IMAP keyword extension as
306 implemented in the Courier IMAP server[1]. It may be optionally
307 initialized to contain a comma-separate list of keywords. The to,
308 or the cc command, delivers the message to the maildir normally,
309 but also associated the list of keywords in KEYWORDS with the newly
310 delivered message.
311
312 KEYWORDS must be set before the message is delivered to a maildir.
313 The contents of KEYWORDS are ignored, when delivering on an mbox
314 folder.
315
316 LINES
317 Number of lines in the current message. Note that this may be an
318 approximation. It may or may not take into account the -A option.
319 Use this as criteria for filtering, nothing more.
320
321 MAILDIRQUOTA
322 Set this variable in order to manually enforce a maximum size on
323 ANY maildir where the message is delivered. This is an optional
324 feature that must be enabled by the system administrator, see
325 maildirquota(8)[4] for more information.
326
327 RETURNCODE
328 This variable is set when maildrop runs the system[5] command,
329 xfilter[6] command, or a command that's specified within a pair of
330 backtick characters ( command substitution ). The RETURNCODE
331 variable will be set to the exit code of the command, after it
332 completes.
333
334 SIZE
335 Number of bytes in the message. This may or may not include the -A
336 option. Use this as a criteria for filtering, nothing more.
337
338 Unquoted text
339 All text strings in filter files should be in single, or double quotes.
340 However, for convenience sake, quotes can be omitted under certain
341 circumstances.
342
343 Text that includes ONLY letters, digits, and the following characters:
344 _-.:/${}@ may appear without quotes. Note that this does not allow
345 spaces, or backslashes to be entered, however the text is still
346 variable-substituted, and the substituted text may contain other
347 characters.
348
349 Also, note that patterns (see below) begin with the slash character.
350 Normally, anything that begins with the slash is interpreted as a
351 pattern. However, text immediately after “VARIABLE=” is interpreted as
352 a string even if it begins with a slash. This is why something like:
353
354 MAILDIR=/var/mail
355
356
357 works as expected. Using quotes, though, is highly recommended. You
358 must use quotes to set a variable to a lone slash, because an unquoted
359 slash is interpreted as a division sign.
360
361 Long double or singly-quoted text can be broken across multiple lines
362 by ending the line with a lone backslash character, like this:
363
364 TEXT="This is a long \
365 text string"
366
367
368 The backslash, the newline, and all leading whitespace on the next line
369 is removed, resulting in "This is a long text string".
370
371 Command substitution
372 Text enclosed in back-tick characters is interpreted as a shell
373 command. The shell command is executed as a child process by maildrop.
374 Its output is used in place of the command. For example:
375
376 DIR=`ls`
377
378
379 places the names of the files in the current directory into the DIR
380 variable.
381
382 The output of the command will have all newline characters replaced by
383 spaces, and leading and trailing spaces will be stripped (multiple
384 spaces are not removed, though). Also, the contents of the message
385 being delivered is made available to the command on standard input.
386
387 Patterns
388 The pattern syntax in maildrop is similar to the grep command's syntax,
389 with some minor differences. A pattern takes the following form in the
390 filter file:
391
392 /pattern/:options
393
394
395 pattern specifies the text to look for in the message, in the UTF-8
396 codeset. pattern must not begin with a space, otherwise the leading
397 slash will then be interpreted as a division sign. If you must search
398 for text that starts with a space, use something like "/[ ] ... /".
399
400 The general syntax of maildrop's patterns is described in the
401 pcrepattern(3) manual page, with certain exceptions noted below.
402 maildrop uses the PCRE[7] library to implement pattern matching. Not
403 all features in PCRE are available in maildrop, and the “options” part,
404 which follows the pattern specification, changes the pattern matching
405 further. Consult the pcrepattern(3) manual page for more information,
406 but note the following exceptions:
407
408 • Internal options settings are not supported (but see the “D”
409 maildrop option, below). Do not include option settings in the
410 pattern, doing so will lead to undefined results.
411
412 • Named subpatterns are not implemented. Numbered subpatterns are
413 implemented, see the section called “Pattern Match Results”, below.
414
415 • The search pattern gets executed not against the raw message text,
416 but the message transcoded into a canonical UTF-8-based format.
417 This process involves transcoding any non-UTF-8 message content
418 into UTF-8. Additionally, message headers get converted into a
419 canonical format before the search pattern gets executed.
420
421 For structured headers with email addresses, the process involves
422 removing extraneous punctuation, or adding missing ones (in
423 situations where a missing punctuation character can be deduced).
424 Additionally certain pre-RFC822 obsolete header formats get
425 converted to canonical form.
426
427 This means that header search patterns that include punctuation
428 character may appear not to work against obviously-matching message
429 text. Use “reformime -u <message.txt”, with message.txt containing
430 the sample message, to see exactly the actual text that gets
431 searched by patterns.
432
433 Pattern options
434 Following /pattern/, there may be an optional colon, followed by one.
435 or more options. The following options may be specified in any order:
436
437 h
438 Match this pattern in the message's header, and the header of any
439 attachments in the message.
440
441 H
442 Match this pattern in the message's main header. Do not match this
443 pattern in the headers of the message's attachments.
444
445 b
446 Match this pattern against the message body.
447
448 D
449 This is a case sensitive match. Normally the patterns match either
450 uppercase or lowercase text. /john/ will match "John", "john", or
451 "JOHN". Specify the D option for a case-sensitive search: lowercase
452 letters in the pattern must match lowercase letters in the message;
453 ditto for uppercase.
454
455 If neither 'h', 'H', or 'b' is specified, 'h' is the default, matching
456 the pattern in the message's header, and all attachments' headers.
457 Specifying the 'b' option causes the pattern to be matched against the
458 message body. Specifying 'b' and 'h' causes the pattern to be matched
459 against the entire message.
460
461 Normally, each line in the message gets matched against the pattern
462 individually. When applying patterns to a header, multi-line headers
463 (headers split on several lines by beginning each continuation line
464 with whitespace) are silently combined into a single line, before the
465 pattern is applied.
466
467 MIME encoding
468 The pattern must be a valid text string in the UTF-8 codeset, and
469 maildrop should handle messages that use MIME encodings in other known
470 character sets. Options that specify a message header search result in
471 maildrop searching the initial message headers, and any headers of
472 additional MIME sections, in a multipart MIME message. Options that
473 specify a message body search will search through all "text" MIME
474 content.
475
476 For a MIME search to succeed, the message must be a well-formed MIME
477 message (with a Mime-Version: 1.0 header).
478
479 Weighted scoring
480 Patterns are evaluated by maildrop as any other numerical expression.
481 If a pattern is found, maildrop's filter interprets the results of the
482 pattern match as number 1, or true, for filtering purposes. If a
483 pattern is not found the results of the pattern search is zero. Once a
484 pattern is found, the search stops. Second, and subsequent occurrences
485 of the same pattern are NOT searched for.
486
487 maildrop can also do weighted scoring. In weighted scoring, multiple
488 occurrences of the same pattern are used to calculate a numerical
489 score.
490
491 To use a weighted search, specify the pattern as follows:
492
493 /pattern/:options,xxx,yyy
494
495
496 where xxx and yyy are two numbers. yyy is optional -- it will default
497 to 1, if missing.
498
499 The first occurrence of the pattern is evaluated as xxx. The second
500 occurrence of the pattern is evaluated as xxx*yyy, the third as
501 xxx*yyy*yyy, etc... All occurrences of the pattern are added up to
502 calculate the final score.
503
504 Note
505 maildrop does not recognize multiple occurrences of the same
506 pattern in the same line. Multiple occurences of the same pattern
507 in one line count as one occurence.
508
509 Pattern Match Results
510 After a pattern is successfully matched, the actual text that is
511 matched is placed in the MATCH variable. For example:
512
513 /^From:.*/
514
515
516 matches a line of the form:
517
518 From: postmaster@localhost
519
520
521 Here the variable MATCH will be set to "From: postmaster@localhost",
522 which can be used in subsequent statements.
523
524 If the pattern contains subpatterns, the portions of the text that
525 match the first subpattern is placed in the MATCH1 variable. The second
526 subpattern, if any, is placed in MATCH2, and so on:
527
528 /^From:\s+(.*)@(.*)/
529
530
531 matched against the same line will set MATCH to “From:
532 postmaster@localhost”, MATCH1 to “postmaster”, and MATCH2 to
533 “localhost”. Of course, in real world the “From:” header is usually
534 much more complicated, and can't be handled that easily. This is just
535 an illustrative example.
536
537 Note
538 Subpatterns are not processed in the foreach statement.
539
540 Note
541 The contents of all MATCH variables use UTF-8 encoding. As
542 explained in the section called “Patterns” the message gets
543 transcoded into a canonical UTF-8 format, replacing MIME-encoded
544 headers with their UTF-8 equivalent. Consequently, MATCH variables
545 that represent matched text are in UTF-8. For example:
546
547 if (/^Subject: *(.*)/)
548
549 This sets MATCH to what's in the “Subject” header, which could
550 possibly use MIME-encoding, for example: “Subject:
551 =?UTF-8?B?SMOzbGEh?=”. The resulting MATCH shows “Hóla!”.
552
553 Conversion of maildrop 1.x patterns to 2.0
554 Although the new PCRE-based pattern matching code in maildrop is
555 completely different from the built-in pattern matching code in
556 maildrop 1.x, very few changes will be required to convert recipes to
557 the new syntax. The only major differences are:
558
559 • The subexpression format has changed. Any pattern that uses
560 subexpression needs to be converted. Additionally, references to
561 MATCH2 must be replaced with MATCH1, MATCH3 to MATCH2, and so on.
562 References to plain old MATCH will remain the same.
563
564 • The “w” pattern option is no longer possible, with PCRE. The very
565 few recipes that use this option, if any actually exist, will have
566 to be rewritten in some other fashion.
567
568 Expressions
569 Although maildrop evaluates expressions numerically, results of
570 expressions are stored as text literals. When necessary, text literals
571 are converted to numbers, then the results of a mathematical operation
572 is converted back into a text literal.
573
574 Operators
575 The following operators carry their usual meaning, and are listed
576 in order from lowest precedence, to the highest:
577
578
579 ||
580 &&
581 < <= > >= == != lt le gt ge eq ne
582 |
583 &
584 + -
585 * /
586 =~ /pattern/
587 /pattern/ ! ~ function()
588
589
590 Variable assignment
591 VARIABLE=expression
592
593
594 Assigns the result of the expression to VARIABLE (note no leading $
595 in front of variable).
596
597 Note
598 If VARIABLE is NOT surrounded by quotes, then it may contain
599 only letters, numbers, underscores, dashes, and a selected few
600 other characters. In order to initialize a variable whose name
601 contains non-standard punctuation marks, surround the name of
602 the variable with quotes.
603
604 cc - deliver a copy of the message
605 cc expression
606
607
608 The cc statement is very similar to the to statement, except that
609 after delivering the message maildrop continues to process the
610 filter file, unlike the to statement which immediately terminates
611 maildrop after the delivery is complete. Essentially, the message
612 is carbon copied to the given mailbox, and may be delivered again
613 to another mailbox by another cc or to statement.
614
615 See the to statement[8] for more details. When cc is used to
616 deliver a message to a process maildrop will set the EXITCODE
617 variable to the process's exit code.
618
619 dotlock - create a manual dot-lock
620 dotlock expression {
621
622 ...
623
624 }
625
626
627 maildrop automatically creates a lock when a message is delivered
628 to a mailbox. Depending upon your system configuration, maildrop
629 will use either dot-locks, or the flock() system call.
630
631 The dotlock statement creates an explicit dot-lock file. Use the
632 flock statement[9] to create an explicit flock() lock.
633
634 The expression is a filename that should be used as a lock file.
635 maildrop creates the indicated dot-lock, executes the filtering
636 instructions contained within the { ... } block, and removes the
637 lock. The expression must be the name of the dot-lock file itself,
638 NOT the name of the mailbox file you want to lock.
639
640 Note
641 With manual locking, it is possible to deadlock multiple
642 maildrop processes (or any other processes that try to claim
643 the same locks).
644
645 No deadlock detection is possible with dot-locks, and since
646 maildrop automatically refreshes all of its dot-locks
647 regularly, they will never go stale. You'll have maildrop
648 processes hanging in limbo, until their watchdog timers go off,
649 aborting the mail delivery.
650
651 echo - output diagnostic information
652 echo expression
653
654
655 maildrop will print the given text. This is usually used when
656 maildrop runs in embedded mode, but can be used for debugging
657 purposes. Normally, a newline is printed after the text. If text is
658 terminated with a \c, no newline will be printed.
659
660 exception - trap fatal errors
661 exception {
662
663 ...
664
665 }
666
667
668 The exception statement traps errors that would normally cause
669 maildrop to terminate. If a fatal error is encountered anywhere
670 within the block of statements enclosed by the exception clause,
671 execution will resume immediately following the exception clause.
672
673 exit - terminate filtering unconditionally
674 exit
675
676
677 The exit statement immediately terminates filtering. maildrop's
678 return code is set to the value of the EXITCODE variable. Normally,
679 maildrop terminates immediately after successfully delivering the
680 message[8] to a mailbox. The exit statement causes maildrop to
681 terminate without delivering the message anywhere.
682
683 The exit statement is usually used when maildrop runs in embedded
684 mode[10], when message delivery instructions are not allowed.
685
686 flock - create an manual flock() lock
687 flock expression {
688
689 ...
690
691 }
692
693
694 maildrop automatically creates a lock when a message is delivered
695 to a mailbox. Depending upon your system configuration, maildrop
696 will use either dot-locks, or the flock() system call.
697
698 The flock statement creates a manual flock() lock. Use the dotlock
699 statement[11] to create a manual dot-lock file.
700
701 The expression is the name of the file that should be locked.
702 maildrop creates the lock on the indicated file, executes the
703 filtering instructions contained within the { ... } block, and
704 removes the lock.
705
706 Note
707 With manual locking, it is possible to deadlock multiple
708 maildrop processes (or any other processes that try to claim
709 the same locks). The operating system will automatically break
710 flock() deadlocks. When that happens, one of the maildrop
711 processes will terminate immediately. Use the exception
712 statement in order to trap this exception condition, and
713 execute an alternative set of filtering instructions.
714
715 foreach - iterate over text sections matched by a pattern
716 foreach /pattern/:options
717 {
718 ...
719 }
720
721 foreach (expression) =~ /pattern/:options
722 {
723 ...
724 }
725
726
727 The foreach statement executes a block of statements for each
728 occurrence of the given pattern in the given message, or
729 expression. On every iteration MATCH variable will be set to the
730 matched string. All the usual options may be applied to the pattern
731 match, EXCEPT the following:
732
733 ,xxx,yyy
734 Weighted scoring is meaningless, in this context.
735
736 ( ... )
737 Subpatterns are not processed. Only the MATCH variable will be
738 set for each found pattern.
739
740 if - conditional execution
741 if (expression)
742 {
743 ...
744 }
745 else
746 {
747 ...
748 }
749
750
751 Conditional execution. If expression evaluates to a logical true
752 (note - parenthesis are required) then the first set of statements
753 is executed. The else keyword, and the subsequent statements, are
754 optional. If present, and the expression evaluates to a logical
755 false, the else part is executed.
756
757 maildrop evaluates all expression as text strings. In the context
758 of a logical expression, an empty string, or the number 0
759 constitutes a logical false value, anything else is a logical true
760 value.
761
762 If the if part, or the else part consists of only one statement,
763 the braces may be omitted.
764
765 Note
766 The grammar of this if statement is stricter than usual. If you
767 get baffling syntax errors from maildrop, make sure that the
768 braces, and the if statement, appear on separate lines.
769 Specifically: the closing parenthesis, the closing braces, and
770 the else statement, must be at the end of the line (comments
771 are allowed), and there may not be any blank lines in between
772 (not even ones containing comments only).
773
774 If the else part contains a single if, and nothing else, this may
775 be combined into an elsif:
776
777 if (expression)
778 {
779 ...
780 }
781 elsif (expression)
782 {
783 ...
784 }
785
786
787 The above example is logically identical to:
788
789 if (expression)
790 {
791 ...
792 }
793 else
794 {
795 if (expression)
796 {
797 ...
798 }
799 }
800
801
802 Consecutive elsif sequences are allowed:
803
804 if (expression)
805 {
806 ...
807 }
808 elsif (expression)
809 {
810 ...
811 }
812 elsif (expression)
813 {
814 ...
815 }
816
817
818 Consecutive occurences of elsif commands eliminate a significant
819 amount of indentation, and the resulting code is more readable.
820
821 import - access original environment variable
822 import variable
823
824
825 When maildrop starts, it normally imports the contents of the
826 environment variables, and assigns them to internal maildrop
827 variables. For example, if there was an environment variable FOO,
828 the internal maildrop variable FOO will have the contents of the
829 environment variable. From then on, FOO will be no different than
830 any other variable, and when maildrop runs an external command, the
831 contents of maildrop's variables will be exported as the
832 environment for the command.
833
834 Certain variables, like HOME and PATH, are always reset to fixed
835 defaults, for security reasons. Also, in delivery and embedded
836 modes, the environment is not imported at all (with the exception
837 of system locale environment variables), and maildrop starts with
838 only the fixed default variables.
839
840 The import statement initializes the specified variable with the
841 contents of the original environment variable when maildrop
842 started. For example:
843
844 echo "PATH is $PATH"
845 PATH="/bin"
846 echo "PATH is $PATH"
847 import PATH
848 echo "PATH is $PATH"
849 exit
850
851
852 This results in the following output:
853
854 PATH is /bin:/usr/bin:/usr/local/bin
855 PATH is /bin
856 PATH is /home/root/bin:/sbin:/usr/sbin:/bin:/usr/bin:/usr/local/bin
857
858
859 This shows that when maildrop starts PATH is set to the fixed
860 default of /bin:/usr/bin:/usr/local/bin. However, the original
861 contents of the PATH environment variable we different, and the
862 import statement shows what it was.
863
864 include - execute filtering instructions from another file
865 include expression
866
867
868 The include statement reads a file, and executes filtering
869 instructions contained in that file. Note that the include
870 statement is processed when the current filter file is being
871 executed. When maildrop reads the initial filter file, any syntax
872 errors in the filtering instructions are immediately reported, and
873 maildrop will terminate with a return code of EX_TEMPFAIL. Any
874 errors in files specified by include statements are NOT reported,
875 because those files will not be read until the include statement is
876 itself executed.
877
878 If the specified file does not exist, or if there are any syntax
879 errors in the file, maildrop reports the error, and terminates with
880 a return code of EX_TEMPFAIL.
881
882 log, logfile - log message deliveries
883 logfile expression
884
885 log expression
886
887
888 Logging in maildrop is normally turned off. The logfile statement
889 specifies the file where maildrop will log how the message has been
890 disposed of. The parameter is then name of the file. If the file
891 exists maildrop appends to the file.
892
893 For each delivery (the to[8] and cc[12] statements, and default
894 deliveries) maildrop records the From: and the Subject: fields,
895 together with the current time, in the log file.
896
897 The log statement adds additional logging text to the log file. The
898 log statement works exactly like the echo statement, except that
899 the text is written to the logfile, instead of standard output.
900
901 system - execute a system command
902 system expression
903
904
905 expression specifies an external program that maildrop runs as a
906 subprocess. The subprocess's standard input gets connected to
907 /dev/null, and the subprocess inherits the standard output and
908 error from maildrop.
909
910 to - deliver message to a mailbox
911 to expression
912
913
914 The to statement delivers the message to a mailbox. expression
915 must evaluate to a valid mailbox. A valid mailbox is either a
916 mailbox file, a maildir, or an external program (which includes
917 forwarding to another address).
918
919 The to statement is the final delivery statement. maildrop
920 delivers message, then immediately terminates, with its return code
921 set to the EXITCODE variable. If there was an error while
922 delivering the message, maildrop terminates with the EX_TEMPFAIL
923 exit code. A properly-written mail transport agent should re-queue
924 the message, and re-attempt delivery at some later time.
925
926 An expression that begins with the "|" character specifies an
927 external program to run to handle the actual delivery. The SHELL
928 variable specifies the shell to execute the given command. The
929 message is provided to the command on standard input. maildrop's
930 exit code will be the process's exit code.
931
932 An expression that begins with an exclamation mark, "!" specifies a
933 whitespace-delimited list of E-mail addresses to forward the
934 message to. The program specified by the SENDMAIL variable is run
935 as an external program, with the list of E-mail addresses provided
936 as parameters to the program.
937
938 Otherwise, expression names the mailbox where maildrop delivers the
939 message. If expression is a directory, maildrop assumes that the
940 directory is a maildir directory. Otherwise, maildrop will deliver
941 the message to a file, formatted in traditional mailbox format.
942 maildrop will use either dot-locking, or flock()-locking when
943 delivering the message to the file.
944
945 while - repeatedly execute a block of statements
946 while (expression)
947 {
948 ...
949 }
950
951
952 The expression is repeatedly evaluated. Each time it evaluates to a
953 logical true[13], the statements inside the braces are executed.
954 When expression evaluates to a logical false, the while loop is
955 over. Take care to avoid infinite loops.
956
957 xfilter - filter message through another program
958 xfilter expression
959
960
961 expression specifies an external program that maildrop runs to
962 filter the current message. The current message will be piped to
963 the filter program as standard input. The output of the filter
964 program replaces the current message being delivered. The external
965 program must terminate with an exit code of 0. If the external
966 program does not terminate with an exit code of 0, or if it does
967 not read the message from the standard input, maildrop terminates
968 with an exit code of EX_TEMPFAIL.
969
970 || - logical or
971 expression1 || expression2
972
973
974
975 If expression1 evaluates to a logical true, the result of the || is
976 expression1, otherwise it's expression2, which is evaluated.
977
978 maildrop uses the following concept of true/false: an empty text
979 literal, or a text literal that consists of the single character
980 "0" is a logical false value. Anything else is a logical true
981 value.
982
983 && - logical and
984 expression1 && expression2
985
986
987
988 If expression1 evaluates to a logical false, the result of the &&
989 is expression1, otherwise it's expression2, which is evaluated.
990
991 maildrop uses the following concept of true/false: an empty text
992 literal, or a text literal that consists of the single character
993 "0" is a logical false value. Anything else is a logical true
994 value.
995
996 <, <=, >, >=, ==, != - numerical comparison
997 expression1 < expression2
998
999 expression1 <= expression2
1000
1001 expression1 > expression2
1002
1003 expression1 >= expression2
1004
1005 expression1 == expression2
1006
1007 expression1 != expression2
1008
1009
1010
1011 These operators compare their left hand side expression against
1012 their right hand side. These operators compare the numerical values
1013 of each side, as floating point numbers. If the numbers compare as
1014 indicated, the result of the comparison is the text string "1",
1015 otherwise it is the text string 0.
1016
1017 Note
1018 Ccomparisons are not associative: "a < b < c" is an error. If
1019 it is absolutely necessary, use "(a < b) < c".
1020
1021 lt, le, gt, ge, eq, ne - text comparison
1022 expression1 lt expression2
1023
1024 expression1 le expression2
1025
1026 expression1 gt expression2
1027
1028 expression1 ge expression2
1029
1030 expression1 eq expression2
1031
1032 expression1 ne expression2
1033
1034
1035
1036 These operators compare their left hand side expression against
1037 their right hand side. These operators compare each side as text
1038 strings (alphabetically, although the text may include anything).
1039 If the text strings compare as indicated, the result of the
1040 comparison is the text string "1", otherwise it is the text string
1041 0.
1042
1043 Note
1044 Comparisons are not associative: "a lt b lt c" is an error. If
1045 it is absolutely necessary, use "(a lt b) lt c". (But why would
1046 you?).
1047
1048 | - bitwise or
1049 expression1 | expression2
1050
1051
1052 This is the bitwise or operator. Its result is a 32 bit integer,
1053 which is a bitwise-or combination of the left hand side and the
1054 right hand side.
1055
1056 & - bitwise and
1057 expression1 & expression2
1058
1059
1060 This is the bitwise and operator. Its result is a 32 bit integer,
1061 which is a bitwise-and combination of the left hand side and the
1062 right hand side.
1063
1064 +, -, *, / - numerical operations
1065 expression1 + expression2
1066
1067 expression1 - expression2
1068
1069 expression1 * expression2
1070
1071 expression1 / expression2
1072
1073
1074
1075 These are numerical, floating point, operators.
1076
1077 =~ /pattern/:options - pattern match against string
1078 expression =~ /pattern/:option
1079
1080
1081 The left hand side of the =~ operator can be any expression. The
1082 right hand side is always a pattern specification. The result of
1083 the operator is the weighted match of the pattern against
1084 expression (if the options do not specify weighted scoring, the
1085 result is simply 1 if the pattern was found, 0 if not).
1086
1087 See "Patterns[14]" for more information.
1088
1089 /pattern/:options - pattern match against message
1090 /pattern/:option
1091
1092
1093 The result of this operator is the weighted match of the pattern
1094 against the current message (if the options do not specify weighted
1095 scoring, the result is simply 1 if the pattern was found, 0 if
1096 not).
1097
1098 See "Patterns[14]" for more information.
1099
1100 !, ~ - logical/bitwise not operator.
1101 ! expression
1102
1103 ~ expression
1104
1105
1106 The result of the ! operator is a logical opposite of its right
1107 hand side expression. If the right hand side expression evaluated
1108 to a logical true, the result is a logical false. If it evaluated
1109 to a logical false, the result is a logical true.
1110
1111 maildrop uses the following concept of true/false: an empty text
1112 literal, or a text literal that consists of the single character
1113 "0" is a logical false value. Anything else is a logical true
1114 value.
1115
1116 The result of the ~ operator is a bitwise complement of its right
1117 hand side expression. The right hand side expression is evaluated
1118 as a 32 bit integer, and the result of this operator is a bitwise
1119 complement of the result.
1120
1121 escape(string) - escape special characters in a string.
1122 escape(expression)
1123
1124
1125 The escape function returns its sole argument with every occurrence
1126 of a special character prefixed by a backslash. A special character
1127 is any of the following characters:
1128
1129 |!$()[]\+*?.&;`'-~<>^{}"
1130
1131
1132 This can used when matching pattern sections[15], and then taking
1133 one section and matching it again. For example:
1134
1135 if ( /^From:\s*(.*)/ )
1136 {
1137 MATCH1=escape($MATCH1)
1138 if ( /^Subject:.*$MATCH1/ )
1139 {
1140 ...
1141 }
1142 }
1143
1144
1145 This example checks if the contents of the From: header can also be
1146 found in the Subject: header. If the escape function were not used,
1147 then any special characters in the From: header that are also used
1148 in regular expressions, such as * or +, would introduce
1149 unpredictable behavior, most likely a syntax error.
1150
1151 The reason why this list of special characters also includes
1152 characters not used in maildrop's regular expressions is to allow
1153 maildrop's variables to be used on the command line of a shell
1154 command executed by the xfilter command, backtick characters, or to
1155 or cc commands.
1156
1157 Although using data from an external data source is dangerous, and
1158 it may result in inadvertent exploits, using the escape function
1159 should hopefully result in fewer surprises.
1160
1161 gdbmopen, gdbmclose, gdbmfetch, gdbmstore - GDBM support in maildrop
1162 These functions provide support for GDBM database files. See
1163 maildropgdbm(5)[16] for more information.
1164
1165 Note
1166 The system administrator can disable GDBM support in maildrop,
1167 so these commands may not be available to you.
1168
1169 getaddr(string) - extract RFC 2822 addresses from a header.
1170 if ( /^From:\s*(.*)/ )
1171 {
1172 ADDR=getaddr($MATCH1)
1173 }
1174
1175
1176 This function is usually applied to a header that contains RFC
1177 2822[17] addresses. It extracts the actual addresses from the
1178 header, without any comments or extraneous punctuation. Each
1179 address is followed by a newline character. For example, if string
1180 contains:
1181
1182 joe@domain.com (Joe Brown), "Alex Smith" <alex@domain.com>, tom@domain.com
1183
1184
1185 The result of the getaddr function is the following string:
1186
1187 joe@domain.com<NL>alex@domain.com<NL>tom@domain.com<NL>
1188
1189
1190 Note
1191 Because getaddr() interprets RFC 2822[18] loosely, it is not
1192 necessary to strip off the "To:" or the "Cc:" header from the
1193 string, before feeding it to getaddr(). For example, the
1194 following snippet of code takes all addresses in the message,
1195 and concatenates them into a single string, separated by
1196 spaces:
1197
1198 ADDRLIST=""
1199 foreach /^(To|Cc): .*/
1200 {
1201 foreach (getaddr $MATCH) =~ /.+/
1202 {
1203 ADDRLIST="$ADDRLIST $MATCH"
1204 }
1205 }
1206
1207
1208 Note
1209 In certain rare situations, RFC 2822[18] allows spaces to be
1210 included in E-mail addresses, so this example is just
1211 educational.
1212
1213 hasaddr(string) - Search for an address.
1214 if ( hasaddr(string) )
1215 {
1216 ...
1217 }
1218
1219
1220 "string" is of the form user@domain. The hasaddr function returns 1
1221 if this address is included in any To:, Cc:,Resent-To:, or
1222 Resent-Cc:, header in the message, otherwise this function returns
1223 0.
1224
1225 This is more than just a simple text search. Each header is parsed
1226 according to RFC822. Addresses found in the header are extracted,
1227 ignoring all comments and names. The remaining addresses are
1228 checked, and if "string" is one of them, hasaddr returns 1,
1229 otherwise it returns 0.
1230
1231 The comparison is case-insensitive. This actually violates RFC822
1232 (and several others) a little bit, because the user part of the
1233 address may be (but is not required to be) case sensitive.
1234
1235 length (string) - length of a string
1236 if (length(string) > 80)
1237 {
1238 ...
1239 }
1240
1241
1242 The length function returns the number of characters in string.
1243
1244 lookup (expr, 'filename', 'options') - read file for patterns
1245 if (lookup(expr, file, "option"))
1246 {
1247 ...
1248 }
1249
1250
1251 expr is any expression. filename is a name of a file containing a
1252 list of patterns. Note that filename is relative to the current
1253 directory, which is the home directory of the user when maildrop
1254 runs in delivery mode, or embedded mode. maildrop then reads the
1255 file. Blank lines will be ignored, as well as any lines that begin
1256 with the # character (comments).
1257
1258 Leading whitespace (but not trailing whitespace, take care) is
1259 removed, and the remaining contents of each line are interpreted as
1260 a pattern which is matched against expr. As soon as the match is
1261 found, lookup returns "1". If no match is found after reading the
1262 entire file, lookup returns "0". For example:
1263
1264 if ( /^To:\s*(.*)/ && lookup( $MATCH1, "badto.dat" ))
1265 {
1266 exit
1267 }
1268
1269
1270 The file badto.dat contains the following two lines:
1271
1272 friend@public
1273 ^[^@]*$
1274
1275
1276 If a message has a To: header that contains the text
1277 "friend@public", or does not contain at least one @ character, then
1278 the message will be silently dropped on the floor ( maildrop will
1279 terminate without delivering the message anywhere).
1280
1281 options are the pattern matching options to use. The only supported
1282 option is "D" (the rest are meaningless, in this case).
1283
1284 Note
1285 Be careful with discarding messages like that. Pattern matching
1286 can be tricky, and a slight miscalculation can cause mail to be
1287 unintentionally discarded. It is much desirable to first
1288 deliver message to a separate folder or mailbox, and once the
1289 filter is verified to work correctly, change it so the messages
1290 are discarded completely.
1291
1292 substr(string,start [,count]) - return substring
1293 foo=substr($foo, 1, 10)
1294
1295
1296 The substr function extracts characters from string beginning with
1297 character #start. If count is specified, at most count characters
1298 starting at position start are kept, any excess is trimmed.
1299
1300 time - return current time
1301 foo=time
1302
1303
1304 The time function returns the current time, in seconds, since
1305 January 1, 1970. This function is useful when using GDBM files. See
1306 maildropex(7)[19] for an example of using the time function.
1307
1308 tolower(string) - Convert string to lowercase.
1309 foo=tolower(string)
1310
1311
1312 This function returns the string with all uppercase characters
1313 replaced by lowercase characters.
1314
1315 toupper(string) - Convert string to uppercase.
1316 foo=toupper(string)
1317
1318
1319 This function returns the string with all lowercase characters
1320 replaced by uppercase characters.
1321
1322 Statements
1323 The filter file is read by maildrop ($HOME/.mailfilter or another
1324 file), and it contains filtering statements, one per line. The
1325 filtering language used by maildrop has a loosely - defined grammatical
1326 structure.
1327
1328 Statements are listed one per line. Multiple statements may be listed
1329 on the same line by separating them with semicolons. To continue a long
1330 statement on the next line, terminate the line with a backslash
1331 character.
1332
1334 If getaddr() or hasaddr() functions are used on broken headers, the
1335 results are unpredictable.
1336
1337 hasaddr() is completely case insensitive. This actually violates a few
1338 RFCs, because the userid portion of the address could be
1339 case-sensitive, but it's not in too many cases, so there.
1340
1342 lockmail(1)[20], maildrop(1)[21], maildropgdbm(5)[16],
1343 maildirquota(8)[4], reformail(1)[22], egrep(1), sendmail(8).
1344
1346 Sam Varshavchik
1347 Author
1348
1350 1. Courier mail server
1351 http://www.courier-mta.org/
1352
1353 2. dot-courier(5)
1354 http://www.courier-mta.org/maildrop/dot-courier.html
1355
1356 3. value of the -M option
1357 http://www.courier-mta.org/maildrop/maildrop.html#moption
1358
1359 4. maildirquota(8)
1360 http://www.courier-mta.org/maildrop/maildirquota.html
1361
1362 5. system
1363 http://www.courier-mta.org/maildrop/#system
1364
1365 6. xfilter
1366 http://www.courier-mta.org/maildrop/#xfilter
1367
1368 7. PCRE
1369 http://www.pcre.org
1370
1371 8. See the to statement
1372 http://www.courier-mta.org/maildrop/#to
1373
1374 9. flock statement
1375 http://www.courier-mta.org/maildrop/#flock
1376
1377 10. embedded mode
1378 http://www.courier-mta.org/maildrop/maildrop.html#embedded
1379
1380 11. dotlock statement
1381 http://www.courier-mta.org/maildrop/#dotlock
1382
1383 12. cc
1384 http://www.courier-mta.org/maildrop/#cc
1385
1386 13. evaluates to a logical true
1387 http://www.courier-mta.org/maildrop/#if
1388
1389 14. Patterns
1390 http://www.courier-mta.org/maildrop/#patterns
1391
1392 15. matching pattern sections
1393 http://www.courier-mta.org/maildrop/#patmatch
1394
1395 16. maildropgdbm(5)
1396 http://www.courier-mta.org/maildrop/maildropgdbm.html
1397
1398 17. RFC 2822
1399 http://www.rfc-editor.org/rfc/rfc2822.txt
1400
1401 18. RFC 2822
1402 http://www.rfc-editor.org/rfc/rfc822.txt
1403
1404 19. maildropex(7)
1405 http://www.courier-mta.org/maildrop/maildropex.html
1406
1407 20. lockmail(1)
1408 http://www.courier-mta.org/maildrop/lockmail.html
1409
1410 21. maildrop(1)
1411 http://www.courier-mta.org/maildrop/maildrop.html
1412
1413 22. reformail(1)
1414 http://www.courier-mta.org/maildrop/reformail.html
1415
1416
1417
1418Courier Mail Server 11/12/2022 MAILDROPFILTER(7)