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 de‐
31 fined 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 ac‐
56 cepted and stored, to validate the authenticity of the server in
57 future connections. This variable takes a boolean as a value. De‐
58 fault 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
70 and don't send the correct response code to the client. By en‐
71 abling this option the client tries to create the mailbox, de‐
72 spite of the server's response. This variable takes a boolean as
73 a value. 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 expunge
81 Normally, messages are marked for deletion and are actually
82 deleted when the mailbox is closed. When this option is enabled,
83 messages are expunged immediately after being marked deleted.
84 This variable takes a boolean as a value. Default is “true”.
85 hostnames
87 When this option is enabled, the server hostname is validated, in
88 order to verify the client is talking to the correct server. This
89 variable takes a boolean as a value. Default is “true”.
90 info When this option is enabled, a summary of the program's actions
92 is printed, while processing mailboxes. This variable takes a
93 boolean as a value. Default is “true”.
94 keepalive
96 The time in minutes before terminating and re-issuing the IDLE
97 command, in order to keep alive the connection, by resetting the
98 inactivity timeout of the server. A standards compliant server
99 must have an inactivity timeout of at least 30 minutes. But some
100 IMAP servers might not respect that, or some intermediary network
101 device has a shorter timeout. By setting this option the above
102 problem can be worked around. This variable takes a number as a
103 value. Default is “29” minutes.
104 limit Some servers have problems handling very long requests, but some
106 of the requests that need to be sent can become quite long be‐
107 cause they apply an action for many messages at once. When this
108 option is set, the client will try to break up these requests
109 into smaller requests, that each operates on fewer messages at a
110 time. A good value for this would be “50”. This variable takes
111 a number as a value. Default is “0”. See also the range option
112 which is related.
113 namespace
115 When enabled, the program gets the namespace of the user's per‐
116 sonal mailboxes, and applies automatically the prefix and hierar‐
117 chy delimiter to any mailboxes residing on the mail server; the
118 user must use the ‘/’ character as the delimiter and “” (i.e.
119 nothing) as the prefix, regardless of the folder format of the
120 mail server. This must be disabled, if the user wants to manu‐
121 ally specify mailbox names (e.g. because they are not part of the
122 user's personal namespace mailboxes). This variable takes a
123 boolean as a value. Default is “true”.
124 range Some servers have problems handling long sequence number ranges,
126 and by setting this option, the number of messages included in
127 each range can be limited. A good value for this would be “50”.
128 This variable takes a number as a value. By default, no such
129 limit is imposed. See also the limit option which is related.
130 starttls
132 When this option is enabled and the server supports the IMAP
133 STARTTLS extension, a TLS connection will be negotiated with the
134 mail server in the beginning of the session. This variable takes
135 a boolean as value. Default is “true”.
136 subscribe
138 By enabling this option new mailboxes that were automatically
139 created, get also subscribed; they are set active in order for
140 IMAP clients to recognize them. This variable takes a boolean as
141 a value. Default is “false”.
142 timeout
144 The time in seconds for the program to wait for a mail server's
145 response. If set to 0, the client will block indefinitely. This
146 variable takes a number as a value. Default is “60” seconds.
147 wakeonany
149 By enabling this option, the IDLE command will return on any
150 event that is received from the server, and not just on the
151 “RECENT” and “EXISTS” events, that normally indicate the arrival
152 of a new message. Examples of other events are “FETCH”, which
153 indicates that the details of a message (e.g. its flags) have
154 been modified, or “EXPUNGE”, which indicates that a message has
155 been deleted. This variable takes a boolean as a value. Default
156 is “false”.
157
159 Accounts are initialized using the IMAP() function, and the details of
160 the connection are defined using an account table:
161 myaccount = IMAP {
163 server = 'imap.mail.server',
164 username = 'me',
165 password = 'secret',
166 ssl = 'auto'
167 }
168 An account table must have the following elements:
170 server The hostname of the IMAP server to connect to. It takes a string
172 as a value.
173 username
175 User's name. It takes a string as a value.
176 An account table can also have the following optional elements:
178 password
180 User's secret keyword. If a password wasn't supplied, the user
181 will be asked to enter one interactively the first time it will
182 be needed (unless oauth2 has been set). It takes a string as a
183 value.
184 Passwords can also be extracted during execution time from an en‐
186 crypted password vault. The samples/extend.lua file contains
187 such an example.
188 Note that due to Lua using backslash ‘\’ as an escape character
190 for its strings, one has to use double backslashes in order to
191 insert a single backslash, and thus a backslash character inside
192 a password might require four backslashes.
193 oauth2 The OAuth2 string to use to authenticate if the server supports
195 the XOAUTH2 authentication mechanism. If the server does not
196 support it and a password has also been set, authentication will
197 be attempted using the password. It takes a string as a value.
198 Note that this requires that an OAuth client ID and client secret
200 have been obtained, an OAuth2 token has been generated and autho‐
201 rized, a new access token has been generated using the refresh
202 token if the last access token has expired, and an OAuth2 string
203 has been generated from the access token. The aforementioned
204 OAuth2 string is a Base64 encoded string that should be set here.
205 For more information, see
206 https://developers.google.com/gmail/xoauth2_protocol.
207 The samples/extend.lua file contains an example of authentication
209 using OAuth2.
210 port The port to connect to. It takes a number as a value. Default
212 is “143” for imap and “993” for imaps.
213 ssl Forces an imaps connection and specifies the SSL/TLS proto‐
215 col/version to be used. It takes a string as a value, specifi‐
216 cally one of: “auto”, “tls1.2”, “tls1.1”, “tls1”, “ssl3”.
217 Note that the latest versions of the OpenSSL library have depre‐
219 cated version specific methods, and the actual protocol version
220 used, will be negotiated to be the highest version mutually sup‐
221 ported by the client and the server. This is also what the
222 “auto” value does.
223 LISTING
225 The following methods can be used on an account to list mailboxes in a
226 folder of an account:
227 list_all(folder)
229 Lists all the available mailboxes in the folder (string), and re‐
230 turns a table that contains strings, the available mailboxes, and
231 a table that contains strings, the available folders.
232 list_subscribed(folder)
234 Lists all the subscribed mailboxes in the folder (string), and
235 returns a table that contains strings, the subscribed mailboxes,
236 and a table that contains strings, the subscribed folders.
237 The following methods can be used on an account to list mailboxes, using
239 wildcards, in a folder of an account. The ‘*’ wildcard, matches any
240 character and the ‘%’ matches any character except the folder delimiter,
241 i.e. non-recursively:
242 list_all(folder, mailbox)
244 Lists all the available mailboxes in the folder (string) with the
245 name mailbox (string), and returns a table that contains strings,
246 the available mailboxes, and a table that contains strings, the
247 available folders. Wildcards may only be used in the mailbox ar‐
248 gument.
249 list_subscribed(folder, mailbox)
251 Lists all the subscribed mailboxes in the folder (string) with
252 the name mailbox (string), and returns a table that contains
253 strings, the subscribed mailboxes, and a table that contains
254 strings, the subscribed folders. Wildcards may only be used in
255 the mailbox argument.
256 Examples:
258 mailboxes, folders = myaccount:list_subscribed('myfolder')
260 mailboxes, folders = myaccount:list_all('myfolder/mysubfolder', '*')
261 MANIPULATING
263 The following methods can be used to manipulate mailboxes in an account:
264 create_mailbox(name)
266 Creates the name (string) mailbox.
267 delete_mailbox(name)
269 Deletes the name (string) mailbox.
270 rename_mailbox(oldname, newname)
272 Renames the oldname (string) mailbox to newname (string).
273 subscribe_mailbox(name)
275 Subscribes the name (string) mailbox.
276 unsubscribe_mailbox(name)
278 Unsubscribes the name (string) mailbox.
279 Examples:
281 myaccount:create_mailbox('mymailbox')
283 myaccount:subscribe_mailbox('mymailbox')
284 myaccount:unsubscribe_mailbox('myfolder/mymailbox')
285 myaccount:delete_mailbox('myfolder/mymailbox')
286
288 After an IMAP account has been initialized, mailboxes residing in that
289 account can be accessed simply as elements of the account table:
290 myaccount.mymailbox
292 If mailbox names don't only include letters, digits and underscores, or
294 begin with a digit, an alternative form must be used:
295 myaccount['mymailbox']
297 A mailbox inside a folder can be only accessed by using the alternative
299 form:
300 myaccount['myfolder/mymailbox']
302 The methods that are available for an account (e.g. list_all(),
304 create_mailbox(), etc.) , are considered keywords and must not be used as
305 mailbox names, and the same also applies for any string starting with an
306 underscore, as they are considered reserved.
307 CHECKING
309 The following methods can be used to check the status of a mailbox:
310 check_status()
312 The check_status() method gets the current status of a mailbox,
314 and returns four values of number type: the total number of mes‐
315 sages, the number of recent messages, the number of unseen mes‐
316 sages in the mailbox, and the next UID to be assigned to a new
317 message in the mailbox.
318 enter_idle()
320 The enter_idle() method implements the IMAP IDLE (RFC 2177) ex‐
321 tension. By using this extension it's not necessary to poll the
322 server for changes to the selected mailbox (i.e. using the
323 check_status() method), but instead the server sends an update
324 when there is a change in the mailbox (e.g. in case of new mail).
325 When the enter_idle() method has been called no more commands in
326 the configuration file are executed until an update is received,
327 at which point the enter_idle() method returns. For the
328 enter_idle() to work, the IDLE extension has to be supported by
329 the IMAP server.
330 The enter_idle() method returns a value of type boolean: “true”
332 if the IDLE extension is supported and there was an update in the
333 mailbox, and “false” if the IDLE extension is not supported, in
334 which case the method returns immediately. When the aforemen‐
335 tioned return value was “true”, an additional second value of
336 type string is also returned, indicating the event received from
337 the server, which is useful when the wakeonany option has been
338 enabled.
339 Apart from an event received by the server, the SIGUSR1 or SI‐
341 GUSR2 signals can also interrupt the IDLE mode at any time, and
342 the execution of the configuration file will then continue from
343 the next line after the enter_idle(). In this case, only the
344 value “true” is returned.
345 Examples:
347 exist, unread, unseen, uidnext = myaccount.mymailbox:check_status()
349 update = myaccount.mymailbox:enter_idle()
350 update, event = myaccount.mymailbox:enter_idle()
351 SEARCHING
353 The searching methods in this subsection can be applied to any mailbox.
354 They return a special form of table, that contains the messages that
355 match the searching method. This table can be combined with other tables
356 using logic theory. There are three available operations, that implement
357 logical “or”, logical “and” and logical “not”.
358 The logical “or” is implemented using the ‘+’ operator:
360 results = myaccount.mymailbox:is_unseen() +
362 myaccount.mymailbox:is_larger(100000)
363 The logical “and” is implemented using the ‘*’ operator:
365 results = myaccount.mymailbox:is_unseen() *
367 myaccount.mymailbox:is_larger(100000)
368 The logical “not” is implemented using the ‘-’ operator:
370 results = myaccount.mymailbox:is_unseen() -
372 myaccount.mymailbox:is_larger(100000)
373 The three logical operators can be combined in the same expression. The
375 logical “and” has higher precedence than the logical “or” and the logical
376 “not”, with the latter two having the same precedence, and parentheses
377 may be used to change this behaviour:
378 results = myaccount.mymailbox:is_unseen() +
380 myaccount.mymailbox:is_larger(100000) *
381 myaccount.mymailbox:contain_subject('test')
382 results = ( myaccount.mymailbox:is_unseen() +
384 myaccount.mymailbox:is_larger(100000) ) *
385 myaccount.mymailbox:contain_subject('test')
386 The returned tables of the searching methods can also be stored in vari‐
388 ables and then further processed:
389 unseen = myaccount.mymailbox:is_unseen()
391 larger = myaccount.mymailbox:is_larger(100000)
392 subject = myaccount.mymailbox:contain_subject('test')
393 results = unseen + larger * subject
394 A composite filter that includes one or more simple rules can be defined:
396 myfilter = function ()
398 return myaccount.mymailbox:is_unseen() +
399 myaccount.mymailbox:is_larger(100000) *
400 myaccount.mymailbox:contain_subject('test')
401 end
402 results = myfilter()
404 Composite filters can may be more dynamic by adding arguments:
406 myfilter = function (mailbox, size, subject)
408 return mailbox:is_unseen() +
409 mailbox:is_larger(size) *
410 mailbox:contain_subject(subject)
411 end
412 results = myfilter(myaccount.mailbox, 100000, 'test')
414 It is also possible to combine the searching methods in different mail‐
416 boxes, either at the same or different accounts, for example when the
417 same actions will be executed on messages residing in different mailboxes
418 or accounts.
419 results = myaccount.mymailbox:is_unseen() +
421 myaccount.myothermailbox:is_larger(100000) +
422 myotheraccount.myothermailbox:contain_subject('test')
423 And for those that want to know more about the return values of the fol‐
425 lowing methods, it is a table which contains tables with two values: the
426 mailbox (table) the message belongs to, and the message UID (number)
427 which points to the matching message. For examples on iterating these
428 returned tables, or creating new tables of this format (they are actually
429 metatables implementing sets), see the samples/extend.lua file.
430 {
432 { <myaccount.mymailbox>, 1 },
433 { <myaccount.mymailbox>, 3 },
434 { <myaccount.myothermailbox>, 5 },
435 { <myothermailbox.myothermailbox>, 7},
436 { ... },
437 ...
438 }
439 The following method can be used to get all messages in a mailbox:
441 select_all()
443 All messages.
444 The following methods can be used to search for messages that are in a
446 specific state:
447 is_answered()
449 Messages that have been answered.
450 is_deleted()
452 Messages that are marked for later removal.
453 is_draft()
455 Messages that have not completed composition.
456 is_flagged()
458 Messages that are flagged for urgent/special attention.
459 is_new()
461 Messages that are recently arrived (this session is the first to
462 have been notified about these messages) and have not been read.
463 is_old()
465 Messages that are not recently arrived (this session is not the
466 first to have been notified about these messages) and have not
467 been read.
468 is_recent()
470 Messages that are recently arrived (this session is the first to
471 have been notified about these messages).
472 is_seen()
474 Messages that have been read.
475 is_unanswered()
477 Messages that have not been answered.
478 is_undeleted()
480 Messages that are not marked for later removal.
481 is_undraft()
483 Messages that have completed composition.
484 is_unflagged()
486 Messages that are not flagged for urgent/special attention.
487 is_unseen()
489 Messages that have not been read.
490 The following method can be used to search for messages that have a spe‐
492 cific keyword flag set:
493 has_keyword(flag)
495 Messages with the specified keyword flag (string) set.
496 has_unkeyword(flag)
497 Messages without the specified keyword flag (string) set.
498 The following methods can be used to search for messages based on their
500 size:
501 is_larger(size)
503 Messages that are larger than the size (number) in octets
504 (bytes).
505 is_smaller(size)
507 Messages that are smaller than the size (number) in octets
508 (bytes).
509 The following methods can be used to search for messages based on their
511 age:
512 is_newer(age)
514 Messages that are newer than the age (number) in days.
515 is_older(age)
517 Messages that are older than the age (number) in days.
518 The following methods can be used to search for messages based on their
520 arrival or sent date, in the “day-month-year” form, where day is the day
521 of the month as a decimal number (01-31), month is the abbreviated month
522 ( “Jan”, “Feb”, “Mar”, “Apr”, “May”, “Jun”, “Jul”, “Aug”, “Sep”, “Oct”,
523 “Nov”, “Dec”) and year is the year as decimal number including the cen‐
524 tury (e.g. 2007):
525 arrived_before(date)
527 messages that have arrived earlier than the date (string), where
528 date is in the “day-month-year” form.
529 arrived_on(date)
531 Messages that have arrived within the date (string), where date
532 is in the “day-month-year” form.
533 arrived_since(date)
535 Messages that have arrived within or later than the date
536 (string), where date is in the “day-month-year” form.
537 sent_before(date)
539 Messages that have been sent earlier than the date (string),
540 where date is in the “day-month-year” form.
541 sent_on(date)
543 Messages that have been sent within the date (string), where date
544 is in the “day-month-year” form.
545 sent_since(date)
547 Messages that have been sent within or later than the date
548 (string), where date is in the “day-month-year” form.
549 The following methods can be used to do case-insensitive searching, for
551 messages that contain a specific word or phrase:
552 contain_bcc(string)
554 Messages that contain the string (string) in the “Bcc” header
555 field.
556 contain_cc(string)
558 Messages that contain the string (string) in the “Cc” header
559 field.
560 contain_from(string)
562 Messages that contain the string (string) in the “From” header
563 field.
564 contain_subject(string)
566 Messages that contain the string (string) in the “Subject” header
567 field.
568 contain_to(string)
570 Messages that contain the string (string) in the “To” header
571 field.
572 contain_field(field, string)
574 Messages that contain the string (string) in the field (string)
575 header field.
576 contain_body(string)
578 Messages that contain the string (string) in the message body.
579 contain_message(string)
581 Messages that contain the string (string) in the message.
582 The following methods can be used to do case-sensitive searching, for
584 messages that match a specific regular expression pattern. The matching
585 mechanism that is used to support this is based on the Perl-compatible
586 regular expressions (PCRE), and more information about the patterns and
587 modifiers that can be used, is available in the relevant documentation at
588 http://pcre.org/original/doc/html/.
589 This way of searching is not supported by the IMAP protocol, and this
591 means that what actually happens under the hood, is that the relevant
592 parts of all the messages are downloaded and matched locally. It is
593 therefore recommended to use these methods with meta-searching (see fol‐
594 lowing section), in order to narrow down the set of messages that should
595 be searched, and thus minimize what will be downloaded.
596 Note that due to Lua using backslash ‘\’ as an escape character for its
598 strings, one has to use double backslashes in order to insert a single
599 backslash inside a regular expression pattern:
600 match_bcc(pattern)
602 Messages that match the regular expression pattern (string) in
603 the “Bcc” header field.
604 match_cc(pattern)
606 Messages that match the regular expression pattern (string) in
607 the “Cc” header field.
608 match_from(pattern)
610 Messages that match the regular expression pattern (string) in
611 the “From” header field.
612 match_subject(pattern)
614 Messages that match the regular expression pattern (string) in
615 the “Subject” header field.
616 match_to(pattern)
618 Messages that match the regular expression pattern (string) in
619 the “To” header field.
620 match_field(field, pattern)
622 Messages that match the regular expression pattern (string) in
623 the field (string) header field.
624 match_header(pattern)
626 Messages that match the regular expression pattern (string) in
627 the message header.
628 match_body(pattern)
630 Messages that match the regular expression pattern (string) in
631 the message body.
632 match_message(pattern)
634 Messages that match the regular expression pattern (string) in
635 the message.
636 The following method can be used to search for messages using user
638 queries based on the IMAP specification (RFC 3501 Section 6.4.4):
639 send_query(criteria)
641 Searches messages by sending an IMAP search query as described in
642 the search criteria (string).
643 Examples:
645 results = myaccount.mymailbox:select_all()
647 results = myaccount.mymailbox:is_new()
648 results = myaccount.mymailbox:is_recent()
649 results = myaccount.mymailbox:is_larger(100000)
650 results = myaccount.mymailbox:is_older(10)
651 results = myaccount.mymailbox:has_keyword('MyFlag')
652 results = myaccount.mymailbox:arrived_before('01-Jan-2007')
653 results = myaccount.mymailbox:sent_since('01-Jan-2007')
654 results = myaccount.mymailbox:contain_subject('test')
655 results = myaccount.mymailbox:contain_field('Sender', 'user@host')
656 results = myaccount.mymailbox:contain_body('hello world')
657 results = myaccount.mymailbox:match_from('.*(user1|user2)@host')
658 results = myaccount.mymailbox:send_query('ALL')
659 results = myaccount['mymailbox']:is_new()
661 results = myaccount['myfolder/mymailbox']:is_recent()
662
664 After one of more searching methods have been applied to one or more
665 mailboxes, the result contains all the necessary information, such as
666 which messages matched in which mailboxes. Using this result these mes‐
667 sages can be either searched further or processed in various way.
668 META-SEARCHING
670 The results of the searching methods can be searched further on in the
671 same way as searching is done in mailboxes. The difference is that in‐
672 stead of doing the search in the whole mailbox, ie. in all the messages,
673 it is instead done only to those messages that were returned in a previ‐
674 ous search.
675 Examples:
677 results:match_message('^[Hh]ello world!?$')
679 myaccount.mymailbox:is_new():match_body('^[Ww]orld, hello!?$')
680 PROCESSING
682 The processing methods are applied to the results that searching re‐
683 turned.
684 The following method can be used to delete messages in a mailbox:
686 delete_messages()
688 Deletes the messages that matched.
689 The following methods can be used to copy and move messages in a mailbox
691 at the same or different accounts. If the destination mailbox is in a
692 different account than the source mailbox, then the messages are down‐
693 loaded and then uploaded to the destination:
694 copy_messages(destination)
696 Copies the messages to the destination, which is a mailbox at an
697 account.
698 move_messages(destination)
700 Moves the messages to the destination, which is a mailbox at an
701 account.
702 The following methods can be used to mark messages in a mailbox:
704 mark_answered()
706 Marks the messages as answered.
707 mark_deleted()
709 Marks the messages for later removal.
710 mark_draft()
712 Marks the messages as draft.
713 mark_flagged()
715 Marks the messages for urgent/special attention.
716 mark_seen()
718 Marks the messages as read.
719 unmark_answered()
721 Unmarks the messages that have been marked as answered.
722 unmark_deleted()
724 Unmarks the messages that have been marked for later removal.
725 unmark_draft()
727 Unmarks the messages that have been marked as draft.
728 unmark_flagged()
730 Unmarks the messages that have been marked for urgent/special at‐
731 tention.
732 unmark_seen()
734 Unmarks the messages that have been marked as read.
735 The following methods can be used to flag messages in a mailbox. The
737 standard system flags are “\Answered”, “\Deleted”, “\Draft”, “\Flagged”,
738 “\Seen”, while, if the server supports it, new user keywords may be de‐
739 fined:
740 add_flags(flags)
742 Adds the flags (table that contains strings) to the messages.
743 remove_flags(flags)
745 Removes the flags (table that contains strings) from the mes‐
746 sages.
747 replace_flags(flags)
749 Replaces the flags (table that contains strings) of the messages.
750 Examples:
752 results:delete_messages()
754 results:copy_messages(myaccount.myothermailbox)
755 results:move_messages(myotheraccount.mymailbox)
756 results:mark_seen()
757 results:unmark_flagged()
758 results:add_flags({ 'MyFlag', '\\Seen' })
759 results:remove_flags({ '\\Seen' })
760 results:move_messages(myotheraccount['myfolder/mymailbox'])
762
764 The messages that are residing in any mailbox can also be accessed, as a
765 whole or in parts. Messages can be accessed using their unique identi‐
766 fier (UID):
767 myaccount.mymailbox[22]
769 The UIDs of messages the user is interested in, are gained from the re‐
771 sults of searching:
772 results = account.INBOX:is_unseen()
774 for _, message in ipairs(results) do
775 mailbox, uid = table.unpack(message)
776 header = mailbox[uid]:fetch_header()
777 end
778 FETCHING
780 The following methods can be used to fetch parts of messages. The meth‐
781 ods return a string. The downloaded message parts are cached locally, so
782 they can be reused inside the same program session:
783 fetch_message()
785 Fetches the header and body of the message.
786 fetch_header()
788 Fetches the header of the message.
789 fetch_body()
791 Fetches the body of the messages.
792 fetch_field(field)
794 Fetches the specified header field (string) of the message.
795 fetch_part(part)
797 Fetches the specified part (string) of the message.
798 The following methods can be used to fetch details about the state of a
800 message:
801 fetch_flags()
803 Fetches the flags of the message. Returns a table of strings.
804 fetch_date()
806 Fetches the internal date of the message. Returns a string.
807 fetch_size()
809 Fetches the size of the message. Returns a number.
810 fetch_structure()
812 Fetches the body structure of the message. Returns a table that
813 has as keys the parts of the message, and as values a table that
814 has one mandatory element, the type (string) of the part, and two
815 optional elements, the size (number) and name (string) of the
816 part.
817 APPENDING
819 The following methods can be used to append a message to a mailbox:
820 append_message(message)
822 Appends the message (string) to the mailbox.
823 append_message(message, flags, date)
825 Appends the message (string) to the mailbox, setting the speci‐
826 fied flags (table of strings), as returned by fetch_flags(), and
827 date (string), as returned by fetch_date().
828 Examples:
830 myaccount.mymailbox[2]:fetch_message()
832 myaccount.mymailbox[3]:fetch_field('subject')
833 myaccount.mymailbox[5]:fetch_part('1.1')
834 myaccount['mymailbox'][7]:fetch_message()
836 myaccount['myfolder/mymailbox'][11]:fetch_message()
837 myaccount.mymailbox:append_message(message)
839
841 The following auxiliary functions are also available for convenience:
842 form_date(days)
844 Forms a date in “day-month-year” format that the system had be‐
845 fore the number of days (number), and returns it as a string.
846 get_password(prompt)
848 Displays the specified prompt (string), and reads a password,
849 while character echoing is turned off. Returns that password as
850 a string.
851 become_daemon(interval, commands)
853 become_daemon(interval, commands, nochdir)
854 become_daemon(interval, commands, nochdir, noclose)
855 Detaches the program from the controlling terminal and runs it in
856 the background as system daemon. The program will then repeatedly
857 poll at the specified interval (number) in seconds. Each time the
858 program wakes up, the commands (function) are executed.
859 If nochdir (boolean) is “true”, the current working directory is
861 not changed to the root directory (/).
862 If noclose (boolean) is “true”, the standard input, standard out‐
864 put and standard error are not redirected to /dev/null.
865 pipe_to(command, data)
867 Executes the system's command (string) and sends the data
868 (string) to the standard input channel of the subprocess. Returns
869 a number, the exit status of the child process.
870 pipe_from(command)
872 Executes the system's command (string) and retrieves the data
873 from the standard output channel of the subprocess. Returns a
874 number, the exit status of the child process, and a string, the
875 output of the child process.
876 regex_search(pattern, string)
878 Implements Perl-compatible regular expressions (PCRE). The
879 pattern (string) is a PCRE pattern. The string (string) is the
880 subject string in which the pattern is matched against. Returns
881 at least a boolean, that denotes if the match was successful, and
882 any captures which are of string type. Note that due to Lua us‐
883 ing backslash ‘\’ as an escape character for its strings, one has
884 to use double backslashes in order to insert a single backslash
885 inside a regular expression pattern. For more information on
886 PCRE see http://pcre.org/original/doc/html/.
887 sleep(interval)
889 Delay for the specified interval (number) in seconds.
890 recover(commands)
892 recover(commands, retries)
893 Protects the commands (function) executed from raising an error.
894 Whenever an error is raised, it sleeps for a few seconds (using
895 exponential backoff up to some upper limit), and then re-executes
896 the commands (function) from start.
897 If the maximum count of retries (number) is specified, it will
899 retry up to the specified number of times, otherwise it will
900 never give up.
901 Returns the status code of the execution as the first result,
903 “true” if it succeeded or “false” if it failed. If it succeeded,
904 it returns all values the commands (function) returned as addi‐
905 tional results. If it failed, it returns the error as an addi‐
906 tional result.
907 Examples:
909 date = form_date(14)
911 password = get_password('Enter password: ')
912 become_daemon(600, myfunction)
913 status = pipe_to('mycommandline', 'mydata')
914 status, data = pipe_from('mycommandline')
915 success, capture = regex_search('^(?i)pcre: (\\w)$', 'mystring')
916 sleep(300)
917 recover(myfunction, 5)
918 For more examples, see the samples/extend.lua file.
920
922 See samples/config.lua and samples/extend.lua in the source code distri‐
923 bution.
924
926 HOME User's home directory.
927
929 imapfilter(1)
930BSD Jan 6, 2023 BSD