1IMAPFILTER_CONFIG(5)        BSD File Formats Manual       IMAPFILTER_CONFIG(5)
2

NAME

4     imapfilter_config — imapfilter configuration file
5

SYNOPSIS

7     $HOME/.imapfilter/config.lua
8

DESCRIPTION

10     imapfilter(1) uses the Lua programming language as a configuration and
11     extension language, therefore the configuration file is a Lua script.
12
13     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

CONVENTIONS

18     A brief description of the Lua values and types mentioned hereafter in
19     the manual page follows:
20
21         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
25         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
28         The type number represents real numbers.
29
30         The type string represents a sequence of characters and can be
31         defined using single quotes, double quotes or double square brackets.
32
33         The type table implements associative arrays, that is, arrays that
34         can be indexed not only with numbers, but with any value.
35
36         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

OPTIONS

40     Program's options are set using an already initialised table named
41     “options”, in the following manner:
42
43         options.timeout = 120
44         options.namespace = false
45         options.charset = 'ISO-8859-1'
46
47     Available options are:
48
49     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
54     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
60     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
66     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
75     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
80     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
87     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
93     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
97     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
107     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
116     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
127     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
141     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
147     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
159     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
168     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
174     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
180     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
185     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

ACCOUNTS

195     Accounts are initialized using the IMAP() function, and the details of
196     the connection are defined using an account table:
197
198         myaccount = IMAP {
199             server = 'imap.mail.server',
200             username = 'me',
201             password = 'secret',
202             ssl = 'auto'
203         }
204
205     An account table must have the following elements:
206
207     server  The hostname of the IMAP server to connect to.  It takes a string
208             as a value.
209
210     username
211             User's name.  It takes a string as a value.
212
213     An account table can also have the following optional elements:
214
215     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
221             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
226     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
231             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
240     port    The port to connect to.  It takes a number as a value.  Default
241             is “143” for imap and “993” for imaps.
242
243     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
247             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
253   LISTING
254     The following methods can be used on an account to list mailboxes in a
255     folder of an account:
256
257     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
262     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
267     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
272     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
279     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
286     Examples:
287
288         mailboxes, folders = myaccount:list_subscribed('myfolder')
289         mailboxes, folders = myaccount:list_all('myfolder/mysubfolder', '*')
290
291   MANIPULATING
292     The following methods can be used to manipulate mailboxes in an account:
293
294     create_mailbox(name)
295             Creates the name (string) mailbox.
296
297     delete_mailbox(name)
298             Deletes the name (string) mailbox.
299
300     rename_mailbox(oldname, newname)
301             Renames the oldname (string) mailbox to newname (string).
302
303     subscribe_mailbox(name)
304             Subscribes the name (string) mailbox.
305
306     unsubscribe_mailbox(name)
307             Unsubscribes the name (string) mailbox.
308
309     Examples:
310
311         myaccount:create_mailbox('mymailbox')
312         myaccount:subscribe_mailbox('mymailbox')
313         myaccount:unsubscribe_mailbox('myfolder/mymailbox')
314         myaccount:delete_mailbox('myfolder/mymailbox')
315

MAILBOXES

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
320         myaccount.mymailbox
321
322     If mailbox names don't only include letters, digits and underscores, or
323     begin with a digit, an alternative form must be used:
324
325         myaccount['mymailbox']
326
327     A mailbox inside a folder can be only accessed by using the alternative
328     form:
329
330         myaccount['myfolder/mymailbox']
331
332     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
337   CHECKING
338     The following methods can be used to check the status of a mailbox:
339
340     check_status()
341
342             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
348     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
360             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
369             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
375     Examples:
376
377         exist, unread, unseen, uidnext = myaccount.mymailbox:check_status()
378         update = myaccount.mymailbox:enter_idle()
379         update, event = myaccount.mymailbox:enter_idle()
380
381   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
388     The logical “or” is implemented using the ‘+’ operator:
389
390         results = myaccount.mymailbox:is_unseen() +
391                   myaccount.mymailbox:is_larger(100000)
392
393     The logical “and” is implemented using the ‘*’ operator:
394
395         results = myaccount.mymailbox:is_unseen() *
396                   myaccount.mymailbox:is_larger(100000)
397
398     The logical “not” is implemented using the ‘-’ operator:
399
400         results = myaccount.mymailbox:is_unseen() -
401                   myaccount.mymailbox:is_larger(100000)
402
403     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
408         results = myaccount.mymailbox:is_unseen() +
409                   myaccount.mymailbox:is_larger(100000) *
410                   myaccount.mymailbox:contain_subject('test')
411
412         results = ( myaccount.mymailbox:is_unseen() +
413                     myaccount.mymailbox:is_larger(100000) ) *
414                     myaccount.mymailbox:contain_subject('test')
415
416     The returned tables of the searching methods can also be stored in vari‐
417     ables and then further processed:
418
419         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
424     A composite filter that includes one or more simple rules can be defined:
425
426         myfilter = function ()
427                        return myaccount.mymailbox:is_unseen() +
428                               myaccount.mymailbox:is_larger(100000) *
429                               myaccount.mymailbox:contain_subject('test')
430                    end
431
432         results = myfilter()
433
434     Composite filters can may be more dynamic by adding arguments:
435
436         myfilter = function (mailbox, size, subject)
437                        return mailbox:is_unseen() +
438                               mailbox:is_larger(size) *
439                               mailbox:contain_subject(subject)
440                    end
441
442         results = myfilter(myaccount.mailbox, 100000, 'test')
443
444     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
449         results = myaccount.mymailbox:is_unseen() +
450                   myaccount.myothermailbox:is_larger(100000) +
451                   myotheraccount.myothermailbox:contain_subject('test')
452
453     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
460         {
461             { <myaccount.mymailbox>, 1 },
462             { <myaccount.mymailbox>, 3 },
463             { <myaccount.myothermailbox>, 5 },
464             { <myothermailbox.myothermailbox>, 7},
465             { ... },
466             ...
467         }
468
469     The following method can be used to get all messages in a mailbox:
470
471     select_all()
472             All messages.
473
474     The following methods can be used to search for messages that are in a
475     specific state:
476
477     is_answered()
478             Messages that have been answered.
479
480     is_deleted()
481             Messages that are marked for later removal.
482
483     is_draft()
484             Messages that have not completed composition.
485
486     is_flagged()
487             Messages that are flagged for urgent/special attention.
488
489     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
493     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
498     is_recent()
499             Messages that are recently arrived (this session is the first to
500             have been notified about these messages).
501
502     is_seen()
503             Messages that have been read.
504
505     is_unanswered()
506             Messages that have not been answered.
507
508     is_undeleted()
509             Messages that are not marked for later removal.
510
511     is_undraft()
512             Messages that have completed composition.
513
514     is_unflagged()
515             Messages that are not flagged for urgent/special attention.
516
517     is_unseen()
518             Messages that have not been read.
519
520     The following method can be used to search for messages that have a spe‐
521     cific keyword flag set:
522
523     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
528     The following methods can be used to search for messages based on their
529     size:
530
531     is_larger(size)
532             Messages that are larger than the size (number) in octets
533             (bytes).
534
535     is_smaller(size)
536             Messages that are smaller than the size (number) in octets
537             (bytes).
538
539     The following methods can be used to search for messages based on their
540     age:
541
542     is_newer(age)
543             Messages that are newer than the age (number) in days.
544
545     is_older(age)
546             Messages that are older than the age (number) in days.
547
548     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
555     arrived_before(date)
556             messages that have arrived earlier than the date (string), where
557             date is in the “day-month-year” form.
558
559     arrived_on(date)
560             Messages that have arrived within the date (string), where date
561             is in the “day-month-year” form.
562
563     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
567     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
571     sent_on(date)
572             Messages that have been sent within the date (string), where date
573             is in the “day-month-year” form.
574
575     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
579     The following methods can be used to do case-insensitive searching, for
580     messages that contain a specific word or phrase:
581
582     contain_bcc(string)
583             Messages that contain the string (string) in the “Bcc” header
584             field.
585
586     contain_cc(string)
587             Messages that contain the string (string) in the “Cc” header
588             field.
589
590     contain_from(string)
591             Messages that contain the string (string) in the “From” header
592             field.
593
594     contain_subject(string)
595             Messages that contain the string (string) in the “Subject” header
596             field.
597
598     contain_to(string)
599             Messages that contain the string (string) in the “To” header
600             field.
601
602     contain_field(field, string)
603             Messages that contain the string (string) in the field (string)
604             header field.
605
606     contain_body(string)
607             Messages that contain the string (string) in the message body.
608
609     contain_message(string)
610             Messages that contain the string (string) in the message.
611
612     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
619     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
626     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
630     match_bcc(pattern)
631             Messages that match the regular expression pattern (string) in
632             the “Bcc” header field.
633
634     match_cc(pattern)
635             Messages that match the regular expression pattern (string) in
636             the “Cc” header field.
637
638     match_from(pattern)
639             Messages that match the regular expression pattern (string) in
640             the “From” header field.
641
642     match_subject(pattern)
643             Messages that match the regular expression pattern (string) in
644             the “Subject” header field.
645
646     match_to(pattern)
647             Messages that match the regular expression pattern (string) in
648             the “To” header field.
649
650     match_field(field, pattern)
651             Messages that match the regular expression pattern (string) in
652             the field (string) header field.
653
654     match_header(pattern)
655             Messages that match the regular expression pattern (string) in
656             the message header.
657
658     match_body(pattern)
659             Messages that match the regular expression pattern (string) in
660             the message body.
661
662     match_message(pattern)
663             Messages that match the regular expression pattern (string) in
664             the message.
665
666     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
669     send_query(criteria)
670             Searches messages by sending an IMAP search query as described in
671             the search criteria (string).
672
673     Examples:
674
675         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
689         results = myaccount['mymailbox']:is_new()
690         results = myaccount['myfolder/mymailbox']:is_recent()
691

RESULTS

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
698   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
705     Examples:
706
707         results:match_message('^[Hh]ello world!?$')
708         myaccount.mymailbox:is_new():match_body('^[Ww]orld, hello!?$')
709
710   PROCESSING
711     The processing methods are applied to the results that searching
712     returned.
713
714     The following method can be used to delete messages in a mailbox:
715
716     delete_messages()
717             Deletes the messages that matched.
718
719     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
724     copy_messages(destination)
725             Copies the messages to the destination, which is a mailbox at an
726             account.
727
728     move_messages(destination)
729             Moves the messages to the destination, which is a mailbox at an
730             account.
731
732     The following methods can be used to mark messages in a mailbox:
733
734     mark_answered()
735             Marks the messages as answered.
736
737     mark_deleted()
738             Marks the messages for later removal.
739
740     mark_draft()
741             Marks the messages as draft.
742
743     mark_flagged()
744             Marks the messages for urgent/special attention.
745
746     mark_seen()
747             Marks the messages as read.
748
749     unmark_answered()
750             Unmarks the messages that have been marked as answered.
751
752     unmark_deleted()
753             Unmarks the messages that have been marked for later removal.
754
755     unmark_draft()
756             Unmarks the messages that have been marked as draft.
757
758     unmark_flagged()
759             Unmarks the messages that have been marked for urgent/special
760             attention.
761
762     unmark_seen()
763             Unmarks the messages that have been marked as read.
764
765     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
770     add_flags(flags)
771             Adds the flags (table that contains strings) to the messages.
772
773     remove_flags(flags)
774             Removes the flags (table that contains strings) from the mes‐
775             sages.
776
777     replace_flags(flags)
778             Replaces the flags (table that contains strings) of the messages.
779
780     Examples:
781
782         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
790         results:move_messages(myotheraccount['myfolder/mymailbox'])
791

MESSAGES

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
797         myaccount.mymailbox[22]
798
799     The UIDs of messages the user is interested in, are gained from the
800     results of searching:
801
802         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
808   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
813     fetch_message()
814             Fetches the header and body of the message.
815
816     fetch_header()
817             Fetches the header of the message.
818
819     fetch_body()
820             Fetches the body of the messages.
821
822     fetch_field(field)
823             Fetches the specified header field (string) of the message.
824
825     fetch_part(part)
826             Fetches the specified part (string) of the message.
827
828     The following methods can be used to fetch details about the state of a
829     message:
830
831     fetch_flags()
832             Fetches the flags of the message.  Returns a table of strings.
833
834     fetch_date()
835             Fetches the internal date of the message.  Returns a string.
836
837     fetch_size()
838             Fetches the size of the message.  Returns a number.
839
840     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
847   APPENDING
848     The following methods can be used to append a message to a mailbox:
849
850     append_message(message)
851             Appends the message (string) to the mailbox.
852
853     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
858     Examples:
859
860         myaccount.mymailbox[2]:fetch_message()
861         myaccount.mymailbox[3]:fetch_field('subject')
862         myaccount.mymailbox[5]:fetch_part('1.1')
863
864         myaccount['mymailbox'][7]:fetch_message()
865         myaccount['myfolder/mymailbox'][11]:fetch_message()
866
867         myaccount.mymailbox:append_message(message)
868

FUNCTIONS

870     The following auxiliary functions are also available for convenience:
871
872     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
876     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
881     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
887     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
893             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
898     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
903     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
909     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
920     Examples:
921
922         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

EXAMPLES

930     See samples/config.lua and samples/extend.lua in the source code distri‐
931     bution.
932

ENVIRONMENT

934     HOME    User's home directory.
935

SEE ALSO

937     imapfilter(1)
938
939BSD                              Aug 26, 2018                              BSD
Impressum