10 IMAP: Reading Mail

10

IMAP: Reading Mail

top ← prev up next →

10 IMAP: Reading Mail

(require net/imap)

package: net-lib

The net/imap module provides utilities for the client side of Internet Message Access Protocol version 4rev1 [RFC2060].

10.1 Connecting and Selecting Mailboxes

procedure
(imap-connection? v) → boolean?
v : any/c

Return #t if v is a IMAP-connection value (which is opaque), #f otherwise.

procedure
(imap-connect server
username
password
mailbox
[ #:tls? tls?
#:try-tls? try-tls?]) →
imap-connection?
exact-nonnegative-integer?
exact-nonnegative-integer?
  server : string?
  username : (or/c string? bytes?)
  password : (or/c string? bytes?)
  mailbox : (or/c string? bytes?)
  tls? : any/c = #f
  try-tls? : any/c = #t

Establishes an IMAP connection to the given server using the given username and password, and selects the specified mailbox. If tls? is true, a TLS connection is made to the server before communicating using the IMAP protocol. If tls? is #f but try-tls? is true, then after the IMAP connection is initially established, the connection is switched to a TLS connection if the server supports it.

The first result value represents the connection. 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!.

parameter
(imap-port-number) → (integer-in 0 65535)
(imap-port-number k) → void?
k : (integer-in 0 65535)

A parameter that determines the server port number. The initial value is 143.

procedure
(imap-connect* in
out
username
password
mailbox
[ #:tls? tls?
#:try-tls? try-tls?])
→
imap-connection?
exact-nonnegative-integer?
exact-nonnegative-integer?
  in : input-port?
  out : output-port?
  username : (or/c string? bytes?)
  password : (or/c string? bytes?)
  mailbox : (or/c string? bytes?)
  tls? : any/c = #f
  try-tls? : any/c = #t

Like imap-connect, but given input and output ports (e.g., ports for an SSL session) instead of a server address.

procedure
(imap-disconnect imap) → void?
imap : imap-connection?

Closes an IMAP connection. The close may fail due to a communication error.

procedure
(imap-force-disconnect imap) → void?
imap : imap-connection?

Closes an IMAP connection forcefully (i.e., without send a close message to the server). A forced disconnect never fails.

procedure
(imap-reselect imap mailbox) →
exact-nonnegative-integer?
exact-nonnegative-integer?
imap : imap-connection?
mailbox : (or/c string? bytes?)

De-selects the mailbox currently selected by the connection and selects the specified mailbox, returning the total and recent message counts for the new mailbox. Expunge and message-state information is removed.

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.

procedure
(imap-examine imap mailbox) →
exact-nonnegative-integer?
exact-nonnegative-integer?
imap : imap-connection?
mailbox : (or/c string? bytes?)

Like imap-reselect, but the mailbox is selected as read-only.

10.2 Selected Mailbox State

procedure
(imap-noop imap) →
exact-nonnegative-integer?
exact-nonnegative-integer?
imap : imap-connection?

Sends a “no-op” message to the server, typically to keep the session alive. As for many commands, the server may report message-state updates or expunges, which are recorded in imap.

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

procedure
(imap-poll imap) → void?
imap : imap-connection?

Does not send a request to the server, but checks for asynchronous messages from the server that update the message count, to report expunges, etc.

procedure
(imap-messages imap) → exact-nonnegative-integer?
imap : imap-connection?

Returns the number of messages in the selected mailbox. The server can update this count during most any interaction.

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

procedure
(imap-recent imap) → exact-nonnegative-integer?
imap : imap-connection?

Returns the number of “recent” messages in the currently selected mailbox, as most recently reported by the server. The server can update this count during most any interaction.

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

procedure
(imap-unseen imap) → (or/c exact-nonnegative-integer? #f)
imap : imap-connection?

Returns the number of “unseen” messages in the currently selected mailbox, as most recently reported by the server. The server can update this count during most any interaction. Old IMAP servers might not report this value, in which case the result is #f.

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

procedure
(imap-uidnext imap) → (or/c exact-nonnegative-integer? #f)
imap : imap-connection?

Returns the predicted next uid for a message in the currently selected mailbox, as most recently reported by the server. The server can update this count during most any interaction. Old IMAP servers might not report this value, in which case the result is #f.

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

procedure
(imap-uidvalidity imap) → (or/c exact-nonnegative-integer? #f)
imap : imap-connection?

Returns an id number that changes when all uids become invalid. The server cannot update this number during a session. Old IMAP servers might not report this value, in which case the result is #f.

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

procedure
(imap-new? imap) → boolean?
imap : imap-connection?

Returns #t if the server has reported an increase in the message count for the currently mailbox since the last call to imap-reset-new!. Selecting a mailbox implicitly calls imap-reset-new!.

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

procedure
(imap-reset-new! imap) → void?
imap : imap-connection?

Resets the new flag for the session; see imap-new?. This operation does not communicate with the server.

procedure
(imap-get-expunges imap) → (listof exact-nonnegative-integer?)
imap : imap-connection?

Returns pending expunge notifications from the server for the selected mailbox in terms of message positions (not uids), and clears the pending notifications. The result list is sorted, ascending.

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.

procedure
(imap-pending-expunges? imap) → boolean?
imap : imap-connection?

Returns #f if imap-get-expunges would return an empty list, #t otherwise.

procedure
(imap-get-updates imap)
→
(listof (cons/c exact-nonnegative-integer?
(listof pair?)))
imap : imap-connection?

Returns information must like imap-get-messages, but includes information reported asynchronously by the server (e.g., to notify a client with some other client changes a message attribute). Instead of reporting specific requested information for specific messages, the result is associates message positions to field-value association lists. The result list is sorted by message position, ascending.

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.

procedure
(imap-pending-updates? imap) → boolean?
imap : imap-connection?

Returns #f if imap-get-updates would return an list, #t otherwise.

10.3 Manipulating Messages

procedure
(imap-get-messages imap msg-nums fields) → (listof list?)
  imap : imap-connection?
  msg-nums : (listof exact-nonnegative-integer?)
   fields :
(listof (or/c 'uid
              'header
              'body
              'flags))

Downloads information for a set of messages. The msg-nums argument specifies a set of messages by their message positions (not their uids). The fields argument specifies the type of information to download for each message. The available fields are:

'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: [email protected] ...")
(110 #"From: [email protected] ...")
(112 #"From: [email protected] ..."))

procedure
(imap-flag->symbol flag) → symbol?
flag : symbol?
procedure
(symbol->imap-flag sym) → symbol?
sym : symbol?

An IMAP flag is a symbol, but it is generally not a convenient one to use within a Racket program, because it usually starts with a backslash. The imap-flag->symbol and symbol->imap-flag procedures convert IMAP flags to convenient symbols and vice-versa:

			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.

procedure
(imap-store imap mode msg-nums imap-flags) → void?
  imap : imap-connection?
  mode : (or/c '+ '- '!)
  msg-nums : (listof exact-nonnegative-integer?)
  imap-flags : (listof symbol?)

Sets flags for a set of messages. The mode argument specifies how flags are set:

'+ — 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

procedure
(imap-expunge imap) → void?
imap : imap-connection?

Purges every message currently marked with the '|\Deleted| flag from the mailbox.

10.4 Querying and Changing (Other) Mailboxes

procedure
(imap-copy imap msg-nums dest-mailbox) → void?
  imap : imap-connection?
  msg-nums : (listof exact-nonnegative-integer?)
  dest-mailbox : (or/c string? bytes?)

Copies the specified messages from the currently selected mailbox to the specified mailbox.

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

procedure
(imap-append imap mailbox message [flags]) → void?
  imap : imap-connection?
  mailbox : string?
  message : (or/c string? bytes?)
   flags :
(listof (or/c 'seen 'answered 'flagged
              'deleted 'draft 'recent))
= '(seen)

Adds a new message (containing message) to the given mailbox.

procedure
(imap-status imap mailbox statuses) → list?
  imap : imap-connection?
  mailbox : (or/c string? bytes?)
  statuses : (listof symbol?)

Requests information about a mailbox from the server, typically not the currently selected mailbox.

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.

procedure
(imap-mailbox-exists? imap mailbox) → boolean?
imap : imap-connection?
mailbox : (or/c string? bytes?)

Returns #t if mailbox exists, #f otherwise.

procedure
(imap-create-mailbox imap mailbox) → void?
imap : imap-connection?
mailbox : (or/c string? bytes?)

Creates mailbox. (It must not exist already.)

procedure
(imap-list-child-mailboxes imap
mailbox
[ delimiter])
→ (listof (list/c (listof symbol?) bytes?))
  imap : imap-connection?
  mailbox : (or/c string? bytes? #f)
   delimiter : (or/c string? bytes?)
= (imap-get-hierarchy-delimiter)

Returns information about sub-mailboxes of mailbox; if mailbox is #f, information about all top-level mailboxes is returned. The delimiter is used to parse mailbox names from the server to detect hierarchy.

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

procedure
(imap-get-hierarchy-delimiter imap) → bytes?
imap : imap-connection?

Returns the server-specific string that is used as a separator in mailbox path names.

procedure
(imap-mailbox-flags imap mailbox) → (listof symbol?)
imap : imap-connection?
mailbox : (or/c string? bytes?)

Returns a list of IMAP flags for the given mailbox. See also imap-flag->symbol.

10.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)

package: compatibility-lib

value
imap@ : unit?

Imports nothing, exports imap^.

10.6 IMAP Signature

(require net/imap-sig)

package: compatibility-lib

signature
imap^ : signature

Includes everything exported by the net/imap module.

top ← prev up next →