1 ! Copyright (C) 2009 Elie Chaftari.
2 ! See https://factorcode.org/license.txt for BSD license.
3 USING: arrays assocs help.markup help.syntax math sequences
10 { "pop3-account" pop3-account }
12 { $description "creates a " { $link pop3-account } " object with defaults for the port and timeout slots." } ;
17 { "pop3-account" pop3-account }
19 { $description "You only need to call " { $link connect } " after calling this word to reconnect to the latest accessed POP3 account." }
29 { "name" "userID of the account" }
31 { $description "Sends the userID of the account on the POP3 server (this could be the full e-mail address)" $nl
32 "This must be the first command after " { $link connect } " if username and password have not been set with " { $link <pop3-account> } "."
37 { "password" "password for the userID" }
39 { $description "Sends the clear-text password for the userID. The password may be case sensitive. This must be the next command after " { $link >user } "." } ;
46 { $description "Queries the mail server capabilities, as described in RFC 2449. It is advised to check for command support before calling the appropriate words (e.g. TOP UIDL)." } ;
50 { "pop3-account" pop3-account }
52 { $description "Opens a network connection to the pop3 mail server with the settings given in the pop3-account slots." }
54 { $code "USING: accessors pop3 ;"
56 " \"pop.yourisp.com\" >>host"
57 " \"username@yourisp.com\" >>user"
69 { $description "Builds a sequence of email tuples, iterating over each email top and consolidating its headers with its number, uidl, and size." } ;
75 { $description "This marks message number message# for deletion from the server. This is the way to get rid of a problem causing message. It is not actually deleted until the " { $link close } " word is issued. If you lose the connection to the mail server before calling the " { $link close } " word, the server should not delete any messages. Example: 3 delete" } ;
82 { $description "Gathers and associates the From:, Subject:, and To: headers of each message." } ;
89 { $description "Lists each message with its number and size in bytes" } ;
92 { $class-description "A POP3 account on a POP3 server. It has the following slots:"
94 { "#" "The ephemeral ordinal number of the message." }
95 { "host" "The name or IP address of the remote host to which a POP3 connection is required." }
96 { "port" "The POP3 server port (defaults to 110)." }
97 { "timeout" "Maximum time in minutes to wait for a response from the POP3 server (defaults to 1 minutes)." }
98 { "user" "The userID of the account on the POP3 server." }
99 { "pwd" { "The clear-text password for the userID." } }
100 { "stream" { "The duplex input/output stream wrapping the POP3 session." } }
101 { "capa" { "A list of the mail server capabilities." } }
102 { "count" { "Number of messages in the mailbox." } }
103 { "list" { "A list of every message with its number and size in bytes" } }
104 { "uidls" { "The UIDL (Unique IDentification Listing) of every message in the mailbox together with its ordinal number." } }
105 { "messages" { "A sequence of email tuples in the mailbox containing each email's headers, number, uidl, and size." } }
107 "The " { $slot "host" } " is required; the rest are either set by default or optional." $nl
108 "The " { $slot "user" } " and " { $slot "pwd" } " must either be set before using " { $link connect } " or immediately after it with the " { $link >user } " and " { $link >pwd } " words."
112 { $class-description "An e-mail message having the following slots:"
114 { "#" "The ephemeral ordinal number of the message." }
115 { "uidl" "The POP3 UIDL (Unique IDentification Listing) of the message." }
116 { "headers" "The From:, Subject:, and To: headers of the message." }
117 { "from" "The sender of the message. An e-mail address." }
118 { "to" "The recipients of the message." }
119 { "subject" { "The subject of the message." } }
120 { "size" { "The size of the message in octets." } }
125 { $description "Deletes any messages marked for deletion, and then logs you off of the mail server. This is the last command to use." } ;
129 { "message#" fixnum }
132 { $description "Sends message number message# to you. You should prepare for some base64 decoding. You probably want to do this with a mailer." } ;
135 { $description "Resets the status of the remote POP3 server. This includes resetting the status of all messages to not be deleted." } ;
142 { $description "Gets the number of messages in the mailbox." } ;
146 { "message#" fixnum } { "#lines" fixnum }
149 { $description "Lists the header for message# and the first #lines of the message text. For example, 1 0 top would list just the headers for message 1, where as 1 5 top would list the headers and first 5 lines of the message text." } ;
153 { "message#" fixnum }
156 { $description "Gets the POP3 UIDL (Unique IDentification Listing) of the given message#." } ;
163 { $description "Gets the POP3 UIDL (Unique IDentification Listing) of every specific message in the mailbox together with its ordinal number. UIDL provides a mechanism that avoids numbering issues between POP3 sessions by assigning a permanent and unique ID for each message." } ;
165 ARTICLE: "pop3" "POP3 client library"
166 "The " { $vocab-link "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.)." $nl
167 "Word names do not necessarily map directly to POP3 commands defined in RFC1081 or RFC1939, although most commands are supported." $nl
168 "This article assumes that you are familiar with the POP3 protocol."
170 "Connecting to the mail server:"
171 { $subsections connect }
172 "You need to construct a pop3-account tuple first, setting at least the host slot."
173 { $subsections <pop3-account> }
175 { $code "USING: accessors pop3 ;"
177 " \"pop.yourisp.com\" >>host"
178 " \"username@yourisp.com\" >>user"
185 "If you do not supply the username or password, you will need to call the " { $link >user } " and " { $link >pwd } " vocabs in this order after the " { $link connect } " vocab."
187 { $code "USING: accessors pop3 ;"
189 " \"pop.yourisp.com\" >>host"
192 "\"username@yourisp.com\" >user"
198 { $notes "Subsequent calls to the " { $link pop3-account } " thus created can be done by calling the " { $link account } " word. If you needed to reconnect to the same POP3 account after having called " { $link close } ", you only need to call " { $link account } " followed by " { $link connect } "." }
200 "Querying the mail server:"
202 "For its capabilities:"
203 { $subsections capa }
207 "{ \"CAPA\" \"TOP\" \"UIDL\" }"
212 "For the message count:"
213 { $subsections count }
222 "For each message's size:"
223 { $subsections list }
227 "H{ { 1 \"1006\" } { 2 \"747\" } }"
232 "For a specific message raw header, appropriate headers, or number of lines:"
237 "<the raw-source of the message header is retrieved>"
242 "<the raw-source of the message header and its first 5 lines are retrieved>"
248 " { \"From:\" \"from@mail.com\" }"
249 " { \"Subject:\" \"Re:\" }"
250 " { \"To:\" \"username@host.com\" }"
256 "To consolidate all the messages of this account into a single association:"
257 { $subsections consolidate }
264 { uidl \"000000d547ac2fc2\" }
265 { from \"from.first@mail.com\" }
266 { to \"username@host.com\" }
267 { subject \"First subject\" }
272 { uidl \"000000d647ac2fc2\" }
273 { from \"from.second@mail.com\" }
274 { to \"username@host.com\" }
275 { subject \"Second subject\" }
283 "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."
284 { $subsections uidl }
288 "\"000000d647ac2fc2\""
293 "Now with your mind at rest, you can delete message #2. The message is marked for deletion."
294 { $subsections delete }
302 "The messages marked for deletion are actually deleted only when " { $link close } " is called. This should be the last command you issue."
303 { $subsections close }
310 { $notes "If you change your mind at any point, you can call " { $link reset } " to reset the status of all messages to not be deleted." } ;