Lua: mail-lua

mail-lua is a plugin that can be loaded to provide API for mail storage Lua plugins.

mail-lua provides a common script to be used in mail storage instead of per-plugin scripts.

See mail-lua plugin.

Initialization

When mail user is created, a script is loaded if present as mail_lua_script() and mail_user_created() is called if present in script.

De-initialization

On deinitialization, mail_user_deinit_pre() is called first, if present, followed by mail_user_deinit().

C API

void dlua_register_mail_storage(struct dlua_script *script)

Parameters:

• script: dlua_script to add mail storage.

Register storage Lua interface to script context.

bool mail_lua_plugin_get_script(struct mail_user *user, struct dlua_script **script_r)

Parameters:

• user: mail_user
• script: dlua_script

Returns script context if available. If FALSE is returned, no Lua script has been loaded, and you should optionally deal this yourself.

void dlua_push_mail_user(struct dlua_script *script, struct mail_user *user)

Parameters:

• script: dlua_script
• user: mail_user

Pushes a mail user on top of stack.

void dlua_push_mailbox(struct dlua_script *script, struct mailbox *box)

Parameters:

• script: dlua_script
• mailbox: mailbox

Pushes a mailbox on top of stack.

void dlua_push_mail(struct dlua_script *script, struct mail* mail)

Parameters:

• script: dlua_script
• mail: mail

Pushes a mail on top of stack.

Lua API

Object dovecot.storage

enum dovecot.storage.STATUS_MESSAGES

enum dovecot.storage.STATUS_RECENT

enum dovecot.storage.STATUS_UIDNEXT

enum dovecot.storage.STATUS_UIDVALIDITY

enum dovecot.storage.STATUS_UNSEEN

enum dovecot.storage.STATUS_FIRST_UNSEEN_SEQ

enum dovecot.storage.STATUS_KEYWORDS

enum dovecot.storage.STATUS_HIGHESTMODSEQ

enum dovecot.storage.STATUS_PERMANENT_FLAGS

enum dovecot.storage.FIRST_RECENT_UID

enum dovecot.storage.STATUS_HIGHESTPVTMODSEQ

enum dovecot.storage.MAILBOX_FLAG_READONLY

enum dovecot.storage.MAILBOX_FLAG_SAVEONLY

enum dovecot.storage.MAILBOX_FLAG_DROP_RECENT

enum dovecot.storage.MAILBOX_FLAG_NO_INDEX_FILES

enum dovecot.storage.MAILBOX_FLAG_KEEP_LOCKED

enum dovecot.storage.MAILBOX_FLAG_IGNORE_ACLS

enum dovecot.storage.MAILBOX_FLAG_AUTO_CREATE

enum dovecot.storage.MAILBOX_FLAG_AUTO_SUBSCRIBE

enum dovecot.storage.MAILBOX_SYNC_FLAG_FULL_READ

enum dovecot.storage.MAILBOX_SYNC_FLAG_FULL_WRITE

enum dovecot.storage.MAILBOX_SYNC_FLAG_FAST

enum dovecot.storage.MAILBOX_SYNC_FLAG_NO_EXPUNGES

enum dovecot.storage.MAILBOX_SYNC_FLAG_FIX_INCONSISTENT

enum dovecot.storage.MAILBOX_SYNC_FLAG_EXPUNGE

enum dovecot.storage.MAILBOX_SYNC_FLAG_FORGE_RESYNC

enum dovecot.storage.MAILBOX_ATTRIBUTE_PREFIX_DOVECOT

String constant vendor/vendor.dovecot/.

enum dovecot.storage.MAILBOX_ATTRIBUTE_PREFIX_DOVECOT_PVT

String constant vendor/vendor.dovecot/pvt/.

enum dovecot.storage.MAILBOX_ATTRIBUTE_PREFIX_DOVECOT_PVT_SERVER

String constant vendor/vendor.dovecot/pvt/server/.

Object mail_user

• Has tostring()
• Is comparable (by username)

Functions

mail_user.plugin_getenv()

Signature	mail_user.plugin_getenv(key)
Arguments	Name Type Description key string Setting name.

Returns key from user plugin settings or userdb environment.

mail_user.var_expand()

Signature	mail_user.var_expand(template)
Arguments	Name Type Description template string Variable template string.

Expands mail user variables (see Config variables).

mail_user.mailbox()

Signature	mail_user.mailbox(name[, flags])
Arguments	Name Type Description name string Mailbox name. flags int Flags, see dovecot.storage.

Allocates a mailbox.

mail_user.metadata_get()

Signature	mail_user.metadata_get(key)
Arguments	Name Type Description key string Metadata key, must begin with /private/ or /shared/.

Returns given metadata key for the user.

mail_user.metadata_set()

Signature	mail_user.metadata_set(key, value)
Arguments	Name Type Description key string Metadata key, must begin with /private/ or /shared/. value string Value to set, nil unsets value.

Sets user metadata key to value.

mail_user.metadata_unset()

Signature	mail_user.metadata_unset(key)
Arguments	Name Type Description key string Metadata key, must begin with /private/ or /shared/.

Unsets value, same as calling mailbox.metadata_set() with value = nil.

mail_user.metadata_list()

Signature	mail_user.metadata_list(key[, key, ...])
Arguments	Name Type Description key string Metadata prefix, must begin with /private/ or /shared/.

Lists all keys for the mailbox metadata under prefix.

Variables

mail_user.home

Home directory (if available).

mail_user.username

User's name.

mail_user.uid

System UID.

mail_user.gid

System GID.

mail_user.service

Service type (IMAP/POP3/LMTP/LDA/...).

mail_user.session_id

Current session ID.

mail_user.session_create_time

When session was created.

mail_user.nonexistent

Does user exist?

mail_user.anonymous

Is user anonymous?

mail_user.autocreated

Was user automatically created internally for some operation?

mail_user.mail_debug

Is debugging turned on?

mail_user.fuzzy_search

Does fuzzy search work for this user?

mail_user.dsyncing

Is user being dsynced?

Object mailbox

• Has tostring()
• Is comparable (by full mailbox name)

Functions

mailbox.open()

Opens the mailbox.

mailbox.close()

Closes the mailbox.

mailbox.free()

Releases mailbox (must be done).

mailbox.sync()

Signature	mailbox.sync([flags])
Arguments	Name Type Description flags int Flags, see dovecot.storage.

Synchronizes the mailbox (should usually be done).

mailbox.status()

Signature	mailbox.status(item[, item, ...])
Arguments	Name Type Description item string Item name.
Returns	mailbox_status table

Returns requested mailbox status items as table.

mailbox.metadata_get()

Signature	mailbox.metadata_get(key)
Arguments	Name Type Description key string Metadata key, must begin with /private/ or /shared/.

Returns given metadata key for the mailbox.

mailbox.metadata_set()

Signature	mailbox.metadata_set(key, value)
Arguments	Name Type Description key string Metadata key, must begin with /private/ or /shared/. value string Value to set, nil unsets value.

Sets mailbox metadata key to value.

Variables

mailbox.attribute

Full mailbox name.

mailbox.name

Mailbox name.

mailbox.attribute

Full mailbox name.

mailbox.name

Mailbox name.

Table mailbox_status

Variables

mailbox_status.mailbox

Full name of mailbox.

mailbox_status.messages

Number of messages.

mailbox_status.recent

Number of \Recent messages.

mailbox_status.unseen

Number of \Unseen messages.

mailbox_status.uidvalidity

Current UID validity.

mailbox_status.uidnext

Next UID.

mailbox_status.first_unseen_seq

First sequence number of unseen mail.

mailbox_status.first_recent_uid

First UID of unseen mail.

mailbox_status.highest_modseq

Highest modification sequence.

mailbox_status.highest_pvt_modseq

Highest private modification sequence.

mailbox_status.permanent_flags

Supported permanent flags as a bitmask.

mailbox_status.flags

Supported flags as a bitmask.

mailbox_status.permanent_keywords

Are permanent keywords supported?

mailbox_status.allow_new_keywords

Can new keywords be added?

mailbox_status.nonpermanent_modseqs

Are modification sequences temporary?

mailbox_status.no_modseq_tracking

Are modification sequences being tracked?

mailbox_status.have_guids

Do GUIDs exist?

mailbox_status.have_save_guids

Can GUIDs be saved?

mailbox_status.have_only_guid128

Are GUIDs only 128 bits?

mailbox_status.keywords

Table of current keywords.

Object mail

• Has tostring()
• Is comparable (within same mailbox, by UID)

Functions

None yet.

Variables

mail.mailbox

Mailbox object.

mail.seq

Sequence number (can change).

mail.uid

UID (immutable).