10 IMAP: Reading Mail

▼ |  | Net: Networking Libraries

1 | HTTP Client
2 | URLs and HTTP
3 | URI Codec: Encoding and Decoding URIs
4 | FTP: Client
5 | Send URL: Opening a Web Browser
6 | SMTP: Sending E-Mail
7 | sendmail: Sending E-Mail
8 | Headers: Parsing and Constructing
9 | Header Field Encoding
10 | IMAP: Reading Mail
11 | POP3: Reading Mail
12 | MIME: Decoding Internet Data
13 | Base 64: Encoding and Decoding
14 | Quoted-Printable: Encoding and Decoding
15 | DNS: Domain Name Service Queries
16 | NNTP: Newsgroup Protocol
17 | TCP: Unit and Signature
18 | TCP Redirect: tcp^ via Channels
19 | SSL Unit: tcp^ via SSL
20 | CGI Scripts
21 | Cookie: Legacy HTTP Client Storage
22 | Git Repository Checkout
| Bibliography
| Index

► | 10 | IMAP: Reading Mail

10.1 | Connecting and Selecting Mailboxes
10.2 | Selected Mailbox State
10.3 | Manipulating Messages
10.4 | Querying and Changing (Other) Mailboxes
10.5 | IMAP Unit
10.6 | IMAP Signature

On this page:

10.1 Connecting and Selecting Mailboxes
imap-connection?
imap-connect
imap-port-number
imap-connect*
imap-disconnect
imap-force-disconnect
imap-reselect
imap-examine
10.2 Selected Mailbox State
imap-noop
imap-poll
imap-messages
imap-recent
imap-unseen
imap-uidnext
imap-uidvalidity
imap-new?
imap-reset-new!
imap-get-expunges
imap-pending-expunges?
imap-get-updates
imap-pending-updates?
10.3 Manipulating Messages
imap-get-messages
imap-flag->symbol
symbol->imap-flag
imap-store
imap-expunge
10.4 Querying and Changing (Other) Mailboxes
imap-copy
imap-move
imap-append
imap-status
imap-mailbox-exists?
imap-create-mailbox
imap-list-child-mailboxes
imap-get-hierarchy-delimiter
imap-mailbox-flags
10.5 IMAP Unit
imap@
10.6 IMAP Signature
imap^

Racket
top contents ← 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? |  |  |  |
> > |  | #:xoauth2? xoauth2?]) |  | → |  |
> > 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
> xoauth2? : any/c = #f

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. If xoauth2? is true, then authentication uses XOAUTH2, and password is used as an access token (which must obtained somehow before calling imap-connect).

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!.

Changed in version 1.2 of package net-lib: Added the xoauth2? argument.

> 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? |
> > |  | #:xoauth2? xoauth2?]) |
> | → |  |
> 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
> xoauth2? : any/c = #f

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

Changed in version 1.2 of package net-lib: Added the xoauth2? argument.

> 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 much 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
> 'date))

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

- 'date — the value is a byte string following IMAP’s format for internal message dates (which is distinct from any date field in the message’s header)

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-messages imap '(1 3 5) '(uid header))
> '((107 #"From: larry@stooges.com ...")
> (110 #"From: moe@stooges.com ...")
> (112 #"From: curly@stooges.com ..."))

Changed in version 1.2 of package net-lib: Added the 'date field option.

> 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-move imap msg-nums dest-mailbox) → void?
> imap : imap-connection?
> msg-nums : (listof exact-nonnegative-integer?)
> dest-mailbox : (or/c string? bytes?)

Moves the specified messages from the currently selected mailbox to the specified mailbox—equivalent to copying and then expunging the messages, but this single step works only when the IMAP server supports the MOVE extension.

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

Added in version 1.3 of package net-lib.

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

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

The date string, if provided, determines the internal date associated with the message, as opposed to the date in the message header. The date-string format is defined by IMAP, and the same format is used for a 'date result from imap-get-messages.

Changed in version 1.2 of package net-lib: Added the optional date argument.

> 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, except for imap-move.

top contents ← prev up next →