This documentation is for Dovecot v2.x, see wiki1 for v1.x documentation.


Mail is first allocated with mail_alloc(). Mails always belong to a transaction. Even if mail is treated read-only, Dovecot might write data to cache file, so whenever possible, mail transactions should be committed. When mail is allocated, you can specify a list of fields and headers that you're (most likely) going to need. This allows Dovecot to optimize the later mail_get_*() lookups so that it doesn't need to parse the message multiple times. These fields are also added to cache file, so you shouldn't list fields unless you're fairly certain you need them.

If you need to jump around in the mailbox based on already known sequences or UIDs, you can do this with mail_set_seq() and mail_set_uid(). This way you don't have to go through all the trouble of setting up a mailbox search.

Getting data

Some of the mail fields can be accessed directly:

The final field is lookup_abort, which is write-only. Normally when doing a mail_get_*() operation for a field that isn't in a cache, the field is generated and added to cache. If you don't want this, but instead have figured out some better optimized way to do non-cached lookups, you can change this field so that mail_get_*() lookups fail instead. This is primarily used by searching code internally.

Most of the mail_get_*() should be fairly obvious in how they work. Only functions returning int can fail, others don't.

Sometimes you might notice that some looked up field is actually corrupted. For example you might notice that input stream returns EOF earlier than previous mail_get_physical_size() said. This might have been caused by various different things, but in any case all you can really do then is to just call mail_set_cache_corrupted() and try again.

Setting data

Some of the messages' metadata can be updated:

Other functions are mainly intended for mailbox replication or restoring an existing mailbox (e.g. dsync):

Other metadata can't be changed. IMAP protocol requires that messages are immutable, so it's not possible to change message's received date, headers or body. If you wish to modify any of them, you need to create a new message and expunge the old one.

Design/Storage/Mail (last edited 2010-10-25 17:11:49 by TimoSirainen)