11 POP3: 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

► | 11 | POP3: Reading Mail

11.1 | Exceptions
11.2 | Example Session
11.3 | POP3 Unit
11.4 | POP3 Signature

On this page:

communicator
connect-to-server
disconnect-from-server
authenticate/ plain-text
get-mailbox-status
get-message/ complete
get-message/ headers
get-message/ body
delete-message
get-unique-id/ single
get-unique-id/ all
make-desired-header
extract-desired-headers
11.1 Exceptions
pop3
cannot-connect
username-rejected
password-rejected
not-ready-for-transaction
not-given-headers
illegal-message-number
cannot-delete-message
disconnect-not-quiet
malformed-server-response
11.2 Example Session
11.3 POP3 Unit
pop3@
11.4 POP3 Signature
pop3^

Racket
top contents ← prev up next →

## 11 POP3: Reading Mail🔗ℹ

(require net/pop3) | package: net-lib

The net/pop3 module provides tools for the Post Office Protocol version 3 [RFC977].

> > struct
> > (struct |  | communicator (sender receiver server port state)
> #:extra-constructor-name make-communicator)
> sender : output-port?
> receiver : input-port?
> server : string?
> port : (integer-in 0 65535)
> state : (or/c 'disconnected 'authorization 'transaction)

Once a connection to a POP-3 server has been established, its state is stored in a communicator instance, and other procedures take communicator instances as an argument.

> procedure (connect-to-server server [port-number]) → communicator?
> server : string?
> port-number : (integer-in 0 65535) = 110

Connects to server at port-number.

> procedure (disconnect-from-server communicator) → void?
> communicator : communicator?

Disconnects communicator from the server, and sets communicator’s state to 'disconnected.

> > procedure
> > (authenticate/plain-text |  | user |  |  |  |
> > |  | passwd |  |  |  |
> > |  | communicator) |  | → |  | void?
> user : string?
> passwd : string?
> communicator : communicator?

Authenticates using user and passwd. If authentication is successful, communicator’s state is set to 'transaction.

> > procedure
> > (get-mailbox-status communicator) |  | → |  |
> > exact-nonnegative-integer?
> > exact-nonnegative-integer?
> communicator : communicator?

Returns the number of messages and the number of octets in the mailbox.

> > procedure
> > (get-message/complete |  | communicator |
> > |  | message-number) |
> | → |  |
> (listof string?) |  | (listof string?)
> communicator : communicator?
> message-number : exact-integer?

Given a message number, returns a list of message-header lines and list of message-body lines.

> > procedure
> > (get-message/headers |  | communicator |
> > |  | message-number) |
> | → |  |
> (listof string?) |  | (listof string?)
> communicator : communicator?
> message-number : exact-integer?

Given a message number, returns a list of message-header lines.

> > procedure
> > (get-message/body |  | communicator |
> > |  | message-number) |
> | → |  |
> (listof string?) |  | (listof string?)
> communicator : communicator?
> message-number : exact-integer?

Given a message number, returns a list of message-body lines.

> > procedure
> > (delete-message |  | communicator |  |  |  |
> > |  | message-number) |  | → |  | void?
> communicator : communicator?
> message-number : exact-integer?

Deletes the specified message.

> > procedure
> > (get-unique-id/single |  | communicator |  |  |  |
> > |  | message-number) |  | → |  | string?
> communicator : communicator?
> message-number : exact-integer?

Gets the server’s unique id for a particular message.

> procedure (get-unique-id/all communicator)
> → (listof (cons/c exact-integer? string?))
> communicator : communicator?

Gets a list of unique id’s from the server for all the messages in the mailbox. The car of each item in the result list is the message number, and the cdr of each item is the message’s id.

> procedure (make-desired-header tag-string) → regexp?
> tag-string : string?

Takes a header field’s tag and returns a regexp to match the field

> procedure (extract-desired-headers header desireds) → (listof string?)
> header : (listof string?)
> desireds : (listof regexp?)

Given a list of header lines and of desired regexps, returns the header lines that match any of the desireds.

### 11.1 Exceptions🔗ℹ

> > struct
> > (struct |  | pop3 exn ()
> #:extra-constructor-name make-pop3)

The supertype of all POP3 exceptions.

> > struct
> > (struct |  | cannot-connect pop3 ()
> #:extra-constructor-name make-cannot-connect)

Raised when a connection to a server cannot be established.

> > struct
> > (struct |  | username-rejected pop3 ()
> #:extra-constructor-name make-username-rejected)

Raised if the username is rejected.

> > struct
> > (struct |  | password-rejected pop3 ()
> #:extra-constructor-name make-password-rejected)

Raised if the password is rejected.

> > struct
> > (struct |  | not-ready-for-transaction pop3 (communicator)
> #:extra-constructor-name make-not-ready-for-transaction)
> communicator : communicator?

Raised when the communicator is not in transaction mode.

> > struct
> > (struct |  | not-given-headers pop3 (communicator message)
> #:extra-constructor-name make-not-given-headers)
> communicator : communicator?
> message : exact-integer?

Raised when the server does not respond with headers for a message as requested.

> > struct
> > (struct |  | illegal-message-number pop3 (communicator message)
> #:extra-constructor-name make-illegal-message-number)
> communicator : communicator?
> message : exact-integer?

Raised when the client specifies an illegal message number.

> > struct
> > (struct |  | cannot-delete-message exn (communicator message)
> #:extra-constructor-name make-cannot-delete-message)
> communicator : communicator?
> message : exact-integer?

Raised when the server is unable to delete a message.

> > struct
> > (struct |  | disconnect-not-quiet pop3 (communicator)
> #:extra-constructor-name make-disconnect-not-quiet)
> communicator : communicator?

Raised when the server does not gracefully disconnect.

> > struct
> > (struct |  | malformed-server-response pop3 (communicator)
> #:extra-constructor-name make-malformed-server-response)
> communicator : communicator?

Raised when the server produces a malformed response.

### 11.2 Example Session🔗ℹ

> > (require net/pop3)
> > (define c (connect-to-server "foo.bar.com"))
> > (authenticate/plain-text "bob" "********" c)
> > (get-mailbox-status c)
> 196
> 816400
> > (get-message/headers c 100)
> ("Date: Thu, 6 Nov 1997 12:34:18 -0600 (CST)"
> "Message-Id: <199711061834.MAA11961@foo.bar.com>"
> "From: Alice <alice@foo.bar.com>"
> ....
> "Status: RO")
> > (get-message/complete c 100)
> ("Date: Thu, 6 Nov 1997 12:34:18 -0600 (CST)"
> "Message-Id: <199711061834.MAA11961@foo.bar.com>"
> "From: Alice <alice@foo.bar.com>"
> ....
> "Status: RO")
> ("some body" "text" "goes" "." "here" "." "")
> > (get-unique-id/single c 205)
> no message numbered 205 available for unique id
> > (list-tail (get-unique-id/all c) 194)
> ((195 . "e24d13c7ef050000") (196 . "3ad2767070050000"))
> > (get-unique-id/single c 196)
> "3ad2767070050000"
> > (disconnect-from-server c)

### 11.3 POP3 Unit🔗ℹ

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

(require net/pop3-unit) | package: compatibility-lib

> value pop3@ : unit?

Imports nothing, exports pop3^.

### 11.4 POP3 Signature🔗ℹ

(require net/pop3-sig) | package: compatibility-lib

> signature pop3^ : signature

Includes everything exported by the net/pop3 module.

top contents ← prev up next →