Using the conversion utility to add IMAP summary attributes to messages

The IMAP service uses special IMAP summary attributes ($Content_Type, IMAP_BodyStruct, and IMAP_RFC822Size) in messages to facilitate the process of sending message headers in response to client requests. After you convert a mail file for IMAP use, for users who receive messages in MIME format, the Router automatically adds these items to new messages it delivers.

About this task

However, these items might not be added to all messages in a mail file. Messages delivered in Notes® rich text format do not contain the items. And Domino® does not automatically add these items to messages delivered before conversion occurred.

Although an IMAP client can read messages that do not contain IMAP summary attributes, the client must first download each message in its entirety before it can display headers. To enable faster header fetching, run the mail conversion utility with the -h switch to add IMAP summary attributes to messages that don't have them.

Updating IMAP attributes following mail file changes

About this task

Changing a message that contains the IMAP_RFC822Size attribute, might affect a user's ability to access the message. When the size value of the IMAP attribute no longer matches the actual message size, IMAP clients might have difficulty downloading the message. If the actual message size is larger than the size indicated by the attribute, the IMAP client might not download the entire message. If the actual size is smaller than the size indicated by the attribute, the IMAP client can hang as it attempts to download the remaining expected message data.

Message size might change inadvertently as a consequence of an agent running after a message is delivered or of changes to certain server configuration options, such as the settings governing outbound MIME conversion options. Although the outbound MIME conversion options apply primarily to messages sent outbound over SMTP, they also affect any message exported from the server, including messages retrieved by the IMAP service for sending to a client. For example, if you change the setting for adding RFC 822 phrases to users' Internet return addresses, this changes message size, because the Internet return address in each message an IMAP client retrieves is altered to comply with the new setting.

To prevent changes to the server configuration from contributing to download errors, update IMAP attributes to reflect the new settings. To update IMAP message attributes and refresh the mail file's MIME directory, you must remove the existing attributes and then add them again. Because IMAP clients cache header information, users must also recreate their IMAP accounts to download messages successfully.

Note: A similar problem occurs for IMAP users whose Person documents specify Notes® rich text as the mail storage preference. In this case, the Router does not add IMAP attributes to messages delivered to mail files, but the IMAP client still caches size information. When you modify the server's configuration, for example, by setting the server to export message content as HTML rather than plain text when converting messages to MIME, this changes message size. Because the client expects the size of existing messages to match their cached size, user can no longer retrieve these existing messages from an IMAP client. To remove the header information cached by the IMAP client, the user must recreate the IMAP account.

To run the mail conversion utility to add or update IMAP attributes.

Procedure

Shut down the Router on the server containing the mail files to convert, by entering the following command at the console:
```
tell router quit
```
This prevents Domino® from routing mail to the mail files while they are being converted. Mail is stored in MAIL.BOX while you upgrade the mail files. After you have converted the mail files and loaded the Router task again, the Router processes and delivers the mail in MAIL.BOX.
Load the mail conversion utility by entering the following command:
```
load convert [-h /-o] maildirectory\mailfilename
```
where maildirectory names the path to the mail subdirectory that contains the user's mail file and mailfilename is the filename of the user's mail file. The maildirectory path describes the path relative to the server's Domino® data directory. For example, to add IMAP attributes to the mail database USER.NSF in the \MAIL subdirectory of the Domino® data directory, enter:
```
load convert -h mail\user.nsf
```
Note: On UNIX™ systems, use a forward slash (/) as the hierarchy separator, rather than a backslash (\). For example, enter:
```
load convert -h mail/user.nsf
```
To specify all files in a directory, make sure the directory only contains mail files and that they are the mail files you want to convert. For example, to add IMAP attributes to all mail files in the \MAIL subdirectory, enter:
```
load convert -h mail\*.nsf
```
CAUTION: When the conversion utility is run with the -h option, the conversion operation can take a long time to complete. The exact time depends on server processing speed and memory, as well as on the size and composition of the mail file. To ensure that you can complete conversions in the available time, run a test with a single mail file before using a wildcard to run multiple conversions.
After you finish enabling mail files for IMAP on this server, load the Router by entering:
```
load router
```