9 IMAP: Reading Mail

9.1 Connecting and Selecting Mailboxes

The second and third return values indicate the total number of messages in the mailbox and the number of recent messages (i.e., messages received since the mailbox was last selected), respectively.

See also imap-port-number.

A user’s primary mailbox is always called "INBOX". (Capitalization doesn’t matter for that mailbox name.)

Updated message-count and recent-count values are available through imap-messages and imap-recent. See also imap-new? and imap-reset-new!.

Do not use this procedure to poll a mailbox to see whether there are any new messages. Use imap-noop, imap-new?, and imap-reset-new! instead.

9.2 Selected Mailbox State

The return information is the same as for imap-reselect.

This operation does not communicate with the server. It merely reports the result of previous communication.

This operation does not communicate with the server. It merely reports the result of previous communication.

This operation does not communicate with the server. It merely reports the result of previous communication.

This operation does not communicate with the server. It merely reports the result of previous communication.

This operation does not communicate with the server. It merely reports the result of previous communication.

This operation does not communicate with the server. It merely reports the result of previous communication.

This operation does not communicate with the server. It merely reports the result of previous communication.

The server can notify the client of newly deleted messages during most other commands, but not asynchronously between commands. Furthermore, the server cannot report new deletions during imap-get-messages or imap-store operations.

Before calling any IMAP operation that works in terms of message numbers, pending expunge notifications must be handled by calling imap-get-expunges.

This operation does not communicate with the server. It merely reports the result of previous communication. It also clears the update information from the connection after reporting it.

When a server reports information that supersedes old reported information for a message, or if the server reports that a message has been deleted, then old information for the message is dropped. Similarly, if imap-get-messages is used to explicitly obtain information, any redundant (or out-of-date) information is dropped.

A client need not use imap-get-updates ever, but accumulated information for the connection consumes space.

9.3 Manipulating Messages

• 'uid — the value is an integer

• 'header — the value is a header (a string, but see net/head)

• 'body — the value is a byte string, with CRLF-separated lines

• 'flags — the value is a list of symbols that correspond to IMAP flags; see imap-flag->symbol

The return value is a list of entry items in parallel to msg-nums. Each entry is itself a list containing value items in parallel to fields.

Pending expunges must be handled before calling this function; see imap-get-expunges.

Example:

> (imap-get-message imap '(1 3 5) '(uid header)) '((107 #"From: larry@stooges.com ...") (110 #"From: moe@stooges.com ...") (112 #"From: curly@stooges.com ..."))

			symbol		IMAP flag
	message flags:		'seen		'|\Seen|
			'answered		'|\Answered|
			'flagged		'|\Flagged|
			'deleted		'|\Deleted|
			'draft		'|\Draft|
			'recent		'|\Recent|
	mailbox flags:		'noinferiors		'|\Noinferiors|
			'noselect		'|\Noselect|
			'marked		'|\Marked|
			'unmarked		'|\Unmarked|
			'hasnochildren		'|\HasNoChildren|
			'haschildren		'|\HasChildren|

The imap-flag->symbol and symbol->imap-flag functions act like the identity function when any other symbol is provided.

• '+ — add the given flags to each message

• '- — remove the given flags from each message

• '! — set each message’s flags to the given set

The msg-nums argument specifies a set of messages by their message positions (not their uids). The flags argument specifies the imap flags to add/remove/install.

Pending expunges must be handled before calling this function; see imap-get-expunges. The server will not report back message-state changes (so they will not show up through imap-get-updates).

Examples:

> (imap-store imap '+ '(1 2 3) (list (symbol->imap-flag 'deleted))) ; marks the first three messages to be deleted > (imap-expunge imap) ; permanently removes the first three messages (and possibly ; others) from the currently-selected mailbox

9.4 Querying and Changing (Other) Mailboxes

Pending expunges must be handled before calling this function; see imap-get-expunges.

The statuses list specifies the request, and the return value includes one value for each symbol in statuses. The allowed status symbols are:

• 'messages — number of messages

• 'recent — number of recent messages

• 'unseen — number of unseen messages

• 'uidnext — uid for next received message

• 'uidvalidity — id that changes when all uids are changed

Use imap-messages to get the message count for the currently selected mailbox, etc. Use imap-new? and imap-reset-new! to detect when new messages are available in the currently selected mailbox.

The return value is a list of mailbox-information lists. Each mailbox-information list contains two items:

• a list of imap flags for the mailbox

• the mailbox’s name

9.5 IMAP Unit

imap@ and imap^ are deprecated. They exist for backward-compatibility and will likely be removed in the future. New code should use the net/imap module.

(require net/imap-unit)

9.6 IMAP Signature

(require net/imap-sig)

Includes everything exported by the net/imap module.