Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
IMAPFILTER_CONFIG(5)	  FreeBSD File Formats Manual	  IMAPFILTER_CONFIG(5)

NAME
     imapfilter_config -- imapfilter configuration file

SYNOPSIS
     $HOME/.imapfilter/config.lua

DESCRIPTION
     imapfilter(1) uses	the Lua	programming language as	a configuration	and
     extension language, therefore the configuration file is a Lua script.

     Although knowledge	of Lua is not required to use imapfilter(1), it	is
     nonetheless recommended, especially if one	wants to extend	it.  For more
     information on Lua	see http://www.lua.org/docs.html.

CONVENTIONS
     A brief description of the	Lua values and types mentioned hereafter in
     the manual	page follows:

	 The nil is the	type of	the value "nil", whose main property is	to be
	 different from	any other value; usually it represents the absence of
	 a useful value.

	 The boolean is	the type of the	values "true" and "false".  Both "nil"
	 and "false" make a condition false; any other value makes it true.

	 The type number represents real numbers.

	 The type string represents a sequence of characters and can be	de-
	 fined using single quotes, double quotes or double square brackets.

	 The type table	implements associative arrays, that is,	arrays that
	 can be	indexed	not only with numbers, but with	any value.

	 A function is a first-class value; it can be stored in	variables,
	 passed	as argument to other functions,	and returned as	a result.

OPTIONS
     Program's options are set using an	already	initialised table named
     "options",	in the following manner:

	 options.timeout = 120
	 options.namespace = false
	 options.charset = 'ISO-8859-1'

     Available options are:

     cache   When this option is enabled, parts	of messages are	cached locally
	     in	memory to avoid	being downloaded more than once.  The cache is
	     preserved for the current session only. This variable takes a
	     boolean as	a value. Default is "true".

     certificates
	     When this option is enabled, the server certificate can be	ac-
	     cepted and	stored,	in order to validate the authenticity of the
	     server in future connections. This	variable takes a boolean as a
	     value. Default is "true".

     charset
	     Indicates to the server the character set of the strings for the
	     searching methods.	 This variable takes a string as a value.  By
	     default no	character set is set, and thus plain ASCII should be
	     assumed by	the server.

     create  According to the IMAP specification, when trying to write a mes-
	     sage to a non-existent mailbox, the server	must send a hint to
	     the client, whether it should create the mailbox and try again or
	     not. However some IMAP servers don't follow the specification and
	     don't send	the correct response code to the client. By enabling
	     this option the client tries to create the	mailbox, despite of
	     the server's response. This variable takes	a boolean as a value.
	     Default is	"false".

     close   This option controls whether the currently	selected mailbox is
	     implicitly	closed at the end of each performed operation, thus
	     removing all messages that	are marked deleted. This variable
	     takes a boolean as	a value.  Default is "false".

     crammd5
	     When this option is enabled and the server	supports the Chal-
	     lenge-Response Authentication Mechanism (specifically CRAM-MD5),
	     this method will be used for user authentication instead of a
	     plaintext password	LOGIN.	This variable takes a boolean as a
	     value.  Default is	"true".

     expunge
	     Normally, messages	are marked for deletion	and are	actually
	     deleted when the mailbox is closed.  When this option is enabled,
	     messages are expunged immediately after being marked deleted.
	     This variable takes a boolean as a	value.	Default	is "true".

     info    When this options is enabled, a summary of	the program's actions
	     is	printed, while processing mailboxes.  This variable takes a
	     boolean as	a value.  Default is "true".

     keepalive
	     The time in minutes before	terminating and	re-issuing the IDLE
	     command, in order to keep alive the connection, by	resetting the
	     inactivity	timeout	of the server.	A standards compliant server
	     must have an inactivity timeout of	at least 30 minutes.  But it
	     may happen	that some IMAP servers don't respect that, or some in-
	     termediary	network	device has a shorter timeout.  By setting this
	     option the	above problem can be worked around. This variable
	     takes a number as a value.	Default	is "29"	minutes.

     limit   Some servers have problems	handling very long requests, but some
	     of	the requests that need to be sent can become quite long, be-
	     cause they	apply an action	for many messages at once.  When this
	     option is set, the	client will try	to break up these requests
	     into smaller requests, that each operates on fewer	messages at a
	     time.  A good value for this would	be "50".  This variable	takes
	     a number as a value.  Default is "0".  See	also the range option
	     which is related.

     namespace
	     When enabled, the program gets the	namespace of the user's	per-
	     sonal mailboxes, and applies automatically	the prefix and hierar-
	     chy delimiter to any mailboxes residing on	the mail server; the
	     user must use the `/' character as	the delimiter and "" (ie.
	     nothing) as the prefix, regardless	of the folder format of	the
	     mail server.  This	must be	disabled, if the user wants to manu-
	     ally specify mailbox names	(eg. because they are not part of the
	     user's personal namespace mailboxes).  This variable takes	a
	     boolean as	a value.  Default is "true".

     persist
	     When the recover option is	enabled, the recovery function tries
	     to	restore	the lost session, but if it fails to do	so it gives up
	     with an error.  In	some cases a temporary network problem might
	     cause the recovery	function to fail, but the connection could be
	     reestablished when	trying a bit later.  By	enabling this option,
	     the recovery function will	be called repeatedly after a timeout,
	     thus it will persist when trying to restore the session.  Note,
	     that this will case the execution of the configuration file to be
	     halted at the point of failure until the session is restored,
	     which can have side effects to other established sessions,	for
	     example they might	get dropped by the server after	a while.  This
	     variable takes a boolean as a value.  Default is "false".

     range   Some servers have problems	handling long sequence number ranges,
	     and by setting this option, the number of messages	included in
	     each range	can be limited.	 A good	value for this would be	"50".
	     This variable takes a number as a value.  By default no such
	     limit is imposed.	See also the limit option which	is related.

     recover
	     With this option it is possible to	control	the recovery function-
	     ality, which restores a session (the connection to	the server and
	     the IMAP state at the time), after	some unexpected	event takes
	     place.  Currently there are two types of events that can end ab-
	     normally a	session, and finally cause the program to terminate:
	     network errors, and the IMAP BYE response which a server can send
	     anytime.  When this option	is set to "all"	the recovery function
	     is	triggered by both types	of events, when	set to "errors"	only
	     in	the case of network errors, and	when set to "none" the mecha-
	     nism is completely	disabled.  Default is "all".

     reenter
	     When this option is enabled and the connection is recovered after
	     some unexpected event while in IDLE mode (see also	the recover
	     option), the client will re-enter IDLE mode.  But when this op-
	     tion is disabled, and after the connection	is recovered, the
	     client will not re-enter IDLE mode, and instead will continue to
	     execute the next line in the configuration	file, ie. the one af-
	     ter enter_idle().	Default	is "true".

     starttls
	     When this option is enabled and the server	supports the IMAP
	     STARTTLS extension, a TLS connection will be negotiated with the
	     mail server in the	beginning of the session.  This	variable takes
	     a boolean as value.  Default is "true".

     subscribe
	     By	enabling this option new mailboxes that	were automatically
	     created, get also subscribed; they	are set	active in order	for
	     IMAP clients to recognize them.  This variable takes a boolean as
	     a value.  Default is "false".

     timeout
	     The time in seconds for the program to wait for a mail server's
	     response.	If set to 0, the client	will block indefinitely.  This
	     variable takes a number as	a value.  Default is "60" seconds.

     wakeonany
	     By	enabling this option the IDLE command will return on any event
	     that is received from the server, and not just on the "RECENT"
	     and "EXISTS" events, that normally	indicate the arrival of	a new
	     message.  Examples	of other events	are "FETCH", which indicates
	     that the details of a message (eg.	its flags) have	been modified,
	     or	"EXPUNGE", which indicates that	a message has been deleted.
	     This variable takes a boolean as a	value.	Default	is "false".

ACCOUNTS
     Accounts are initialized using the	IMAP() function, and the details of
     the connection are	defined	using an account table:

	 myaccount = IMAP {
	     server = 'imap.mail.server',
	     username =	'me',
	     password =	'secret',
	     ssl = 'auto'
	 }

     An	account	table must have	the following elements:

     server  The hostname of the IMAP server to	connect	to.  It	takes a	string
	     as	a value.

     username
	     User's name.  It takes a string as	a value.

     An	account	table can also have the	following optional elements:

     password
	     User's secret keyword.  If	a password wasn't supplied the user
	     will be asked to enter one	interactively the first	time it	will
	     be	needed (unless oauth2 has been set).  It takes a string	as a
	     value.

	     Note that due to Lua using	backslash `\' as an escape character
	     for its strings, one has to use double backslashes	in order to
	     insert a single backslash,	and thus a backslash character inside
	     a password	might require four backslashes.

     oauth2  The OAuth2	string to use to authenticate if the server supports
	     the XOAUTH2 authentication	mechanism.  If the server does not
	     support it	and a password has been	also set, authentication will
	     be	attempted using	the password.  It takes	a string as a value.

	     Note that this requires that an OAuth client ID and client	secret
	     have been obtained, an OAuth2 token has been generated and	autho-
	     rized, a new access token has been	generated using	the refresh
	     token if the last access token has	expired, and an	OAuth2 string
	     has been generated	from the access	token.	The aforementioned
	     OAuth2 string is a	Base64 encoded string that should be set here.
	     For more information see
	     https://developers.google.com/gmail/xoauth2_protocol.

     port    The port to connect to.  It takes a number	as a value.  Default
	     is	"143" for imap and "993" for imaps.

     ssl     Forces an imaps connection	and specifies the SSL/TLS proto-
	     col/version to be used.  It takes a string	as a value, specifi-
	     cally one of: "auto", "tls1.2", "tls1.1", "tls1", "ssl3".

	     Note that the latest versions of the OpenSSL library have depre-
	     cated version specific methods, and the actual protocol version
	     used will be negotiated to	be the highest version mutually	sup-
	     ported by the client and the server.  This	is also	what the
	     "auto" value does.

   LISTING
     The following methods can be used on an account to	list mailboxes in a
     folder of an account:

     list_all(folder)
	     Lists all the available mailboxes in the folder (string), and re-
	     turns a table that	contains strings, the available	mailboxes, and
	     a table that contains strings, the	available folders.

     list_subscribed(folder)
	     Lists all the subscribed mailboxes	in the folder (string),	and
	     returns a table that contains strings, the	subscribed mailboxes,
	     and a table that contains strings,	the subscribed folders.

     The following methods can be used on an account to	list mailboxes,	using
     wildcards,	in a folder of an account.  The	`*' wildcard, matches any
     character and the `%' matches any character except	the folder delimiter,
     ie.  non-recursively:

     list_all(folder, mailbox)
	     Lists all the available mailboxes in the folder (string) with the
	     name mailbox (string), and	returns	a table	that contains strings,
	     the available mailboxes, and a table that contains	strings, the
	     available folders.	 Wildcards may only be used in the mailbox ar-
	     gument.

     list_subscribed(folder, mailbox)
	     Lists all the subscribed mailboxes	in the folder (string) with
	     the name mailbox (string),	and returns a table that contains
	     strings, the subscribed mailboxes,	and a table that contains
	     strings, the subscribed folders.  Wildcards may only be used in
	     the mailbox argument.

     Examples:

	 mailboxes, folders = myaccount:list_subscribed('myfolder')
	 mailboxes, folders = myaccount:list_all('myfolder/mysubfolder', '*')

   MANIPULATING
     The following methods can be used to manipulate mailboxes in an account:

     create_mailbox(name)
	     Creates the name (string) mailbox.

     delete_mailbox(name)
	     Deletes the name (string) mailbox.

     rename_mailbox(oldname, newname)
	     Renames the oldname (string) mailbox to newname (string).

     subscribe_mailbox(name)
	     Subscribes	the name (string) mailbox.

     unsubscribe_mailbox(name)
	     Unsubscribes the name (string) mailbox.

     Examples:

	 myaccount:create_mailbox('mymailbox')
	 myaccount:subscribe_mailbox('mymailbox')
	 myaccount:unsubscribe_mailbox('myfolder/mymailbox')
	 myaccount:delete_mailbox('myfolder/mymailbox')

MAILBOXES
     After an IMAP account has been initialized, mailboxes residing in that
     account can be accessed simply as elements	of the account table:

	 myaccount.mymailbox

     If	mailbox	names don't only include letters, digits and underscores, or
     begin with	a digit, an alternative	form must be used:

	 myaccount['mymailbox']

     A mailbox inside a	folder can be only accessed by using the alternative
     form:

	 myaccount['myfolder/mymailbox']

     The methods that are available for	an account (eg.	 list_all(),
     create_mailbox(), etc.) , are considered keywords and must	not be used as
     mailbox names, and	the same also applies for any string starting with an
     underscore, as they are considered	reserved.

   CHECKING
     The following methods can be used to check	the status of a	mailbox:

     check_status()

	     The check_status()	method gets the	current	status of a mailbox,
	     and returns four values of	number type: the total number of mes-
	     sages, the	number of recent messages, the number of unseen	mes-
	     sages in the mailbox, and the next	UID to be assigned to a	new
	     message in	the mailbox.

     enter_idle()
	     The enter_idle() method implements	the IMAP IDLE (RFC 2177) ex-
	     tension.  By using	this extension it's not	necessary to poll the
	     server for	changes	to the selected	mailbox	(ie.  using the
	     check_status() method), but instead the server sends an update
	     when there	is a change in the mailbox (eg.	in case	of new mail).
	     When the enter_idle() method has been called no more commands in
	     the configuration file are	executed until an update is received,
	     at	which point the	enter_idle() method returns.  For the
	     enter_idle() to work, the IDLE extension has to be	supported by
	     the IMAP server.

	     The enter_idle() method returns a value of	type boolean: "true"
	     if	the IDLE extension is supported	and there was a	update in the
	     mailbox, and "false" if the IDLE extension	is not supported, in
	     which case	the method returns immediately.	 When the aforemen-
	     tioned return value was "true", an	additional second value	of
	     type string is also returned, indicating the event	received from
	     the server, which is useful when the wakeonany option has been
	     enabled.

	     Apart from	an event received by the server, the SIGUSR1 or	SI-
	     GUSR2 signals can also interrupt the IDLE mode at any time, and
	     the execution of the configuration	file will then continue	from
	     the next line after the enter_idle().  In this case only the
	     value "true" is returned.

     Examples:

	 exist,	unread,	unseen,	uidnext	= myaccount.mymailbox:check_status()
	 update	= myaccount.mymailbox:enter_idle()
	 update, event = myaccount.mymailbox:enter_idle()

   SEARCHING
     The searching methods in this subsection can be applied to	any mailbox.
     They return a special form	of table, that contains	the messages that
     match the searching method.  This table can be combined with other	tables
     using logic theory. There are three available operations, that implement
     logical "or", logical "and" and logical "not".

     The logical "or" is implemented using the `+' operator:

	 results = myaccount.mymailbox:is_unseen() +
		   myaccount.mymailbox:is_larger(100000)

     The logical "and" is implemented using the	`*' operator:

	 results = myaccount.mymailbox:is_unseen() *
		   myaccount.mymailbox:is_larger(100000)

     The logical "not" is implemented using the	`-' operator:

	 results = myaccount.mymailbox:is_unseen() -
		   myaccount.mymailbox:is_larger(100000)

     The three logical operators can be	combined in the	same expression. The
     logical "and" has higher precedence than the logical "or" and the logical
     "not", with the latter two	having the same	precedence, and	parentheses
     may be used to change this	behaviour:

	 results = myaccount.mymailbox:is_unseen() +
		   myaccount.mymailbox:is_larger(100000) *
		   myaccount.mymailbox:contain_subject('test')

	 results = ( myaccount.mymailbox:is_unseen() +
		     myaccount.mymailbox:is_larger(100000) ) *
		     myaccount.mymailbox:contain_subject('test')

     The returned tables of the	searching methods can also be stored in	vari-
     ables and then further processed:

	 unseen	= myaccount.myaccount:is_unseen()
	 larger	= myaccount.mymailbox:is_larger(100000)
	 subject = myaccount.mymailbox:contain_subject('test')
	 results = unseen + larger * subject

     A composite filter	that includes one or more simple rules can be defined:

	 myfilter = function ()
			return myaccount.mymailbox:is_unseen() +
			       myaccount.mymailbox:is_larger(100000) *
			       myaccount.mymailbox:contain_subject('test')
		    end

	 results = myfilter()

     Composite filters can may be more dynamic by adding arguments:

	 myfilter = function (mailbox, size, subject)
			return mailbox:is_unseen() +
			       mailbox:is_larger(size) *
			       mailbox:contain_subject(subject)
		    end

	 results = myfilter(myaccount.mailbox, 100000, 'test')

     It	is also	possible to combine the	searching methods in different mail-
     boxes, either at the same or different accounts, for example when the
     same actions will be executed on messages residing	in different mailboxes
     or	accounts.

	 results = myaccount.mymailbox:is_unseen() +
		   myaccount.myothermailbox:is_larger(100000) +
		   myotheraccount.myothermailbox:contain_subject('test')

     And for those that	want to	know more about	the return values of the fol-
     lowing methods, it	is a table which contains tables with two values: the
     mailbox (table) the message belongs to, and the message UID (number)
     which points to the matching message.  For	examples on iterating these
     returned tables, or creating new tables of	this format (they are actually
     metatables	implementing sets), see	the samples/extend.lua file.

	 {
	     { <myaccount.mymailbox>, 1	},
	     { <myaccount.mymailbox>, 3	},
	     { <myaccount.myothermailbox>, 5 },
	     { <myothermailbox.myothermailbox>,	7},
	     { ... },
	     ...
	 }

     The following method can be used to get all messages in a mailbox:

     select_all()
	     All messages.

     The following methods can be used to search for messages that are in a
     specific state:

     is_answered()
	     Messages that have	been answered.

     is_deleted()
	     Messages that are marked for later	removal.

     is_draft()
	     Messages that have	not completed composition.

     is_flagged()
	     Messages that are flagged for urgent/special attention.

     is_new()
	     Messages that are recently	arrived	(this session is the first to
	     have been notified	about these messages) and have not been	read.

     is_old()
	     Messages that are not recently arrived (this session is not the
	     first to have been	notified about these messages) and have	not
	     been read.

     is_recent()
	     Messages that are recently	arrived	(this session is the first to
	     have been notified	about these messages).

     is_seen()
	     Messages that have	been read.

     is_unanswered()
	     Messages that have	not been answered.

     is_undeleted()
	     Messages that are not marked for later removal.

     is_undraft()
	     Messages that have	completed composition.

     is_unflagged()
	     Messages that are not flagged for urgent/special attention.

     is_unseen()
	     Messages that have	not been read.

     The following method can be used to search	for messages that have a spe-
     cific keyword flag	set:

     has_keyword(flag)
	     Messages with the specified keyword flag (string) set.
     has_unkeyword(flag)
	     Messages without the specified keyword flag (string) set.

     The following methods can be used to search for messages based on their
     size:

     is_larger(size)
	     Messages that are larger than the size (number) in	octets
	     (bytes).

     is_smaller(size)
	     Messages that are smaller than the	size (number) in octets
	     (bytes).

     The following methods can be used to search for messages based on their
     age:

     is_newer(age)
	     Messages that are newer than the age (number) in days.

     is_older(age)
	     Messages that are older than the age (number) in days.

     The following methods can be used to search for messages based on their
     arrival or	sent date, in the "day-month-year" form, where day is the day
     of	the month as a decimal number (01-31), month is	the abbreviated	month
     ( "Jan", "Feb", "Mar", "Apr", "May", "Jun", "Jul",	"Aug", "Sep", "Oct",
     "Nov", "Dec") and year is the year	as decimal number including the	cen-
     tury (eg. 2007):

     arrived_before(date)
	     messages that have	arrived	earlier	than the date (string),	where
	     date is in	the "day-month-year" form.

     arrived_on(date)
	     Messages that have	arrived	within the date	(string), where	date
	     is	in the "day-month-year"	form.

     arrived_since(date)
	     Messages that have	arrived	within or later	than the date
	     (string), where date is in	the "day-month-year" form.

     sent_before(date)
	     Messages that have	been sent earlier than the date	(string),
	     where date	is in the "day-month-year" form.

     sent_on(date)
	     Messages that have	been sent within the date (string), where date
	     is	in the "day-month-year"	form.

     sent_since(date)
	     Messages that have	been sent within or later than the date
	     (string), where date is in	the "day-month-year" form.

     The following methods can be used to do case-insensitive searching, for
     messages that contain a specific word or phrase:

     contain_bcc(string)
	     Messages that contain the string (string) in the "Bcc" header
	     field.

     contain_cc(string)
	     Messages that contain the string (string) in the "Cc" header
	     field.

     contain_from(string)
	     Messages that contain the string (string) in the "From" header
	     field.

     contain_subject(string)
	     Messages that contain the string (string) in the "Subject"	header
	     field.

     contain_to(string)
	     Messages that contain the string (string) in the "To" header
	     field.

     contain_field(field, string)
	     Messages that contain the string (string) in the field (string)
	     header field.

     contain_body(string)
	     Messages that contain the string (string) in the message body.

     contain_message(string)
	     Messages that contain the string (string) in the message.

     The following methods can be used to do case-sensitive searching, for
     messages that match a specific regular expression pattern.	The matching
     mechanism that is used to support this is based on	the Perl-compatible
     regular expressions (PCRE), and more information about the	patterns and
     modifiers that can	be used, is available in the relevant documentation at
     http://pcre.org/original/doc/html/.

     This way of searching is not supported by the IMAP	protocol, and this
     means that	what actually happens under the	hood, is that the relevant
     parts of all the messages are downloaded and matched locally.  It is
     therefore recommended to use these	methods	with meta-searching (see fol-
     lowing section), in order to narrow down the set of messages that should
     be	searched, and thus minimize what will be downloaded.

     Note that due to Lua using	backslash `\' as an escape character for its
     strings, one has to use double backslashes	in order to insert a single
     backslash inside a	regular	expression pattern:

     match_bcc(pattern)
	     Messages that match the regular expression	pattern	(string) in
	     the "Bcc" header field.

     match_cc(pattern)
	     Messages that match the regular expression	pattern	(string) in
	     the "Cc" header field.

     match_from(pattern)
	     Messages that match the regular expression	pattern	(string) in
	     the "From"	header field.

     match_subject(pattern)
	     Messages that match the regular expression	pattern	(string) in
	     the "Subject" header field.

     match_to(pattern)
	     Messages that match the regular expression	pattern	(string) in
	     the "To" header field.

     match_field(field,	pattern)
	     Messages that match the regular expression	pattern	(string) in
	     the field (string)	header field.

     match_header(pattern)
	     Messages that match the regular expression	pattern	(string) in
	     the message header.

     match_body(pattern)
	     Messages that match the regular expression	pattern	(string) in
	     the message body.

     match_message(pattern)
	     Messages that match the regular expression	pattern	(string) in
	     the message.

     The following method can be used to search	for messages using user
     queries based on the IMAP specification (RFC 3501 Section 6.4.4):

     send_query(criteria)
	     Searches messages by sending an IMAP search query as described in
	     the search	criteria (string).

     Examples:

	 results = myaccount.mymailbox:select_all()
	 results = myaccount.mymailbox:is_new()
	 results = myaccount.mymailbox:is_recent()
	 results = myaccount.mymailbox:is_larger(100000)
	 results = myaccount.mymailbox:is_older(10)
	 results = myaccount.mymailbox:has_keyword('MyFlag')
	 results = myaccount.mymailbox:arrived_before('01-Jan-2007')
	 results = myaccount.mymailbox:sent_since('01-Jan-2007')
	 results = myaccount.mymailbox:contain_subject('test')
	 results = myaccount.mymailbox:contain_field('Sender', 'user@host')
	 results = myaccount.mymailbox:contain_body('hello world')
	 results = myaccount.mymailbox:match_from('.*(user1|user2)@host')
	 results = myaccount.mymailbox:send_query('ALL')

	 results = myaccount['mymailbox']:is_new()
	 results = myaccount['myfolder/mymailbox']:is_recent()

RESULTS
     After one of more searching methods have been applied to one or more
     mailboxes,	the result contains all	the necessary information, such	as
     which messages matched in which mailboxes.	 Using this result these mes-
     sages can be either searched further or processed in various way.

   META-SEARCHING
     The results of the	searching methods can be searched further on in	the
     same way as searching is done in mailboxes.  The difference is that in-
     stead of doing the	search in the whole mailbox, ie. in all	the messages,
     it	is instead done	only to	those messages that were returned in a previ-
     ous search.

     Examples:

	 results:match_message('^[Hh]ello world!?$')
	 myaccount.mymailbox:is_new():match_body('^[Ww]orld, hello!?$')

   PROCESSING
     The processing methods are	applied	to the results that searching re-
     turned.

     The following method can be used to delete	messages in a mailbox:

     delete_messages()
	     Deletes the messages that matched.

     The following methods can be used to copy and move	messages in a mailbox
     at	the same or different accounts.	 If the	destination mailbox is in a
     different account than the	source mailbox,	then the messages are down-
     loaded and	then uploaded to the destination:

     copy_messages(destination)
	     Copies the	messages to the	destination, which is a	mailbox	at an
	     account.

     move_messages(destination)
	     Moves the messages	to the destination, which is a mailbox at an
	     account.

     The following methods can be used to mark messages	in a mailbox:

     mark_answered()
	     Marks the messages	as answered.

     mark_deleted()
	     Marks the messages	for later removal.

     mark_draft()
	     Marks the messages	as draft.

     mark_flagged()
	     Marks the messages	for urgent/special attention.

     mark_seen()
	     Marks the messages	as read.

     unmark_answered()
	     Unmarks the messages that have been marked	as answered.

     unmark_deleted()
	     Unmarks the messages that have been marked	for later removal.

     unmark_draft()
	     Unmarks the messages that have been marked	as draft.

     unmark_flagged()
	     Unmarks the messages that have been marked	for urgent/special at-
	     tention.

     unmark_seen()
	     Unmarks the messages that have been marked	as read.

     The following methods can be used to flag messages	in a mailbox. The
     standard system flags are "\Answered", "\Deleted",	"\Draft", "\Flagged",
     "\Seen", while if the server supports it, new user	keywords may be	de-
     fined:

     add_flags(flags)
	     Adds the flags (table that	contains strings) to the messages.

     remove_flags(flags)
	     Removes the flags (table that contains strings) from the mes-
	     sages.

     replace_flags(flags)
	     Replaces the flags	(table that contains strings) of the messages.

     Examples:

	 results:delete_messages()
	 results:copy_messages(myaccount.myothermailbox)
	 results:move_messages(myotheraccount.mymailbox)
	 results:mark_seen()
	 results:unmark_flagged()
	 results:add_flags({ 'MyFlag', '\\Seen'	})
	 results:remove_flags({	'\\Seen' })

	 results:move_messages(myotheraccount['myfolder/mymailbox'])

MESSAGES
     The messages that are residing in any mailbox can be also accessed, as a
     whole or in parts.	 Messages can be accessed using	their unique identi-
     fier (UID):

	 myaccount.mymailbox[22]

     The UIDs of messages the user is interested in, are gained	from the re-
     sults of searching:

	 results = account.INBOX:is_unseen()
	 for _,	message	in ipairs(results) do
	     mailbox, uid = table.unpack(message)
	     header = mailbox[uid]:fetch_header()
	 end

   FETCHING
     The following methods can be used to fetch	parts of messages.  The	meth-
     ods return	a string.  The downloaded message parts	are cached locally, so
     they can be reused	inside the same	program	session:

     fetch_message()
	     Fetches the header	and body of the	message.

     fetch_header()
	     Fetches the header	of the message.

     fetch_body()
	     Fetches the body of the messages.

     fetch_field(field)
	     Fetches the specified header field	(string) of the	message.

     fetch_part(part)
	     Fetches the specified part	(string) of the	message.

     The following methods can be used to fetch	details	about the state	of a
     message:

     fetch_flags()
	     Fetches the flags of the message.	Returns	a table	of strings.

     fetch_date()
	     Fetches the internal date of the message.	Returns	a string.

     fetch_size()
	     Fetches the size of the message.  Returns a number.

     fetch_structure()
	     Fetches the body structure	of the message.	Returns	a table	that
	     has as keys the parts of the message, and as values a table that
	     has one mandatory element,	the type (string) of the part, and two
	     optional elements,	the size (number) and name (string) of the
	     part.

   APPENDING
     The following methods can be used to append a message to a	mailbox:

     append_message(message)
	     Appends the message (string) to the mailbox.

     append_message(message, flags, date)
	     Appends the message (string) to the mailbox, setting the speci-
	     fied flags	(table of strings), as returned	by fetch_flags(), and
	     date (string), as returned	by fetch_date().

     Examples:

	 myaccount.mymailbox[2]:fetch_message()
	 myaccount.mymailbox[3]:fetch_field('subject')
	 myaccount.mymailbox[5]:fetch_part('1.1')

	 myaccount['mymailbox'][7]:fetch_message()
	 myaccount['myfolder/mymailbox'][11]:fetch_message()

	 myaccount.mymailbox:append_message(message)

FUNCTIONS
     The following auxiliary functions are also	available for convenience:

     form_date(days)
	     Forms a date in "day-month-year" format that the system had be-
	     fore the number of	days (number), and returns it as a string.

     get_password(prompt)
	     Displays the specified prompt (string), and reads a password,
	     while character echoing is	turned off.  Returns that password as
	     a string.

     become_daemon(interval, commands)
	     Detaches the program from the controlling terminal	and runs it in
	     the background as system daemon. The program will then repeatedly
	     poll at the specified interval (number) in	seconds. Each time the
	     program wakes up, the commands (function) are executed.

     become_daemon(interval, commands, nochdir,	noclose)
	     Detaches the program from the controlling terminal	and runs it in
	     the background as system daemon. The program will then repeatedly
	     poll at the specified interval (number) in	seconds. Each time the
	     program wakes up, the commands (function) are executed.

	     If	nochdir	(boolean) is "true", the current working directory is
	     not changed to the	root directory (/).  If	noclose	(boolean) is
	     "true", the standard input, standard output and standard error
	     are not redirected	to /dev/null.

     pipe_to(command, data)
	     Executes the system's command (string) and	sends the data
	     (string) to the standard input channel of the subprocess. Returns
	     a number, the exit	status of the child process.

     pipe_from(command)
	     Executes the system's command (string) and	retrieves the data
	     from the standard output channel of the subprocess.  Returns a
	     number, the exit status of	the child process, and a string, the
	     output of the child process.

     regex_search(pattern, string)
	     Implements	Perl-compatible	regular	expressions (PCRE). The
	     pattern (string) is a PCRE	pattern. The string (string) is	the
	     subject string in which the pattern is matched against. Returns
	     at	least a	boolean, that denotes if the match was successful, and
	     any captures which	are of string type.  Note that due to Lua us-
	     ing backslash `\' as an escape character for its strings, one has
	     to	use double backslashes in order	to insert a single backslash
	     inside a regular expression pattern.  For more information	on
	     PCRE see http://pcre.org/original/doc/html/.

     Examples:

	 date =	form_date(14)
	 password = get_password('Enter	password: ')
	 become_daemon(600, myfunction)
	 status	= pipe_to('mycommandline', 'mydata')
	 status, data =	pipe_from('mycommandline')
	 success, capture = regex_search('^(?i)pcre: (\\w)$', 'mystring')

EXAMPLES
     See samples/config.lua and	samples/extend.lua in the source code distri-
     bution.

ENVIRONMENT
     HOME    User's home directory.

SEE ALSO
     imapfilter(1)

FreeBSD	13.0			 Aug 26, 2018			  FreeBSD 13.0

NAME | SYNOPSIS | DESCRIPTION | CONVENTIONS | OPTIONS | ACCOUNTS | MAILBOXES | RESULTS | MESSAGES | FUNCTIONS | EXAMPLES | ENVIRONMENT | SEE ALSO

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=imapfilter_config&sektion=5&manpath=FreeBSD+12.2-RELEASE+and+Ports>

home | help