874 |
in call to `header' |
in call to `header' |
875 |
@end example |
@end example |
876 |
|
|
877 |
@menu |
@deffn Test false |
|
* false:Sieve test false. |
|
|
* true:Sieve test true. |
|
|
* address:Sieve test address. |
|
|
* size:Sieve test size. |
|
|
* envelope:Sieve test envelope. |
|
|
* exists:Sieve test exists. |
|
|
* header:Sieve test header. |
|
|
* numaddr:Sieve test numaddr. |
|
|
@end menu |
|
|
|
|
|
@node Sieve test false |
|
|
@subsubsection Sieve test false |
|
|
|
|
|
@example |
|
|
Syntax: false |
|
|
@end example |
|
|
|
|
878 |
This test always evaluates to ``false''. |
This test always evaluates to ``false''. |
879 |
|
@end deffn |
880 |
|
|
881 |
@node Sieve test true |
@deffn Test true |
|
@subsubsection Sieve test true |
|
|
|
|
|
@example |
|
|
Syntax: true |
|
|
@end example |
|
|
|
|
882 |
This test always evaluates to ``true''. |
This test always evaluates to ``true''. |
883 |
|
@end deffn |
884 |
|
|
885 |
@node Sieve test address |
@deffn Test address [@var{address-part}][@var{comparator}][@var{match-type}] @var{header-names} @var{key-list} |
|
@subsubsection Sieve test address |
|
886 |
|
|
|
@example |
|
|
Syntax: address [@var{address-part}][@var{comparator}][@var{match-type}] |
|
|
@var{header-names} @var{key-list} |
|
|
@end example |
|
|
@sp 1 |
|
|
@noindent |
|
887 |
Tagged arguments: |
Tagged arguments: |
888 |
|
|
889 |
@table @var |
@table @var |
932 |
discard; |
discard; |
933 |
@} |
@} |
934 |
@end example |
@end example |
935 |
|
@end deffn |
936 |
|
|
937 |
@node Sieve test size |
@deffn Test size [:over|:under] @var{number} |
|
@subsubsection Sieve test size |
|
|
|
|
|
@example |
|
|
Syntax: size [:over|:under] @var{number} |
|
|
@end example |
|
938 |
@sp 1 |
@sp 1 |
939 |
@noindent |
@noindent |
940 |
The @code{size} test deals with the size of a message. The required |
The @code{size} test deals with the size of a message. The required |
960 |
the @var{number}, the test is true; otherwise, it is false. |
the @var{number}, the test is true; otherwise, it is false. |
961 |
|
|
962 |
Otherwise, the test is true only if the size of the message equals |
Otherwise, the test is true only if the size of the message equals |
963 |
exactly @var{number}. This is a GNU extension |
exactly @var{number}. This is a GNU extension. |
964 |
|
|
965 |
The size of a message is defined to be the number of octets from the |
The size of a message is defined to be the number of octets from the |
966 |
initial header until the last character in the message body. |
initial header until the last character in the message body. |
967 |
|
@end deffn |
968 |
|
|
969 |
|
@deffn Test envelope [@var{address-part}][@var{comparator}][@var{match-type}] @var{envelope-part} @var{key-list} |
|
@node Sieve test envelope |
|
|
@subsubsection Sieve test envelope |
|
|
|
|
|
@example |
|
|
Syntax: envelope [@var{address-part}][@var{comparator}][@var{match-type}] |
|
|
@var{envelope-part} @var{key-list} |
|
|
@end example |
|
970 |
@sp 1 |
@sp 1 |
971 |
@noindent |
@noindent |
972 |
Tagged arguments: |
Tagged arguments: |
1006 |
@emph{Notice}, that due to the limitations imposed by @sc{smtp} envelope |
@emph{Notice}, that due to the limitations imposed by @sc{smtp} envelope |
1007 |
structure the use of any other values in @var{envelope-parts} header is |
structure the use of any other values in @var{envelope-parts} header is |
1008 |
meaningless. |
meaningless. |
1009 |
|
@end deffn |
1010 |
|
|
1011 |
@node Sieve test exists |
@deffn Test exists @var{header-names} |
1012 |
@subsubsection Sieve test exists |
@sp 1 |
1013 |
|
@noindent |
1014 |
|
Required arguments: |
1015 |
|
|
1016 |
@example |
@table @var |
1017 |
Syntax: exists @var{header-names} |
@item header-names |
1018 |
@end example |
List of message header names. |
1019 |
|
@end table |
1020 |
@sp 1 |
@sp 1 |
1021 |
@noindent |
@noindent |
1022 |
|
|
1033 |
discard; |
discard; |
1034 |
@} |
@} |
1035 |
@end example |
@end example |
1036 |
|
@end deffn |
1037 |
|
|
1038 |
@node Sieve test header |
@deffn header [@var{comparator}] [@var{match-type}] [:mime] @var{header-names} @var{key-list} |
1039 |
@subsubsection Sieve test header |
@sp 1 |
|
|
|
|
@example |
|
|
Syntax: header [@var{comparator}] [@var{match-type}] [:mime] |
|
|
@var{header-names} @var{key-list} |
|
|
@end example |
|
|
|
|
1040 |
@noindent |
@noindent |
1041 |
Tagged arguments: |
Tagged arguments: |
1042 |
|
|
1087 |
header :is ["X-Caffeine"] [""] @result{} false |
header :is ["X-Caffeine"] [""] @result{} false |
1088 |
header :contains ["X-Caffeine"] [""] @result{} true |
header :contains ["X-Caffeine"] [""] @result{} true |
1089 |
@end example |
@end example |
1090 |
|
@end deffn |
1091 |
|
|
1092 |
@node Sieve test numaddr |
@deffn Test numaddr [:over|:under] @var{header-names} @var{number} |
|
@subsubsection Sieve test numaddr |
|
|
|
|
|
@example |
|
|
Syntax: require "test-numaddr"; |
|
|
numaddr [:over|:under] @var{header-names} @var{number} |
|
|
@end example |
|
|
@sp 1 |
|
|
@noindent |
|
1093 |
|
|
1094 |
This test is provided as an example of loadable extension tests. You |
This test is provided as an example of loadable extension tests. You |
1095 |
must use @samp{require "test-numaddr"} statement before actually using |
must use @samp{require "test-numaddr"} statement before actually using |
1106 |
less than @var{number}, the test is true; otherwise, it is false. |
less than @var{number}, the test is true; otherwise, it is false. |
1107 |
|
|
1108 |
If the tagged argument is not given, @samp{:over} is assumed. |
If the tagged argument is not given, @samp{:over} is assumed. |
1109 |
|
@end deffn |
1110 |
|
|
1111 |
@node Actions |
@node Actions |
1112 |
@subsection Actions |
@subsection Actions |
1113 |
|
|
1114 |
|
The GNU libsieve supports the following default actions: |
1115 |
|
|
1116 |
|
@itemize |
1117 |
|
@item stop |
1118 |
|
@item keep |
1119 |
|
@item discard |
1120 |
|
@item fileinto |
1121 |
|
@item reject |
1122 |
|
@item redirect |
1123 |
|
@end itemize |
1124 |
|
|
1125 |
|
Among them the first three actions do not need to be explicitly required |
1126 |
|
by a @code{require} statement, while the others do. |
1127 |
|
|
1128 |
|
These actions are described in detail below. |
1129 |
|
|
1130 |
|
@deffn Action stop |
1131 |
|
|
1132 |
|
The @code{stop} action ends all processing. If no actions have been |
1133 |
|
executed, then the @code{keep} action is taken. |
1134 |
|
@end deffn |
1135 |
|
|
1136 |
|
@deffn Action keep |
1137 |
|
|
1138 |
|
The effect of this action is to preserve the current message in the |
1139 |
|
mailbox. This action is executed if no other action has been executed. |
1140 |
|
@end deffn |
1141 |
|
|
1142 |
|
@deffn discard |
1143 |
|
|
1144 |
|
@code{Discard} silently throws away the current message. No notification |
1145 |
|
is returned to the sender, the message is deleted from the mailbox. |
1146 |
|
|
1147 |
|
Example: |
1148 |
|
@example |
1149 |
|
if header :contains ["from"] ["idiot@@example.edu"] |
1150 |
|
@{ |
1151 |
|
discard; |
1152 |
|
@} |
1153 |
|
@end example |
1154 |
|
@end deffn |
1155 |
|
|
1156 |
|
@deffn Action fileinto @var{folder} |
1157 |
|
@noindent |
1158 |
|
@sp 1 |
1159 |
|
Required arguments: |
1160 |
|
|
1161 |
|
@table @var |
1162 |
|
@item folder |
1163 |
|
A string representing the folder name |
1164 |
|
@end table |
1165 |
|
|
1166 |
|
The @code{fileinto} action delivers the message into the specified folder. |
1167 |
|
@end deffn |
1168 |
|
|
1169 |
|
@deffn Action reject @var{reason} |
1170 |
|
|
1171 |
|
The optional @code{reject} action refuses delivery of a message by sending |
1172 |
|
back a message delivery notification to the sender. It resends the |
1173 |
|
message to the sender, wrapping it in a ``reject'' form, noting that it |
1174 |
|
was rejected by the recipient. The required argument @var{reason} is |
1175 |
|
a string specifying the reason for rejecting the message. |
1176 |
|
|
1177 |
|
Example: |
1178 |
|
|
1179 |
|
If the message contained |
1180 |
|
@example |
1181 |
|
Date: Tue, 1 Apr 1997 09:06:31 -0800 (PST) |
1182 |
|
From: coyote@@desert.example.org |
1183 |
|
To: roadrunner@@acme.example.com |
1184 |
|
Subject: I have a present for you |
1185 |
|
|
1186 |
|
I've got some great birdseed over here at my place. |
1187 |
|
Want to buy it? |
1188 |
|
@end example |
1189 |
|
@noindent |
1190 |
|
@sp 1 |
1191 |
|
and the user's script contained: |
1192 |
|
|
1193 |
|
@example |
1194 |
|
if header :contains "from" "coyote@@desert.example.org" |
1195 |
|
@{ |
1196 |
|
reject "I am not taking mail from you, and I don't want |
1197 |
|
your birdseed, either!"; |
1198 |
|
@} |
1199 |
|
@end example |
1200 |
|
@noindent |
1201 |
|
then the original sender <coyote@@desert.example.org> would receive the |
1202 |
|
following notification: |
1203 |
|
|
1204 |
|
@example |
1205 |
|
To: <coyote@@desert.example.org> |
1206 |
|
X-Authentication-Warning: roadrunner set sender using -f flag |
1207 |
|
Content-Type: multipart/mixed; boundary=----- =_aaaaaaaaaa0 |
1208 |
|
MIME-Version: 1.0 |
1209 |
|
----- =_aaaaaaaaaa0 |
1210 |
|
The original message was received at |
1211 |
|
Tue, 1 Apr 1997 09:07:15 -0800 from |
1212 |
|
coyote@@desert.example.org. |
1213 |
|
Message was refused by recipient's mail filtering program. |
1214 |
|
Reason given was as follows: |
1215 |
|
|
1216 |
|
I am not taking mail from you, and I don't want your birdseed, either! |
1217 |
|
|
1218 |
|
----- =_aaaaaaaaaa0 |
1219 |
|
Content-Type: message/delivery-status |
1220 |
|
|
1221 |
|
Reporting-UA: sieve; GNU Mailutils 0.1.3 |
1222 |
|
Arrival-Date: Tue, 1 Apr 1997 09:07:15 -0800 |
1223 |
|
Final-Recipient: RFC822; roadrunner@@acme.example.com |
1224 |
|
Action: deleted |
1225 |
|
Disposition: automatic-action/MDN-sent-automatically;deleted |
1226 |
|
Last-Attempt-Date: Tue, 1 Apr 1997 09:07:15 -0800 |
1227 |
|
|
1228 |
|
----- =_aaaaaaaaaa0 |
1229 |
|
Content-Type: message/rfc822 |
1230 |
|
|
1231 |
|
From: coyote@@desert.example.org |
1232 |
|
To: roadrunner@@acme.example.com |
1233 |
|
Subject: I have a present for you |
1234 |
|
|
1235 |
|
I've got some great birdseed over here at my place. |
1236 |
|
Want to buy it? |
1237 |
|
----- =_aaaaaaaaaa0 |
1238 |
|
@end example |
1239 |
|
|
1240 |
|
If the @var{reason} argument is rather long, the common approach is |
1241 |
|
to use the combination of the @code{text:} and @code{#include} keywords, |
1242 |
|
e.g.: |
1243 |
|
|
1244 |
|
@example |
1245 |
|
if header :mime :matches "Content-Type" |
1246 |
|
[ "*application/msword;*", "*audio/x-midi*" ] |
1247 |
|
@{ |
1248 |
|
reject text: |
1249 |
|
#include "nomsword.txt" |
1250 |
|
. |
1251 |
|
; |
1252 |
|
@} |
1253 |
|
@end example |
1254 |
|
|
1255 |
|
@end deffn |
1256 |
|
|
1257 |
|
@deffn Action redirect @var{address} |
1258 |
|
The @code{redirect} action is used to send the message to another user at |
1259 |
|
a supplied @var{address}, as a mail forwarding feature does. This action |
1260 |
|
makes no changes to the message body or existing headers, but it may add |
1261 |
|
new headers. It also modifies the envelope recipient. |
1262 |
|
|
1263 |
|
The @code{redirect} command performs an MTA-style ``forward'' --- that |
1264 |
|
is, what you get from a @file{.forward} file using @code{sendmail} under |
1265 |
|
@sc{unix}. The address on the SMTP envelope is replaced with the one on |
1266 |
|
the @code{redirect} command and the message is sent back |
1267 |
|
out. @emph{Notice}, that it differs from the MUA-style forward, which |
1268 |
|
creates a new message with a different sender and message ID, wrapping |
1269 |
|
the old message in a new one. |
1270 |
|
@end deffn |
1271 |
|
|
1272 |
@node Extensions |
@node Extensions |
1273 |
@section Extensions |
@section Extensions |
1274 |
|
|
1275 |
|
This section summarizes the GNU extensions to the sieve language |
1276 |
|
|
1277 |
|
@enumerate 1 |
1278 |
|
|
1279 |
|
@item Handling of the @code{require} statement. |
1280 |
|
|
1281 |
|
@itemize |
1282 |
|
@item According to the RFC an error must occur if a @code{require} appears |
1283 |
|
after a command other than @code{require}. The GNU sieve library allows |
1284 |
|
interspersing the @code{require} and other statements. The only |
1285 |
|
requirement is that @code{require} must occur before a statement that is |
1286 |
|
using the required capability (@pxref{Require Statement}). |
1287 |
|
|
1288 |
|
@item Prefixing the required capability with ``test'' requires the use |
1289 |
|
of an extension test. |
1290 |
|
@end itemize |
1291 |
|
|
1292 |
|
@item @code{header} test |
1293 |
|
|
1294 |
|
The @code{header} takes an optional argument @code{:mime}, meaning to |
1295 |
|
scan the headers from each part of a multipart message. |
1296 |
|
|
1297 |
|
@item @code{size} test |
1298 |
|
|
1299 |
|
The @code{size} test allows to omit the optional argument |
1300 |
|
(:over|:under). In this case exact equality is assumed. |
1301 |
|
|
1302 |
|
@item @code{envelope} test |
1303 |
|
|
1304 |
|
The only value that can be meaningfully used as the first required |
1305 |
|
argument of an @code{envelope} test is @samp{from}. This limitation |
1306 |
|
may disappear from the subsequent releases. |
1307 |
|
|
1308 |
|
@item Match type optional argument. |
1309 |
|
|
1310 |
|
Along with the usual @code{:is}, @code{:matches} and @code{contains} |
1311 |
|
matching type, GNU sieve library understands @code{:regex} type. This |
1312 |
|
matching type toggles POSIX Extended Regular Expression matching. |
1313 |
|
|
1314 |
|
@end enumerate |
1315 |
|
|
1316 |
|
|
1317 |
|
|
1318 |
|
|