1IMAPFILTER_CONFIG(5) BSD File Formats Manual IMAPFILTER_CONFIG(5)
2
4 imapfilter_config — imapfilter configuration file
5
7 $HOME/.imapfilter/config.lua
8
10 imapfilter(1) uses the Lua programming language as a configuration and
11 extension language, therefore the configuration file is a Lua script.
12 Although knowledge of Lua is not required to use imapfilter(1), it is
14 nonetheless recommended, especially if one wants to extend it. For more
15 information on Lua see http://www.lua.org/docs.html.
16
18 A brief description of the Lua values and types mentioned hereafter in
19 the manual page follows:
20 The nil is the type of the value “nil”, whose main property is to be
22 different from any other value; usually it represents the absence of
23 a useful value.
24 The boolean is the type of the values “true” and “false”. Both “nil”
26 and “false” make a condition false; any other value makes it true.
27 The type number represents real numbers.
29 The type string represents a sequence of characters and can be
31 defined using single quotes, double quotes or double square brackets.
32 The type table implements associative arrays, that is, arrays that
34 can be indexed not only with numbers, but with any value.
35 A function is a first-class value; it can be stored in variables,
37 passed as argument to other functions, and returned as a result.
38
40 Program's options are set using an already initialised table named
41 “options”, in the following manner:
42 options.timeout = 120
44 options.namespace = false
45 options.charset = 'ISO-8859-1'
46 Available options are:
48 cache When this option is enabled, parts of messages are cached locally
50 in memory to avoid being downloaded more than once. The cache is
51 preserved for the current session only. This variable takes a
52 boolean as a value. Default is “true”.
53 certificates
55 When this option is enabled, the server certificate can be
56 accepted and stored, in order to validate the authenticity of the
57 server in future connections. This variable takes a boolean as a
58 value. Default is “true”.
59 charset
61 Indicates to the server the character set of the strings for the
62 searching methods. This variable takes a string as a value. By
63 default no character set is set, and thus plain ASCII should be
64 assumed by the server.
65 create According to the IMAP specification, when trying to write a mes‐
67 sage to a non-existent mailbox, the server must send a hint to
68 the client, whether it should create the mailbox and try again or
69 not. However some IMAP servers don't follow the specification and
70 don't send the correct response code to the client. By enabling
71 this option the client tries to create the mailbox, despite of
72 the server's response. This variable takes a boolean as a value.
73 Default is “false”.
74 close This option controls whether the currently selected mailbox is
76 implicitly closed at the end of each performed operation, thus
77 removing all messages that are marked deleted. This variable
78 takes a boolean as a value. Default is “false”.
79 crammd5
81 When this option is enabled and the server supports the Chal‐
82 lenge-Response Authentication Mechanism (specifically CRAM-MD5),
83 this method will be used for user authentication instead of a
84 plaintext password LOGIN. This variable takes a boolean as a
85 value. Default is “true”.
86 expunge
88 Normally, messages are marked for deletion and are actually
89 deleted when the mailbox is closed. When this option is enabled,
90 messages are expunged immediately after being marked deleted.
91 This variable takes a boolean as a value. Default is “true”.
92 info When this options is enabled, a summary of the program's actions
94 is printed, while processing mailboxes. This variable takes a
95 boolean as a value. Default is “true”.
96 keepalive
98 The time in minutes before terminating and re-issuing the IDLE
99 command, in order to keep alive the connection, by resetting the
100 inactivity timeout of the server. A standards compliant server
101 must have an inactivity timeout of at least 30 minutes. But it
102 may happen that some IMAP servers don't respect that, or some
103 intermediary network device has a shorter timeout. By setting
104 this option the above problem can be worked around. This variable
105 takes a number as a value. Default is “29” minutes.
106 limit Some servers have problems handling very long requests, but some
108 of the requests that need to be sent can become quite long,
109 because they apply an action for many messages at once. When
110 this option is set, the client will try to break up these
111 requests into smaller requests, that each operates on fewer mes‐
112 sages at a time. A good value for this would be “50”. This
113 variable takes a number as a value. Default is “0”. See also
114 the range option which is related.
115 namespace
117 When enabled, the program gets the namespace of the user's per‐
118 sonal mailboxes, and applies automatically the prefix and hierar‐
119 chy delimiter to any mailboxes residing on the mail server; the
120 user must use the ‘/’ character as the delimiter and “” (ie.
121 nothing) as the prefix, regardless of the folder format of the
122 mail server. This must be disabled, if the user wants to manu‐
123 ally specify mailbox names (eg. because they are not part of the
124 user's personal namespace mailboxes). This variable takes a
125 boolean as a value. Default is “true”.
126 persist
128 When the recover option is enabled, the recovery function tries
129 to restore the lost session, but if it fails to do so it gives up
130 with an error. In some cases a temporary network problem might
131 cause the recovery function to fail, but the connection could be
132 reestablished when trying a bit later. By enabling this option,
133 the recovery function will be called repeatedly after a timeout,
134 thus it will persist when trying to restore the session. Note,
135 that this will case the execution of the configuration file to be
136 halted at the point of failure until the session is restored,
137 which can have side effects to other established sessions, for
138 example they might get dropped by the server after a while. This
139 variable takes a boolean as a value. Default is “false”.
140 range Some servers have problems handling long sequence number ranges,
142 and by setting this option, the number of messages included in
143 each range can be limited. A good value for this would be “50”.
144 This variable takes a number as a value. By default no such
145 limit is imposed. See also the limit option which is related.
146 recover
148 With this option it is possible to control the recovery function‐
149 ality, which restores a session (the connection to the server and
150 the IMAP state at the time), after some unexpected event takes
151 place. Currently there are two types of events that can end
152 abnormally a session, and finally cause the program to terminate:
153 network errors, and the IMAP BYE response which a server can send
154 anytime. When this option is set to “all” the recovery function
155 is triggered by both types of events, when set to “errors” only
156 in the case of network errors, and when set to “none” the mecha‐
157 nism is completely disabled. Default is “all”.
158 reenter
160 When this option is enabled and the connection is recovered after
161 some unexpected event while in IDLE mode (see also the recover
162 option), the client will re-enter IDLE mode. But when this
163 option is disabled, and after the connection is recovered, the
164 client will not re-enter IDLE mode, and instead will continue to
165 execute the next line in the configuration file, ie. the one
166 after enter_idle(). Default is “true”.
167 starttls
169 When this option is enabled and the server supports the IMAP
170 STARTTLS extension, a TLS connection will be negotiated with the
171 mail server in the beginning of the session. This variable takes
172 a boolean as value. Default is “true”.
173 subscribe
175 By enabling this option new mailboxes that were automatically
176 created, get also subscribed; they are set active in order for
177 IMAP clients to recognize them. This variable takes a boolean as
178 a value. Default is “false”.
179 timeout
181 The time in seconds for the program to wait for a mail server's
182 response. If set to 0, the client will block indefinitely. This
183 variable takes a number as a value. Default is “60” seconds.
184 wakeonany
186 By enabling this option the IDLE command will return on any event
187 that is received from the server, and not just on the “RECENT”
188 and “EXISTS” events, that normally indicate the arrival of a new
189 message. Examples of other events are “FETCH”, which indicates
190 that the details of a message (eg. its flags) have been modified,
191 or “EXPUNGE”, which indicates that a message has been deleted.
192 This variable takes a boolean as a value. Default is “false”.
193
195 Accounts are initialized using the IMAP() function, and the details of
196 the connection are defined using an account table:
197 myaccount = IMAP {
199 server = 'imap.mail.server',
200 username = 'me',
201 password = 'secret',
202 ssl = 'auto'
203 }
204 An account table must have the following elements:
206 server The hostname of the IMAP server to connect to. It takes a string
208 as a value.
209 username
211 User's name. It takes a string as a value.
212 An account table can also have the following optional elements:
214 password
216 User's secret keyword. If a password wasn't supplied the user
217 will be asked to enter one interactively the first time it will
218 be needed (unless oauth2 has been set). It takes a string as a
219 value.
220 Note that due to Lua using backslash ‘\’ as an escape character
222 for its strings, one has to use double backslashes in order to
223 insert a single backslash, and thus a backslash character inside
224 a password might require four backslashes.
225 oauth2 The OAuth2 string to use to authenticate if the server supports
227 the XOAUTH2 authentication mechanism. If the server does not
228 support it and a password has been also set, authentication will
229 be attempted using the password. It takes a string as a value.
230 Note that this requires that an OAuth client ID and client secret
232 have been obtained, an OAuth2 token has been generated and autho‐
233 rized, a new access token has been generated using the refresh
234 token if the last access token has expired, and an OAuth2 string
235 has been generated from the access token. The aforementioned
236 OAuth2 string is a Base64 encoded string that should be set here.
237 For more information see
238 https://developers.google.com/gmail/xoauth2_protocol.
239 port The port to connect to. It takes a number as a value. Default
241 is “143” for imap and “993” for imaps.
242 ssl Forces an imaps connection and specifies the SSL/TLS proto‐
244 col/version to be used. It takes a string as a value, specifi‐
245 cally one of: “auto”, “tls1.2”, “tls1.1”, “tls1”, “ssl3”.
246 Note that the latest versions of the OpenSSL library have depre‐
248 cated version specific methods, and the actual protocol version
249 used will be negotiated to be the highest version mutually sup‐
250 ported by the client and the server. This is also what the
251 “auto” value does.
252 LISTING
254 The following methods can be used on an account to list mailboxes in a
255 folder of an account:
256 list_all(folder)
258 Lists all the available mailboxes in the folder (string), and
259 returns a table that contains strings, the available mailboxes,
260 and a table that contains strings, the available folders.
261 list_subscribed(folder)
263 Lists all the subscribed mailboxes in the folder (string), and
264 returns a table that contains strings, the subscribed mailboxes,
265 and a table that contains strings, the subscribed folders.
266 The following methods can be used on an account to list mailboxes, using
268 wildcards, in a folder of an account. The ‘*’ wildcard, matches any
269 character and the ‘%’ matches any character except the folder delimiter,
270 ie. non-recursively:
271 list_all(folder, mailbox)
273 Lists all the available mailboxes in the folder (string) with the
274 name mailbox (string), and returns a table that contains strings,
275 the available mailboxes, and a table that contains strings, the
276 available folders. Wildcards may only be used in the mailbox
277 argument.
278 list_subscribed(folder, mailbox)
280 Lists all the subscribed mailboxes in the folder (string) with
281 the name mailbox (string), and returns a table that contains
282 strings, the subscribed mailboxes, and a table that contains
283 strings, the subscribed folders. Wildcards may only be used in
284 the mailbox argument.
285 Examples:
287 mailboxes, folders = myaccount:list_subscribed('myfolder')
289 mailboxes, folders = myaccount:list_all('myfolder/mysubfolder', '*')
290 MANIPULATING
292 The following methods can be used to manipulate mailboxes in an account:
293 create_mailbox(name)
295 Creates the name (string) mailbox.
296 delete_mailbox(name)
298 Deletes the name (string) mailbox.
299 rename_mailbox(oldname, newname)
301 Renames the oldname (string) mailbox to newname (string).
302 subscribe_mailbox(name)
304 Subscribes the name (string) mailbox.
305 unsubscribe_mailbox(name)
307 Unsubscribes the name (string) mailbox.
308 Examples:
310 myaccount:create_mailbox('mymailbox')
312 myaccount:subscribe_mailbox('mymailbox')
313 myaccount:unsubscribe_mailbox('myfolder/mymailbox')
314 myaccount:delete_mailbox('myfolder/mymailbox')
315
317 After an IMAP account has been initialized, mailboxes residing in that
318 account can be accessed simply as elements of the account table:
319 myaccount.mymailbox
321 If mailbox names don't only include letters, digits and underscores, or
323 begin with a digit, an alternative form must be used:
324 myaccount['mymailbox']
326 A mailbox inside a folder can be only accessed by using the alternative
328 form:
329 myaccount['myfolder/mymailbox']
331 The methods that are available for an account (eg. list_all(),
333 create_mailbox(), etc.) , are considered keywords and must not be used as
334 mailbox names, and the same also applies for any string starting with an
335 underscore, as they are considered reserved.
336 CHECKING
338 The following methods can be used to check the status of a mailbox:
339 check_status()
341 The check_status() method gets the current status of a mailbox,
343 and returns four values of number type: the total number of mes‐
344 sages, the number of recent messages, the number of unseen mes‐
345 sages in the mailbox, and the next UID to be assigned to a new
346 message in the mailbox.
347 enter_idle()
349 The enter_idle() method implements the IMAP IDLE (RFC 2177)
350 extension. By using this extension it's not necessary to poll
351 the server for changes to the selected mailbox (ie. using the
352 check_status() method), but instead the server sends an update
353 when there is a change in the mailbox (eg. in case of new mail).
354 When the enter_idle() method has been called no more commands in
355 the configuration file are executed until an update is received,
356 at which point the enter_idle() method returns. For the
357 enter_idle() to work, the IDLE extension has to be supported by
358 the IMAP server.
359 The enter_idle() method returns a value of type boolean: “true”
361 if the IDLE extension is supported and there was a update in the
362 mailbox, and “false” if the IDLE extension is not supported, in
363 which case the method returns immediately. When the aforemen‐
364 tioned return value was “true”, an additional second value of
365 type string is also returned, indicating the event received from
366 the server, which is useful when the wakeonany option has been
367 enabled.
368 Apart from an event received by the server, the SIGUSR1 or
370 SIGUSR2 signals can also interrupt the IDLE mode at any time, and
371 the execution of the configuration file will then continue from
372 the next line after the enter_idle(). In this case only the
373 value “true” is returned.
374 Examples:
376 exist, unread, unseen, uidnext = myaccount.mymailbox:check_status()
378 update = myaccount.mymailbox:enter_idle()
379 update, event = myaccount.mymailbox:enter_idle()
380 SEARCHING
382 The searching methods in this subsection can be applied to any mailbox.
383 They return a special form of table, that contains the messages that
384 match the searching method. This table can be combined with other tables
385 using logic theory. There are three available operations, that implement
386 logical “or”, logical “and” and logical “not”.
387 The logical “or” is implemented using the ‘+’ operator:
389 results = myaccount.mymailbox:is_unseen() +
391 myaccount.mymailbox:is_larger(100000)
392 The logical “and” is implemented using the ‘*’ operator:
394 results = myaccount.mymailbox:is_unseen() *
396 myaccount.mymailbox:is_larger(100000)
397 The logical “not” is implemented using the ‘-’ operator:
399 results = myaccount.mymailbox:is_unseen() -
401 myaccount.mymailbox:is_larger(100000)
402 The three logical operators can be combined in the same expression. The
404 logical “and” has higher precedence than the logical “or” and the logical
405 “not”, with the latter two having the same precedence, and parentheses
406 may be used to change this behaviour:
407 results = myaccount.mymailbox:is_unseen() +
409 myaccount.mymailbox:is_larger(100000) *
410 myaccount.mymailbox:contain_subject('test')
411 results = ( myaccount.mymailbox:is_unseen() +
413 myaccount.mymailbox:is_larger(100000) ) *
414 myaccount.mymailbox:contain_subject('test')
415 The returned tables of the searching methods can also be stored in vari‐
417 ables and then further processed:
418 unseen = myaccount.myaccount:is_unseen()
420 larger = myaccount.mymailbox:is_larger(100000)
421 subject = myaccount.mymailbox:contain_subject('test')
422 results = unseen + larger * subject
423 A composite filter that includes one or more simple rules can be defined:
425 myfilter = function ()
427 return myaccount.mymailbox:is_unseen() +
428 myaccount.mymailbox:is_larger(100000) *
429 myaccount.mymailbox:contain_subject('test')
430 end
431 results = myfilter()
433 Composite filters can may be more dynamic by adding arguments:
435 myfilter = function (mailbox, size, subject)
437 return mailbox:is_unseen() +
438 mailbox:is_larger(size) *
439 mailbox:contain_subject(subject)
440 end
441 results = myfilter(myaccount.mailbox, 100000, 'test')
443 It is also possible to combine the searching methods in different mail‐
445 boxes, either at the same or different accounts, for example when the
446 same actions will be executed on messages residing in different mailboxes
447 or accounts.
448 results = myaccount.mymailbox:is_unseen() +
450 myaccount.myothermailbox:is_larger(100000) +
451 myotheraccount.myothermailbox:contain_subject('test')
452 And for those that want to know more about the return values of the fol‐
454 lowing methods, it is a table which contains tables with two values: the
455 mailbox (table) the message belongs to, and the message UID (number)
456 which points to the matching message. For examples on iterating these
457 returned tables, or creating new tables of this format (they are actually
458 metatables implementing sets), see the samples/extend.lua file.
459 {
461 { <myaccount.mymailbox>, 1 },
462 { <myaccount.mymailbox>, 3 },
463 { <myaccount.myothermailbox>, 5 },
464 { <myothermailbox.myothermailbox>, 7},
465 { ... },
466 ...
467 }
468 The following method can be used to get all messages in a mailbox:
470 select_all()
472 All messages.
473 The following methods can be used to search for messages that are in a
475 specific state:
476 is_answered()
478 Messages that have been answered.
479 is_deleted()
481 Messages that are marked for later removal.
482 is_draft()
484 Messages that have not completed composition.
485 is_flagged()
487 Messages that are flagged for urgent/special attention.
488 is_new()
490 Messages that are recently arrived (this session is the first to
491 have been notified about these messages) and have not been read.
492 is_old()
494 Messages that are not recently arrived (this session is not the
495 first to have been notified about these messages) and have not
496 been read.
497 is_recent()
499 Messages that are recently arrived (this session is the first to
500 have been notified about these messages).
501 is_seen()
503 Messages that have been read.
504 is_unanswered()
506 Messages that have not been answered.
507 is_undeleted()
509 Messages that are not marked for later removal.
510 is_undraft()
512 Messages that have completed composition.
513 is_unflagged()
515 Messages that are not flagged for urgent/special attention.
516 is_unseen()
518 Messages that have not been read.
519 The following method can be used to search for messages that have a spe‐
521 cific keyword flag set:
522 has_keyword(flag)
524 Messages with the specified keyword flag (string) set.
525 has_unkeyword(flag)
526 Messages without the specified keyword flag (string) set.
527 The following methods can be used to search for messages based on their
529 size:
530 is_larger(size)
532 Messages that are larger than the size (number) in octets
533 (bytes).
534 is_smaller(size)
536 Messages that are smaller than the size (number) in octets
537 (bytes).
538 The following methods can be used to search for messages based on their
540 age:
541 is_newer(age)
543 Messages that are newer than the age (number) in days.
544 is_older(age)
546 Messages that are older than the age (number) in days.
547 The following methods can be used to search for messages based on their
549 arrival or sent date, in the “day-month-year” form, where day is the day
550 of the month as a decimal number (01-31), month is the abbreviated month
551 ( “Jan”, “Feb”, “Mar”, “Apr”, “May”, “Jun”, “Jul”, “Aug”, “Sep”, “Oct”,
552 “Nov”, “Dec”) and year is the year as decimal number including the cen‐
553 tury (eg. 2007):
554 arrived_before(date)
556 messages that have arrived earlier than the date (string), where
557 date is in the “day-month-year” form.
558 arrived_on(date)
560 Messages that have arrived within the date (string), where date
561 is in the “day-month-year” form.
562 arrived_since(date)
564 Messages that have arrived within or later than the date
565 (string), where date is in the “day-month-year” form.
566 sent_before(date)
568 Messages that have been sent earlier than the date (string),
569 where date is in the “day-month-year” form.
570 sent_on(date)
572 Messages that have been sent within the date (string), where date
573 is in the “day-month-year” form.
574 sent_since(date)
576 Messages that have been sent within or later than the date
577 (string), where date is in the “day-month-year” form.
578 The following methods can be used to do case-insensitive searching, for
580 messages that contain a specific word or phrase:
581 contain_bcc(string)
583 Messages that contain the string (string) in the “Bcc” header
584 field.
585 contain_cc(string)
587 Messages that contain the string (string) in the “Cc” header
588 field.
589 contain_from(string)
591 Messages that contain the string (string) in the “From” header
592 field.
593 contain_subject(string)
595 Messages that contain the string (string) in the “Subject” header
596 field.
597 contain_to(string)
599 Messages that contain the string (string) in the “To” header
600 field.
601 contain_field(field, string)
603 Messages that contain the string (string) in the field (string)
604 header field.
605 contain_body(string)
607 Messages that contain the string (string) in the message body.
608 contain_message(string)
610 Messages that contain the string (string) in the message.
611 The following methods can be used to do case-sensitive searching, for
613 messages that match a specific regular expression pattern. The matching
614 mechanism that is used to support this is based on the Perl-compatible
615 regular expressions (PCRE), and more information about the patterns and
616 modifiers that can be used, is available in the relevant documentation at
617 http://pcre.org/original/doc/html/.
618 This way of searching is not supported by the IMAP protocol, and this
620 means that what actually happens under the hood, is that the relevant
621 parts of all the messages are downloaded and matched locally. It is
622 therefore recommended to use these methods with meta-searching (see fol‐
623 lowing section), in order to narrow down the set of messages that should
624 be searched, and thus minimize what will be downloaded.
625 Note that due to Lua using backslash ‘\’ as an escape character for its
627 strings, one has to use double backslashes in order to insert a single
628 backslash inside a regular expression pattern:
629 match_bcc(pattern)
631 Messages that match the regular expression pattern (string) in
632 the “Bcc” header field.
633 match_cc(pattern)
635 Messages that match the regular expression pattern (string) in
636 the “Cc” header field.
637 match_from(pattern)
639 Messages that match the regular expression pattern (string) in
640 the “From” header field.
641 match_subject(pattern)
643 Messages that match the regular expression pattern (string) in
644 the “Subject” header field.
645 match_to(pattern)
647 Messages that match the regular expression pattern (string) in
648 the “To” header field.
649 match_field(field, pattern)
651 Messages that match the regular expression pattern (string) in
652 the field (string) header field.
653 match_header(pattern)
655 Messages that match the regular expression pattern (string) in
656 the message header.
657 match_body(pattern)
659 Messages that match the regular expression pattern (string) in
660 the message body.
661 match_message(pattern)
663 Messages that match the regular expression pattern (string) in
664 the message.
665 The following method can be used to search for messages using user
667 queries based on the IMAP specification (RFC 3501 Section 6.4.4):
668 send_query(criteria)
670 Searches messages by sending an IMAP search query as described in
671 the search criteria (string).
672 Examples:
674 results = myaccount.mymailbox:select_all()
676 results = myaccount.mymailbox:is_new()
677 results = myaccount.mymailbox:is_recent()
678 results = myaccount.mymailbox:is_larger(100000)
679 results = myaccount.mymailbox:is_older(10)
680 results = myaccount.mymailbox:has_keyword('MyFlag')
681 results = myaccount.mymailbox:arrived_before('01-Jan-2007')
682 results = myaccount.mymailbox:sent_since('01-Jan-2007')
683 results = myaccount.mymailbox:contain_subject('test')
684 results = myaccount.mymailbox:contain_field('Sender', 'user@host')
685 results = myaccount.mymailbox:contain_body('hello world')
686 results = myaccount.mymailbox:match_from('.*(user1|user2)@host')
687 results = myaccount.mymailbox:send_query('ALL')
688 results = myaccount['mymailbox']:is_new()
690 results = myaccount['myfolder/mymailbox']:is_recent()
691
693 After one of more searching methods have been applied to one or more
694 mailboxes, the result contains all the necessary information, such as
695 which messages matched in which mailboxes. Using this result these mes‐
696 sages can be either searched further or processed in various way.
697 META-SEARCHING
699 The results of the searching methods can be searched further on in the
700 same way as searching is done in mailboxes. The difference is that
701 instead of doing the search in the whole mailbox, ie. in all the mes‐
702 sages, it is instead done only to those messages that were returned in a
703 previous search.
704 Examples:
706 results:match_message('^[Hh]ello world!?$')
708 myaccount.mymailbox:is_new():match_body('^[Ww]orld, hello!?$')
709 PROCESSING
711 The processing methods are applied to the results that searching
712 returned.
713 The following method can be used to delete messages in a mailbox:
715 delete_messages()
717 Deletes the messages that matched.
718 The following methods can be used to copy and move messages in a mailbox
720 at the same or different accounts. If the destination mailbox is in a
721 different account than the source mailbox, then the messages are down‐
722 loaded and then uploaded to the destination:
723 copy_messages(destination)
725 Copies the messages to the destination, which is a mailbox at an
726 account.
727 move_messages(destination)
729 Moves the messages to the destination, which is a mailbox at an
730 account.
731 The following methods can be used to mark messages in a mailbox:
733 mark_answered()
735 Marks the messages as answered.
736 mark_deleted()
738 Marks the messages for later removal.
739 mark_draft()
741 Marks the messages as draft.
742 mark_flagged()
744 Marks the messages for urgent/special attention.
745 mark_seen()
747 Marks the messages as read.
748 unmark_answered()
750 Unmarks the messages that have been marked as answered.
751 unmark_deleted()
753 Unmarks the messages that have been marked for later removal.
754 unmark_draft()
756 Unmarks the messages that have been marked as draft.
757 unmark_flagged()
759 Unmarks the messages that have been marked for urgent/special
760 attention.
761 unmark_seen()
763 Unmarks the messages that have been marked as read.
764 The following methods can be used to flag messages in a mailbox. The
766 standard system flags are “\Answered”, “\Deleted”, “\Draft”, “\Flagged”,
767 “\Seen”, while if the server supports it, new user keywords may be
768 defined:
769 add_flags(flags)
771 Adds the flags (table that contains strings) to the messages.
772 remove_flags(flags)
774 Removes the flags (table that contains strings) from the mes‐
775 sages.
776 replace_flags(flags)
778 Replaces the flags (table that contains strings) of the messages.
779 Examples:
781 results:delete_messages()
783 results:copy_messages(myaccount.myothermailbox)
784 results:move_messages(myotheraccount.mymailbox)
785 results:mark_seen()
786 results:unmark_flagged()
787 results:add_flags({ 'MyFlag', '\\Seen' })
788 results:remove_flags({ '\\Seen' })
789 results:move_messages(myotheraccount['myfolder/mymailbox'])
791
793 The messages that are residing in any mailbox can be also accessed, as a
794 whole or in parts. Messages can be accessed using their unique identi‐
795 fier (UID):
796 myaccount.mymailbox[22]
798 The UIDs of messages the user is interested in, are gained from the
800 results of searching:
801 results = account.INBOX:is_unseen()
803 for _, message in ipairs(results) do
804 mailbox, uid = table.unpack(message)
805 header = mailbox[uid]:fetch_header()
806 end
807 FETCHING
809 The following methods can be used to fetch parts of messages. The meth‐
810 ods return a string. The downloaded message parts are cached locally, so
811 they can be reused inside the same program session:
812 fetch_message()
814 Fetches the header and body of the message.
815 fetch_header()
817 Fetches the header of the message.
818 fetch_body()
820 Fetches the body of the messages.
821 fetch_field(field)
823 Fetches the specified header field (string) of the message.
824 fetch_part(part)
826 Fetches the specified part (string) of the message.
827 The following methods can be used to fetch details about the state of a
829 message:
830 fetch_flags()
832 Fetches the flags of the message. Returns a table of strings.
833 fetch_date()
835 Fetches the internal date of the message. Returns a string.
836 fetch_size()
838 Fetches the size of the message. Returns a number.
839 fetch_structure()
841 Fetches the body structure of the message. Returns a table that
842 has as keys the parts of the message, and as values a table that
843 has one mandatory element, the type (string) of the part, and two
844 optional elements, the size (number) and name (string) of the
845 part.
846 APPENDING
848 The following methods can be used to append a message to a mailbox:
849 append_message(message)
851 Appends the message (string) to the mailbox.
852 append_message(message, flags, date)
854 Appends the message (string) to the mailbox, setting the speci‐
855 fied flags (table of strings), as returned by fetch_flags(), and
856 date (string), as returned by fetch_date().
857 Examples:
859 myaccount.mymailbox[2]:fetch_message()
861 myaccount.mymailbox[3]:fetch_field('subject')
862 myaccount.mymailbox[5]:fetch_part('1.1')
863 myaccount['mymailbox'][7]:fetch_message()
865 myaccount['myfolder/mymailbox'][11]:fetch_message()
866 myaccount.mymailbox:append_message(message)
868
870 The following auxiliary functions are also available for convenience:
871 form_date(days)
873 Forms a date in “day-month-year” format that the system had
874 before the number of days (number), and returns it as a string.
875 get_password(prompt)
877 Displays the specified prompt (string), and reads a password,
878 while character echoing is turned off. Returns that password as
879 a string.
880 become_daemon(interval, commands)
882 Detaches the program from the controlling terminal and runs it in
883 the background as system daemon. The program will then repeatedly
884 poll at the specified interval (number) in seconds. Each time the
885 program wakes up, the commands (function) are executed.
886 become_daemon(interval, commands, nochdir, noclose)
888 Detaches the program from the controlling terminal and runs it in
889 the background as system daemon. The program will then repeatedly
890 poll at the specified interval (number) in seconds. Each time the
891 program wakes up, the commands (function) are executed.
892 If nochdir (boolean) is “true”, the current working directory is
894 not changed to the root directory (/). If noclose (boolean) is
895 “true”, the standard input, standard output and standard error
896 are not redirected to /dev/null.
897 pipe_to(command, data)
899 Executes the system's command (string) and sends the data
900 (string) to the standard input channel of the subprocess. Returns
901 a number, the exit status of the child process.
902 pipe_from(command)
904 Executes the system's command (string) and retrieves the data
905 from the standard output channel of the subprocess. Returns a
906 number, the exit status of the child process, and a string, the
907 output of the child process.
908 regex_search(pattern, string)
910 Implements Perl-compatible regular expressions (PCRE). The
911 pattern (string) is a PCRE pattern. The string (string) is the
912 subject string in which the pattern is matched against. Returns
913 at least a boolean, that denotes if the match was successful, and
914 any captures which are of string type. Note that due to Lua
915 using backslash ‘\’ as an escape character for its strings, one
916 has to use double backslashes in order to insert a single back‐
917 slash inside a regular expression pattern. For more information
918 on PCRE see http://pcre.org/original/doc/html/.
919 Examples:
921 date = form_date(14)
923 password = get_password('Enter password: ')
924 become_daemon(600, myfunction)
925 status = pipe_to('mycommandline', 'mydata')
926 status, data = pipe_from('mycommandline')
927 success, capture = regex_search('^(?i)pcre: (\\w)$', 'mystring')
928
930 See samples/config.lua and samples/extend.lua in the source code distri‐
931 bution.
932
934 HOME User's home directory.
935
937 imapfilter(1)
938BSD Aug 26, 2018 BSD