Backend module contract

This module describes backend module contract. Backend module is used to create new method of accessing the collection of messages. For example one can write module to access messages stored in database (not currently planned).

Module content

Backend module is module contained in webmail.backends package. Backend module has one exported name mailbox_factory.

Exported mailbox_factory (usually class of mailbox accounts) must be callable with two positional parameters, named here main_config and box_config.

• main_config

  • Instance of webmail.settings.MailboxesListSetupMixin derivative or contract-compatible object. See contract document for it (not created yet at the time of writing). Most useful methods are get_mailbox* family.

• box_config

  • Dictionary-like object with settings needed to setup mailbox account.

    Usually instance of webmail.settings.MailboxSettings. Do not use for backend-specific needs names "backend", "auto_check" and "password". Also "email" should contain full email. You may require "password" field which is used as password for box be same as password for backend storage. And it's required by default backends for which this makes sense - "pop3", "web" and hopefully somewhere in future "imap".

Mailbox account

Callable mailbox_factory must return closed mailbox account.

Object returned by mailbox_factory (refered here mailbox account) must have following attributes and methods:

• email

  • Required string. Must contains valid email address form which should be email sending message to which will result in delivering message to one of this mail account's folders (generally inbox).

• closed

  • Required boolean. Must be True of non-zero when account just returned by mailbox_factory and after close called on account. Must be False or 0 when open successfully called on account.

• open

  • Required method. Must not require arguments. Must check availability of account storage. Must do all appliable of the following: connect to storage, check correctness of stored username and password, fetch options and capabilities of account storage. May also: pre-fetch list of folders and/or messages.

• close

  • Required method. Must not require arguments. Must switch account

    to closed state regardless of success or failure result. Must commit delayed changes if possible and raise an error on failure. Must not invalidate mailbox account object.

• get_inbox_name

  • Required method. Must not require arguments. Must return folder

    name which is treated same as None - as default (Inbox) folder.

• list

  • Required method. Must not require arguments. Must return unique list of folder names that can be used as arguments

    to get method. List must include either None or folder name returned by get_inbox_name but not both.

• get

  • Required method. Must accept one optional argument - folder name.

    Must return mailbox folder object. Objects returned by calls to get with same folder name can be same (cached). Contract for folder object see below. Folder name can be None, then it must be treated as default (Inbox) folder which must be treated as same as folder name returned by get_inbox_name.

Mailbox folder

Object returned by get method of mailbox account object (referred here mailbox folders) must have following attributes and methods:

• folder

  • Required string. Must be folder name. May be None after call to close method.

• close

  • Required method. Must not require arguments. Must invalidate mailbox folder object and if reasonable commit delayed change.

• list

  • Required method. Must not require arguments. Must return list of message information objects for every message in mailbox folder.

    May filter message depending on box_config options.

• get

  • Required method. Must accept one argument - msgid. Must return message identified by msgid in form of "rfc822.Message" instance. NOTE: this may change to "email.Message.Message" in future.

• delete

  • Required method. Must accept one argument - list of msgid's. Deletes messages at one transaction - if at least one message not found must return with failure and delete nothing. However sometimes it can not be guarateed - for example "pop3" backend checks that message id's is known from previous "LIST" command, but can't ensure that "DELE" command will not fail for some messages. Also this method should not delay true deletion, but it's allowed to delay it until folder or ever account "close" method - again "pop3" backend waits until account's "close".

Message information

Objects returned by list method of mailbox folder object (referred here message information) must have following attributes and methods:

• uid

  • Required string. Must be unique identifier of message in mailbox

    folder for the duration of mailbox account session (between calls to open and close). Should be preserved between sessions.

• size

  • Required number. Must contain size of message in bytes. May sometimes be non-precise, but must be precise after call

    to read_details or get. If None than message treated as unknown and is subject to read_details call.

• subject

  • Required string. Must contain subject of message.

    Must be not None after call to read_details with true force argument and after call to get.

• sender

  • Required two-tuple. Must be tuple with two parts - name and email.

    At least one part must be not None after call to read_details with true force argument and after call to get.

• date

  • Required tuple. Must contain date of message in format

    accepted by time.mktime. Must be not None after call to read_details with true force argument and after call to get.

• msg

  • Required message instance of "rfc822.Message". NOTE: this may change to "email.Message.Message" in future.

    Must be not None after call to get.

• read_details

  • Required method. Must accept one optional boolean argument force with false default value. Must fill at least size attribute after call with false force argument. Must fill all attributes except msg.

• get

  • Required method. Must require no arguments. Must retrieve

    (or get from cache) message header and body to msg attribute and return it. Message must by in form of "rfc822.Message" instance. NOTE: this may change to "email.Message.Message" in future.

• delete

  • Required method. Must require no arguments. Must delete message

    described by object with same effect as folder.delete([msg.uid]). State of object after call to this function is undefined.