POP3 client library


The pop3 vocab implements a client interface to the POP3 protocol, enabling a Factor application to talk to POP3 servers. It allows interactive sessions similar to telnet ones to do maintenance on your mailbox on a POP3 mail server; to look at, and possibly delete, any problem causing message (e.g. too large, improperly formatted, etc.).

Word names do not necessarily map directly to POP3 commands defined in RFC1081 or RFC1939, although most commands are supported.

This article assumes that you are familiar with the POP3 protocol.

Connecting to the mail server:
connect ( pop3-account -- )


You need to construct a pop3-account tuple first, setting at least the host slot.
<pop3-account> ( -- pop3-account )


Examples
USING: accessors pop3 ; <pop3-account> "pop.yourisp.com" >>host "username@yourisp.com" >>user "pass123" >>pwd connect



If you do not supply the username or password, you will need to call the >user and >pwd vocabs in this order after the connect vocab.

Examples
USING: accessors pop3 ; <pop3-account> "pop.yourisp.com" >>host connect "username@yourisp.com" >user "pass123" >pwd



Notes
Subsequent calls to the pop3-account thus created can be done by calling the account word. If you needed to reconnect to the same POP3 account after having called close, you only need to call account followed by connect.

Querying the mail server:

For its capabilities:
capa ( -- array )


Examples
capa . { "CAPA" "TOP" "UIDL" }



For the message count:
count ( -- n )


Examples
count . 2



For each message's size:
list ( -- assoc )


Examples
list . H{ { 1 "1006" } { 2 "747" } }



For a specific message raw header, appropriate headers, or number of lines:
top ( message# #lines -- seq )


Examples
1 0 top . <the raw-source of the message header is retrieved>

1 5 top . <the raw-source of the message header and its first 5 lines are retrieved>

1 0 top headers . H{ { "From:" "from@mail.com" } { "Subject:" "Re:" } { "To:" "username@host.com" } }



To consolidate all the messages of this account into a single association:
consolidate ( -- seq )


Examples
consolidate . { T{ message { # 1 } { uidl "000000d547ac2fc2" } { from "from.first@mail.com" } { to "username@host.com" } { subject "First subject" } { size "1006" } } T{ message { # 2 } { uidl "000000d647ac2fc2" } { from "from.second@mail.com" } { to "username@host.com" } { subject "Second subject" } { size "747" } } }



You may want to delete message #2 but want to make sure you are deleting the right one. You can check that message #2 has the uidl from the example above.
uidl ( message# -- uidl )


Examples
2 uidl . "000000d647ac2fc2"



Now with your mind at rest, you can delete message #2. The message is marked for deletion.
delete ( message# -- )


Examples
2 delete



The messages marked for deletion are actually deleted only when close is called. This should be the last command you issue.
close ( -- )


Examples
close



Notes
If you change your mind at any point, you can call reset to reset the status of all messages to not be deleted.