Browse code
checkpoint
jkf authored on 26/04/2000 20:50:28Showing 1 changed files
| ... | ... |
@@ -1,1107 +1,1200 @@ |
| 1 |
-<html> |
|
| 2 |
- |
|
| 3 |
-<head> |
|
| 4 |
-<title>Allegro CL imap and pop interface</title> |
|
| 5 |
-<meta name="GENERATOR" content="Microsoft FrontPage 3.0"> |
|
| 6 |
-</head> |
|
| 7 |
- |
|
| 8 |
-<body> |
|
| 9 |
- |
|
| 10 |
-<h1 align="center">Allegro CL imap and pop interface</h1> |
|
| 11 |
- |
|
| 12 |
-<p align="left">copyright (c) 1999 Franz Inc.</p> |
|
| 13 |
- |
|
| 14 |
-<p align="left"> </p> |
|
| 15 |
- |
|
| 16 |
-<p align="left"><strong>imap</strong> is a client-server protocol for processing |
|
| 17 |
-electronic mail boxes. <strong>imap </strong>is the successor to the <strong>pop</strong> |
|
| 18 |
-protocol. It is <strong>not</strong> an upward compatible successor. |
|
| 19 |
- The main focus of this document is the <strong>imap</strong> |
|
| 20 |
-protocol. Only one small section describes the functions in the <strong>pop</strong> |
|
| 21 |
-interface.</p> |
|
| 22 |
- |
|
| 23 |
-<p align="left">The contents of this document are:</p> |
|
| 24 |
- |
|
| 25 |
-<ul> |
|
| 26 |
- <li><p align="left">the <strong>imap</strong> interface</p> |
|
| 27 |
- </li> |
|
| 28 |
- <li><p align="left"><a href="#pop">the <strong>pop</strong> interface</a></p> |
|
| 29 |
- </li> |
|
| 30 |
- <li><p align="left"><a href="#conditions">the <strong>conditions</strong> signaled by the <strong>imap</strong> |
|
| 31 |
- and <strong>pop</strong> interfaces.</a></p> |
|
| 32 |
- </li> |
|
| 33 |
- <li><p align="left"><a href="#smtp">the <strong>smtp</strong> interface</a> (used for |
|
| 34 |
- sending mail)</p> |
|
| 35 |
- </li> |
|
| 36 |
-</ul> |
|
| 37 |
- |
|
| 38 |
-<p align="left">The imap interface is based on the Imap4rev1 protocol described in |
|
| 39 |
-rfc2060. Where this document is describing the actions of the imap commands it |
|
| 40 |
-should be considered a secondary source of information about those commands and rfc2060 |
|
| 41 |
-should be considered the primary source.</p> |
|
| 42 |
- |
|
| 43 |
-<p align="left">The advantages of <strong>imap</strong> over <strong>pop</strong> are:</p> |
|
| 44 |
- |
|
| 45 |
-<ol> |
|
| 46 |
- <li><p align="left"><strong>imap </strong>can work with multiple mailboxes (<strong>pop </strong>works |
|
| 47 |
- with a single mailbox)</p> |
|
| 48 |
- </li> |
|
| 49 |
- <li><p align="left">With <strong>imap</strong> you're encouraged to leave mail in mailboxes |
|
| 50 |
- on the server machine, thus it can be read from any machine on the network. |
|
| 51 |
- With <strong>pop</strong> you're encouraged to download the mail to the client machine's |
|
| 52 |
- disk, and it thus becomes inaccessible to all other client machines.</p> |
|
| 53 |
- </li> |
|
| 54 |
- <li><p align="left"><strong>imap</strong> parses the headers of messages thus allowing |
|
| 55 |
- easier analysis of mail messages by the client program.</p> |
|
| 56 |
- </li> |
|
| 57 |
- <li><p align="left"><strong>imap</strong> supports searching messages for data and sorting |
|
| 58 |
- by date.</p> |
|
| 59 |
- </li> |
|
| 60 |
- <li><p align="left"><strong>imap </strong>supports annotating messages with flags, thus |
|
| 61 |
- making subsequent searching easier.</p> |
|
| 62 |
- </li> |
|
| 63 |
-</ol> |
|
| 64 |
- |
|
| 65 |
-<p align="left"> </p> |
|
| 66 |
- |
|
| 67 |
-<h1 align="left">Package</h1> |
|
| 68 |
- |
|
| 69 |
-<p align="left">The functions in this interface are defined in the <strong>post-office</strong> |
|
| 70 |
-package which has a nickname <strong>po</strong>.</p> |
|
| 71 |
- |
|
| 72 |
-<p align="left"> </p> |
|
| 73 |
- |
|
| 74 |
-<h1 align="left">Mailboxes</h1> |
|
| 75 |
- |
|
| 76 |
-<p align="left">Mailboxes are repositories for messages. Mailboxes are named |
|
| 77 |
-by Lisp strings. The mailbox "inbox" always exists and it is the mailbox |
|
| 78 |
-in which new messages are stored. New mailboxes can be created. |
|
| 79 |
- They can have simple names, like "foo" or they can have |
|
| 80 |
-hierarchical names (like "clients/california/widgetco"). After |
|
| 81 |
-connecting to an imap server you can determine what string of characters you must use |
|
| 82 |
-between simple names to create a hierarchical name (in this example "/" was the |
|
| 83 |
-separator character). </p> |
|
| 84 |
- |
|
| 85 |
-<p align="left">Each mailbox has an associated unique number called its <strong>uidvalidity</strong>. |
|
| 86 |
- This number won't change as long as <strong>imap</strong> is the only |
|
| 87 |
-program used to manipulate the mailbox. In fact if you see that the number has |
|
| 88 |
-changed then that means that some other program has done something to the mailbox that |
|
| 89 |
-destroyed the information that <strong>imap</strong> had been keeping about the |
|
| 90 |
-mailbox. In particular you can't now retrieve messages by their unique |
|
| 91 |
-ids that you had used before.</p> |
|
| 92 |
- |
|
| 93 |
-<h1 align="left">Messages</h1> |
|
| 94 |
- |
|
| 95 |
-<p align="left">Messages in a mailbox can be denoted in one of two ways: message |
|
| 96 |
-sequence number or unique id. </p> |
|
| 97 |
- |
|
| 98 |
-<p align="left">The <em>message sequence number</em> is the normal way. The messages |
|
| 99 |
-in a mailbox are numbered from 1 to N where N is the number of messages in the mailbox. |
|
| 100 |
- There are never any gaps in the sequence numbers. If you tell <strong>imap</strong> |
|
| 101 |
-to delete messages 3,4 and 5 then it will return a value telling you the it has deleted |
|
| 102 |
-messages 3,3 and 3. This is because when you deleted message 3, message 4 became the |
|
| 103 |
-new message 3 just before it was deleted and then message 5 became message 3 just before |
|
| 104 |
-it was deleted.</p> |
|
| 105 |
- |
|
| 106 |
-<p align="left">A <em>unique id </em>of a message is a number associated with a message |
|
| 107 |
-that is unique only within a mailbox. As long as the uidvalidity value of a |
|
| 108 |
-mailbox doesn't change, the unique ids used in deleted messages will never be reused for |
|
| 109 |
-new messages. </p> |
|
| 110 |
- |
|
| 111 |
-<h1 align="left">Flags</h1> |
|
| 112 |
- |
|
| 113 |
-<p align="left">A flag is a symbol denoting that a message or mailbox has a certain |
|
| 114 |
-property. We use keywords in Lisp to denote flags. There are two |
|
| 115 |
-kinds of flags - System and User flags. System flags begin with the backslash |
|
| 116 |
-character, which is an unfortunate design decision since that means that in Lisp we |
|
| 117 |
-have to remember to use two backslashes (e.g. <strong>:\\deleted</strong>). |
|
| 118 |
- A subset of the flags can be stored permanently in the mailbox with the |
|
| 119 |
-messages. When a connection is made to an <strong>imap</strong> server it will |
|
| 120 |
-return the list of flags and permanent flags (and these are stored in the mailbox object |
|
| 121 |
-returned for access by the program). If the list of permanent flags includes <strong>:\\*</strong> |
|
| 122 |
-then the program can create its own flag names (not beginning with a backslash) and can |
|
| 123 |
-store them permanently in messages.</p> |
|
| 124 |
- |
|
| 125 |
-<p align="left">Some of the important system flags are:</p> |
|
| 126 |
- |
|
| 127 |
-<ul> |
|
| 128 |
- <li><p align="left"><strong>:\\seen</strong> - this means that the message has been read |
|
| 129 |
- (a <strong>fetch-letter</strong> has been done that includes the content of the |
|
| 130 |
- message, not just its headers)</p> |
|
| 131 |
- </li> |
|
| 132 |
- <li><p align="left"><strong>:\\deleted </strong>- the message will be deleted the next time |
|
| 133 |
- an <strong>expunge-mailbox</strong> or <strong>close-mailbox</strong> is done.</p> |
|
| 134 |
- </li> |
|
| 135 |
- <li><p align="left"><strong>:\\recent </strong>- this is the first session to have been |
|
| 136 |
- notified about this message being present in the mailbox.</p> |
|
| 137 |
- </li> |
|
| 138 |
-</ul> |
|
| 139 |
- |
|
| 140 |
-<p align="left"> </p> |
|
| 141 |
- |
|
| 142 |
-<h1 align="left">Connecting to the server</h1> |
|
| 143 |
- |
|
| 144 |
-<p align="left"> </p> |
|
| 145 |
- |
|
| 146 |
-<p align="left"><font face="Courier New">(<strong>make-imap-connection host &key user |
|
| 147 |
-password port timeout)</strong></font></p> |
|
| 148 |
- |
|
| 149 |
-<p align="left">This creates a connection to the <strong>imap</strong> server on machine <strong>host</strong> |
|
| 150 |
-and logs in as <strong>user </strong>with password <strong>password. </strong>The |
|
| 151 |
-<strong>port</strong> argument defaults to143, which is the port on which the <strong>imap</strong> |
|
| 152 |
-server normally listens. The <strong>timeout</strong> argument defaults |
|
| 153 |
-to 30 (seconds) and this value is used to limit the amount of time this imap interface |
|
| 154 |
-code will wait for a response from the server before giving up. In |
|
| 155 |
-certain circumstances the server may get so busy that you see timeout errors signaled in |
|
| 156 |
-this code. In that case you should specify a larger timeout when connecting. </p> |
|
| 157 |
- |
|
| 158 |
-<p align="left">The <strong>make-imap-connection</strong> function returns a <strong>mailbox</strong> |
|
| 159 |
-object which is then passed to other functions in this interface. From this |
|
| 160 |
-one connection you can access all of the mailboxes owned by <strong>user</strong>.</p> |
|
| 161 |
- |
|
| 162 |
-<p align="left">After the connection is established a mailbox is <strong>not</strong> |
|
| 163 |
-selected. In this state attempting to execute message access functions may |
|
| 164 |
-result in cryptic error messages from the <strong>imap</strong> server that won't tell you |
|
| 165 |
-what you need to know -- that a mailbox is not selected. Therefore be sure to |
|
| 166 |
-select a mailbox using <strong>select-mailbox</strong> shortly after connecting.</p> |
|
| 167 |
- |
|
| 168 |
-<p align="left"> </p> |
|
| 169 |
- |
|
| 170 |
-<p align="left"> </p> |
|
| 171 |
- |
|
| 172 |
-<p align="left"><strong><font face="Courier New">(close-connection mailbox)</font></strong></p> |
|
| 173 |
- |
|
| 174 |
-<p align="left">This sends a <strong>logout</strong> command to the <strong>imap</strong> |
|
| 175 |
-server and then closes the socket that's communicating with the <strong>imap</strong> |
|
| 176 |
-server. <strong>mailbox </strong>is the object returned by <strong>make-imap-connection.</strong> |
|
| 177 |
- This does <em>not</em> close the currently select mailbox before logging out, |
|
| 178 |
-thus messages marked to be deleted in the currently selected mailbox will <em>not</em> be |
|
| 179 |
-removed from the mailbox. Use <strong>close-mailbox</strong> or <strong>expunge-mailbox</strong> |
|
| 180 |
-before calling this <strong>close-connection</strong> to ensure that messages to be |
|
| 181 |
-deleted are deleted.</p> |
|
| 182 |
- |
|
| 183 |
-<p align="left"> </p> |
|
| 184 |
- |
|
| 185 |
-<p align="left"> </p> |
|
| 186 |
- |
|
| 187 |
-<h1 align="left">Mailbox manipulation</h1> |
|
| 188 |
- |
|
| 189 |
-<p align="left">These functions work on mailboxes as a whole. The <strong>mailbox</strong> |
|
| 190 |
-argument to the functions is is the object returned by <strong>make-imap-connection. |
|
| 191 |
- </strong>If a return value isn't specified for a function then the return value |
|
| 192 |
-isn't important - if something goes wrong an error will be signaled.</p> |
|
| 193 |
- |
|
| 194 |
-<p align="left"> </p> |
|
| 195 |
- |
|
| 196 |
-<p align="left"><font face="Courier New"><strong>(select-mailbox mailbox name)</strong></font></p> |
|
| 197 |
- |
|
| 198 |
-<p align="left">makes the mailbox named by the string <strong>name</strong> be the current |
|
| 199 |
-mailbox and store statistics about that mailbox in the <strong>mailbox</strong> object |
|
| 200 |
-where they can be retrieved by the accessors described below. The |
|
| 201 |
-selected mailbox is the source for all message manipulation functions.</p> |
|
| 202 |
- |
|
| 203 |
-<p align="left"> </p> |
|
| 204 |
- |
|
| 205 |
-<p align="left"><font face="Courier New"><strong>(create-mailbox mailbox name)</strong></font></p> |
|
| 206 |
- |
|
| 207 |
-<p align="left">creates a new mailbox with the given <strong>name</strong>. It |
|
| 208 |
-is an error if the mailbox already exists. If you want to create a mailbox in a |
|
| 209 |
-hierarchy then you should be sure that it uses the correct hierarchy separator character |
|
| 210 |
-string (see <strong>mailbox-separator)</strong>. You do <strong>not</strong> |
|
| 211 |
- have to create intermediate levels of the hierarchy yourself -- just provide the |
|
| 212 |
-complete name and the <strong>imap</strong> server will create all necessary levels.</p> |
|
| 213 |
- |
|
| 214 |
-<p align="left"> </p> |
|
| 215 |
- |
|
| 216 |
-<p align="left"><font face="Courier New"><strong>(delete-mailbox mailbox name)</strong></font></p> |
|
| 217 |
- |
|
| 218 |
-<p align="left">deletes the mailbox with the given name.</p> |
|
| 219 |
- |
|
| 220 |
-<p align="left"> </p> |
|
| 221 |
- |
|
| 222 |
-<p align="left"><font face="Courier New"><strong>(rename-mailbox mailbox old-name |
|
| 223 |
-new-name)</strong></font></p> |
|
| 224 |
- |
|
| 225 |
-<p align="left">changes the name of mailbox <strong>old-name</strong> to <strong>new-name</strong>. |
|
| 226 |
- It's an error if <strong>new-name</strong> already exists. There's a special |
|
| 227 |
-behavior if <strong>old-name</strong> is "inbox". In this case all of the |
|
| 228 |
-messages in "inbox" are moved to <strong>new-name </strong>mailbox, but the |
|
| 229 |
-"inbox" mailbox continues to exist. Note: The <strong>imap </strong>server |
|
| 230 |
-supplied with Linux does <strong>not</strong> support this special behavior of renaming |
|
| 231 |
-"inbox".</p> |
|
| 232 |
- |
|
| 233 |
-<p align="left"> </p> |
|
| 234 |
- |
|
| 235 |
-<p align="left"><strong><font face="Courier New">(mailbox-list mailbox &key reference |
|
| 236 |
-pattern)</font></strong></p> |
|
| 237 |
- |
|
| 238 |
-<p align="left">returns a list of items describing the mailboxes that match the arguments. |
|
| 239 |
- The <strong>reference</strong> is the root of the hierarchy to |
|
| 240 |
-scan. By default is is the empty string (from which all mailboxes are reachable). |
|
| 241 |
- The <strong>pattern </strong>is a string matched against all mailbox |
|
| 242 |
-names reachable from <strong>reference. </strong>There are two special characters allowed |
|
| 243 |
-in the <strong>pattern: </strong>Asterisk (*) matches all characters including |
|
| 244 |
-hierarchy delimiters. Percent (%) matches all characters but not the hierarchy |
|
| 245 |
-delimiter. Thus</p> |
|
| 246 |
- |
|
| 247 |
-<p align="center"><font face="Courier New">(mailbox-list mailbox :pattern "*")</font></p> |
|
| 248 |
- |
|
| 249 |
-<p align="left">returns a list of all mailboxes at all depths in the hierarchy. |
|
| 250 |
- </p> |
|
| 251 |
- |
|
| 252 |
-<p align="left">The value returned is a list of lists, but we've created the <strong>mailbox-list |
|
| 253 |
-</strong>struct definition in order to make accessing the parts of the inner lists |
|
| 254 |
-easier. The accessors for that structure are:</p> |
|
| 255 |
- |
|
| 256 |
-<p align="left"> </p> |
|
| 257 |
- |
|
| 258 |
-<p align="left"><font face="Courier New"><strong>(mailbox-list-flags mailbox-list) </strong></font></p> |
|
| 259 |
- |
|
| 260 |
-<p align="left">returns the flags describing this entry. The most important |
|
| 261 |
-flag to check is <strong>:\\noselect</strong> as this specifies that this is not a mailbox |
|
| 262 |
-but instead just a directory in the hierarchy of mailboxes. The flag <strong>:\\noinferiors</strong> |
|
| 263 |
-specifies that you can't create a hierarchical mailbox name with this as a prefix. |
|
| 264 |
- This flag is often associated with the special mailbox "inbox".</p> |
|
| 265 |
- |
|
| 266 |
-<p align="left"> </p> |
|
| 267 |
- |
|
| 268 |
-<p align="left"><font face="Courier New"><strong>(mailbox-list-separator mailbox-list)</strong></font></p> |
|
| 269 |
- |
|
| 270 |
-<p align="left">returns a string containing the characters used to separate names in a |
|
| 271 |
-hierarchical name.</p> |
|
| 272 |
- |
|
| 273 |
-<p align="left"> </p> |
|
| 274 |
- |
|
| 275 |
-<p align="left"><font face="Courier New"><strong>(mailbox-list-name mailbox-list)</strong></font></p> |
|
| 276 |
- |
|
| 277 |
-<p align="left">returns the name of the mailbox or directory (see mailbox-list-flags to |
|
| 278 |
-determine which it is).</p> |
|
| 279 |
- |
|
| 280 |
-<p align="left"> </p> |
|
| 281 |
- |
|
| 282 |
-<h1 align="left">Message manipulation</h1> |
|
| 283 |
- |
|
| 284 |
-<p align="left">These functions work with the messages in the currently selected mailbox. |
|
| 285 |
- The <strong>mailbox</strong> argument is the object returned by <strong>make-imap-connection.</strong> |
|
| 286 |
- The <strong>messages</strong> argument is either a number (denoting a single |
|
| 287 |
-message), or is the list <strong>(:seq N M) </strong>denoting messages <strong>N</strong> |
|
| 288 |
-through <strong>M, </strong>or is a list of numbers and <strong>:seq </strong>forms |
|
| 289 |
-denoting the messages specified in the list.</p> |
|
| 290 |
- |
|
| 291 |
-<p align="left"> </p> |
|
| 292 |
- |
|
| 293 |
-<p align="left">(<font face="Courier New"><strong>alter-flags mailbox messages &key |
|
| 294 |
-flags add-flags remove-flags silent uid)</strong></font></p> |
|
| 295 |
- |
|
| 296 |
-<p>changes the flags of the messages in the specified way. Exactly one of <strong>flags, |
|
| 297 |
-add-flags</strong>, and <strong>remove-flags</strong> must be specified. <strong>flags</strong> |
|
| 298 |
-specifies the complete set of flags to be stores in the <strong>messages</strong> and the |
|
| 299 |
-other two add or remove flags. If <strong>uid</strong> is true then <strong>messages</strong> |
|
| 300 |
-will be interpreted as unique ids rather than message sequence numbers. |
|
| 301 |
- Normally <strong>alter-flags</strong> returns a data structure |
|
| 302 |
-that describes the state of the flags after the alternation has been done. This data |
|
| 303 |
-structure can be examined with the <strong>fetch-field</strong> function. |
|
| 304 |
- If <strong>silent</strong> is true then this data structure won't be created |
|
| 305 |
-thus saving some time and space.</p> |
|
| 306 |
- |
|
| 307 |
-<p>Removing a message from a mailbox is done by adding the <strong>:\\deleted</strong> |
|
| 308 |
-flag to the message and then either calling <strong>close-mailbox </strong>or <strong>expunge-mailbox.</strong></p> |
|
| 309 |
- |
|
| 310 |
-<p> </p> |
|
| 311 |
- |
|
| 312 |
-<p><font face="Courier New"><strong>(close-mailbox mailbox)</strong></font></p> |
|
| 313 |
- |
|
| 314 |
-<p>permanently removes all messages flagged as <strong>:\\deleted</strong> from the |
|
| 315 |
-currently selected mailbox and then un-selects the currently selected mailbox. After |
|
| 316 |
-this command has finished there is no currently selected mailbox.</p> |
|
| 317 |
- |
|
| 318 |
-<p align="left"> </p> |
|
| 319 |
- |
|
| 320 |
-<p align="left"><strong><font face="Courier New">(copy-to-mailbox mailbox messages |
|
| 321 |
-destination &key uid)</font></strong></p> |
|
| 322 |
- |
|
| 323 |
-<p align="left">copies the specified <strong>messages </strong>from the currently selected |
|
| 324 |
-mailbox to the mailbox named <strong>destination</strong> (given as a string). The |
|
| 325 |
-flags are copied as well. The destination mailbox must already exist. The messages |
|
| 326 |
-are <strong>not</strong> removed from the selected mailbox after the copy .If <strong>uid</strong> |
|
| 327 |
-is true then the <strong>messages</strong> are considered to be unique ids rather than |
|
| 328 |
-message sequence numbers. </p> |
|
| 329 |
- |
|
| 330 |
-<p align="left"> </p> |
|
| 331 |
- |
|
| 332 |
-<p align="left"><font face="Courier New"><strong>(delete-letter mailbox messages &key |
|
| 333 |
-expunge uid</strong></font>)</p> |
|
| 334 |
- |
|
| 335 |
-<p align="left">Mark the <strong>messages</strong> for deletion and then remove them |
|
| 336 |
-permanently (using <strong>expunge-mailbox</strong>) if <strong>expunge</strong> is true. |
|
| 337 |
- <strong>expunge </strong>defaults to true. If <strong>uid</strong> |
|
| 338 |
-is true then the message numbers are unique ids instead of messages sequence numbers.</p> |
|
| 339 |
- |
|
| 340 |
-<p align="left"> </p> |
|
| 341 |
- |
|
| 342 |
-<p align="left"><font face="Courier New"><strong>(expunge-mailbox mailbox)</strong></font></p> |
|
| 343 |
- |
|
| 344 |
-<p align="left">permanently removes all messages flagged as <strong>:\\deleted</strong> |
|
| 345 |
-from the currently selected mailbox. The currently selected mailbox stays |
|
| 346 |
-selected.</p> |
|
| 347 |
- |
|
| 348 |
-<p align="left"> </p> |
|
| 349 |
- |
|
| 350 |
-<p align="left"><font face="Courier New"><strong>(fetch-field message part info &key |
|
| 351 |
-uid)</strong></font></p> |
|
| 352 |
- |
|
| 353 |
-<p align="left">is used to extract the desired information from the value returned by <strong>fetch-letter</strong>. |
|
| 354 |
- With <strong>fetch-letter</strong> you can retrieve a variety of |
|
| 355 |
-information about one or more messages and <strong>fetch-field</strong> can search though |
|
| 356 |
-that information and return a particular piece of information about a particular |
|
| 357 |
-letter. <strong>message</strong> is the message number (it's assumed to be a |
|
| 358 |
-message sequence number unless <strong>uid </strong>is true, in which case it's a unique |
|
| 359 |
-id). <strong>part </strong>is the type of information desired. It is a |
|
| 360 |
-string just as used in the call to <strong>fetch-letter</strong>.</p> |
|
| 361 |
- |
|
| 362 |
-<p align="left"> </p> |
|
| 363 |
- |
|
| 364 |
-<p align="left"><strong><font face="Courier New">(fetch-letter mailbox message &key |
|
| 365 |
-uid)</font></strong></p> |
|
| 366 |
- |
|
| 367 |
-<p align="left">Return the complete message, headers and body, as one big string. |
|
| 368 |
-This is a combination of <strong>fetch-field</strong> and <strong>fetch-parts</strong> |
|
| 369 |
-where the part specification is "body[]".</p> |
|
| 370 |
- |
|
| 371 |
-<p align="left"> </p> |
|
| 372 |
- |
|
| 373 |
-<p align="left"><font face="Courier New"><strong>(fetch-parts mailbox messages parts |
|
| 374 |
-&key uid)</strong></font></p> |
|
| 375 |
- |
|
| 376 |
-<p align="left">retrieves the specified <strong>parts</strong> of the specified <strong>messages. |
|
| 377 |
- </strong>If <strong>uid</strong> is true then the <strong>messages</strong> |
|
| 378 |
-are considered to be unique ids rather than message sequence numbers. |
|
| 379 |
- The description of what can be specified for <strong>parts </strong>is |
|
| 380 |
-quite complex and is described in the section below "Fetching a Letter".</p> |
|
| 381 |
- |
|
| 382 |
-<p align="left">The return value from this function is a structure that can be examined |
|
| 383 |
-with <strong>fetch-field</strong>.</p> |
|
| 384 |
- |
|
| 385 |
-<p align="left">When the result returned includes an envelope value the following |
|
| 386 |
-functions can be used to extract the components of the envelope:</p> |
|
| 387 |
- |
|
| 388 |
-<ul> |
|
| 389 |
- <li><p align="left"><font face="Courier New"><strong>envelope-date</strong></font></p> |
|
| 390 |
- </li> |
|
| 391 |
- <li><p align="left"><font face="Courier New"><strong>envelope-subject</strong></font></p> |
|
| 392 |
- </li> |
|
| 393 |
- <li><p align="left"><font face="Courier New"><strong>envelope-from</strong></font></p> |
|
| 394 |
- </li> |
|
| 395 |
- <li><p align="left"><font face="Courier New"><strong>envelope-sender</strong></font></p> |
|
| 396 |
- </li> |
|
| 397 |
- <li><p align="left"><font face="Courier New"><strong>envelope-reply-to</strong></font></p> |
|
| 398 |
- </li> |
|
| 399 |
- <li><p align="left"><font face="Courier New"><strong>envelope-to</strong></font></p> |
|
| 400 |
- </li> |
|
| 401 |
- <li><p align="left"><font face="Courier New"><strong>envelope-cc</strong></font></p> |
|
| 402 |
- </li> |
|
| 403 |
- <li><p align="left"><font face="Courier New"><strong>envelope-bcc</strong></font></p> |
|
| 404 |
- </li> |
|
| 405 |
- <li><p align="left"><font face="Courier New"><strong>envelope-in-reply-to</strong></font></p> |
|
| 406 |
- </li> |
|
| 407 |
- <li><p align="left"><font face="Courier New"><strong>envelope-message-id</strong></font></p> |
|
| 408 |
- </li> |
|
| 409 |
-</ul> |
|
| 410 |
- |
|
| 411 |
-<p align="left"> </p> |
|
| 412 |
- |
|
| 413 |
-<p align="left"> </p> |
|
| 414 |
- |
|
| 415 |
-<p align="left"><strong><font face="Courier New">(noop mailbox)</font></strong></p> |
|
| 416 |
- |
|
| 417 |
-<p align="left">does nothing but remind the <strong>imap</strong> server that this |
|
| 418 |
-client is still active, thus resetting the timers used in the server that will |
|
| 419 |
-automatically shut down this connection after a period of inactivity. Like all |
|
| 420 |
-other commands if messages have been added to the currently selected mailbox, the server |
|
| 421 |
-will return the new message count as a response to the <strong>noop</strong> command, and |
|
| 422 |
-this can be check using <strong>mailbox-message-count</strong>. </p> |
|
| 423 |
- |
|
| 424 |
-<p align="left"> </p> |
|
| 425 |
- |
|
| 426 |
-<p align="left"><font face="Courier New"><strong>(search-mailbox mailbox search-expression |
|
| 427 |
-&key uid)</strong></font></p> |
|
| 428 |
- |
|
| 429 |
-<p align="left">return a list of messages in the mailbox that satisfy the<strong> |
|
| 430 |
-search-expression. </strong>If <strong>uid</strong> is true then unique ids |
|
| 431 |
-will be returned instead of message sequence numbers. See the section |
|
| 432 |
-"Searching for messages" for details on the <strong>search-expression</strong>.</p> |
|
| 433 |
- |
|
| 434 |
-<p align="left"> </p> |
|
| 435 |
- |
|
| 436 |
-<h1 align="left">Mailbox Accessors</h1> |
|
| 437 |
- |
|
| 438 |
-<p align="left">The mailbox object contains information about the <strong>imap </strong>server |
|
| 439 |
-it's connected to as well as the currently selected mailbox. This information |
|
| 440 |
-can potentially be updated each time a request is made to the <strong>imap </strong>server. |
|
| 441 |
- The following functions access values from the mailbox object. </p> |
|
| 442 |
- |
|
| 443 |
-<p align="left"><font face="Courier New"><strong>(mailbox-flags mailbox)</strong></font></p> |
|
| 444 |
- |
|
| 445 |
-<p align="left">returns a complete list of flags used in all the messages in this mailbox.</p> |
|
| 446 |
- |
|
| 447 |
-<p align="left"> </p> |
|
| 448 |
- |
|
| 449 |
-<p align="left"><font face="Courier New"><strong>(mailbox-permanent-flags mailbox)</strong></font></p> |
|
| 450 |
- |
|
| 451 |
-<p align="left">returns a list of flags that can be stored permanently in a message. |
|
| 452 |
- If the flag <strong>:\\*</strong> is present then it means that the client can |
|
| 453 |
-create its own flags.</p> |
|
| 454 |
- |
|
| 455 |
-<p align="left"> </p> |
|
| 456 |
- |
|
| 457 |
-<p align="left"><font face="Courier New"><strong>(mailbox-message-count mailbox)</strong></font></p> |
|
| 458 |
- |
|
| 459 |
-<p align="left">returns the number of messages in the currently selected mailbox</p> |
|
| 460 |
- |
|
| 461 |
-<p align="left"> </p> |
|
| 462 |
- |
|
| 463 |
-<p align="left"><font face="Courier New"><strong>(mailbox-recent-messages mailbox)</strong></font></p> |
|
| 464 |
- |
|
| 465 |
-<p align="left">returns the number of messages have just arrived in the mailbox.</p> |
|
| 466 |
- |
|
| 467 |
-<p align="left"> </p> |
|
| 468 |
- |
|
| 469 |
-<p align="left"><font face="Courier New"><strong>(mailbox-separator mailbox)</strong></font></p> |
|
| 470 |
- |
|
| 471 |
-<p align="left">returns the hierarchy separator string for this <strong>imap </strong>server.</p> |
|
| 472 |
- |
|
| 473 |
-<p align="left"> </p> |
|
| 474 |
- |
|
| 475 |
-<p align="left"><font face="Courier New"><strong>(mailbox-uidnext mailbox)</strong></font></p> |
|
| 476 |
- |
|
| 477 |
-<p align="left">returns the value predicated to be the unique id assigned to the |
|
| 478 |
-next message.</p> |
|
| 479 |
- |
|
| 480 |
-<p align="left"> </p> |
|
| 481 |
- |
|
| 482 |
-<p align="left"><font face="Courier New"><strong>(mailbox-uidvalidty mailbox)</strong></font></p> |
|
| 483 |
- |
|
| 484 |
-<p align="left">returns the uidvalidity value for the currently selected mailbox.</p> |
|
| 485 |
- |
|
| 486 |
-<p align="left"> </p> |
|
| 487 |
- |
|
| 488 |
-<p align="left"> </p> |
|
| 489 |
- |
|
| 490 |
-<h1 align="left">Fetching a Letter</h1> |
|
| 491 |
- |
|
| 492 |
-<p align="left">When using <strong>fetch-parts</strong> to access letters, you must |
|
| 493 |
-specify the parts of the messages in which you're interested. There are a wide |
|
| 494 |
-variety of specifiers, some redundant and overlapping, described in the imap specification |
|
| 495 |
-in rfe2060. We'll describe the most common ones here. The specification |
|
| 496 |
-is always a string but it may be specified more than one thing by the use of parentheses in |
|
| 497 |
-the string, e.g. "(flags envelope)". </p> |
|
| 498 |
- |
|
| 499 |
-<p align="left">The most common specifiers are:</p> |
|
| 500 |
- |
|
| 501 |
-<ul> |
|
| 502 |
- <li><p align="left"><strong>body[]</strong> - this returns the full message: headers and |
|
| 503 |
- body. You can use <strong>fetch-letter</strong> if you only want this part and |
|
| 504 |
- you want to avoid having to call <strong>fetch-field</strong>.</p> |
|
| 505 |
- </li> |
|
| 506 |
- <li><p align="left"><strong>body[text]</strong> - this returns just the the text of the body |
|
| 507 |
- of the message, not the header.</p> |
|
| 508 |
- </li> |
|
| 509 |
- <li><p align="left"><strong>body</strong> - this returns a list describing the structure of |
|
| 510 |
- the message.</p> |
|
| 511 |
- </li> |
|
| 512 |
- <li><p align="left"><strong>envelope</strong> - this parses the header and returns a list of |
|
| 513 |
- information in it. We've defined a set of accessors <strong>(</strong>like<strong> |
|
| 514 |
- envelope-xxx</strong>) that allow you to retrieve the envelope information easily.</p> |
|
| 515 |
- </li> |
|
| 516 |
- <li><p align="left"><strong>flags</strong> - return a list of the flags in the message</p> |
|
| 517 |
- </li> |
|
| 518 |
- <li><p align="left"><strong>uid</strong> - the unique identifier of the message</p> |
|
| 519 |
- </li> |
|
| 520 |
-</ul> |
|
| 521 |
- |
|
| 522 |
-<p align="left"> </p> |
|
| 523 |
- |
|
| 524 |
-<p align="left">The result of a <strong>fetch-parts</strong> is a data structure |
|
| 525 |
-containing all of the requested information. The <strong>fetch-field</strong> |
|
| 526 |
-function is then used to extract the particular information for the particular message.</p> |
|
| 527 |
- |
|
| 528 |
-<p align="left"> </p> |
|
| 529 |
- |
|
| 530 |
-<h1 align="left">Searching for Messages</h1> |
|
| 531 |
- |
|
| 532 |
-<p align="left">.The <strong>imap</strong> server is able to search for messages matching |
|
| 533 |
-a search expression. A search-expression is a predicate or one of |
|
| 534 |
-these forms:</p> |
|
| 535 |
- |
|
| 536 |
-<ul> |
|
| 537 |
- <li><p align="left">(<strong>and</strong> search-expression ...)</p> |
|
| 538 |
- </li> |
|
| 539 |
- <li><p align="left">(<strong>or</strong> search-expression ...)</p> |
|
| 540 |
- </li> |
|
| 541 |
- <li><p align="left">(<strong>not</strong> search-expression)</p> |
|
| 542 |
- </li> |
|
| 543 |
-</ul> |
|
| 544 |
- |
|
| 545 |
-<p align="left">A predicate is </p> |
|
| 546 |
- |
|
| 547 |
-<ul> |
|
| 548 |
- <li><p align="left">a number in which case the predicate is true if and only if we're are |
|
| 549 |
- considering this message</p> |
|
| 550 |
- </li> |
|
| 551 |
- <li><p align="left">a <strong>(:seq N M)</strong> expression that is true if we're |
|
| 552 |
- considering messages N through M.</p> |
|
| 553 |
- </li> |
|
| 554 |
- <li><p align="left"><strong>:all</strong> - this predicate is always true</p> |
|
| 555 |
- </li> |
|
| 556 |
- <li><p align="left"><strong>:answered</strong> - true if the message has the <strong>:\\answered</strong> |
|
| 557 |
- flag</p> |
|
| 558 |
- </li> |
|
| 559 |
- <li><p align="left"><strong>(:bcc "string") </strong>- true if the envelope |
|
| 560 |
- structure's bcc field contains this "string".</p> |
|
| 561 |
- </li> |
|
| 562 |
- <li><p align="left"><strong>(:before date)</strong> - true if the messages internal date is |
|
| 563 |
- before this date. The date can either be a string in the rfc822 form (e.g. |
|
| 564 |
- "7-Mar-1999") or a lisp universal time.</p> |
|
| 565 |
- </li> |
|
| 566 |
- <li><p align="left"><strong>(:body "string") </strong>- true if the body of the |
|
| 567 |
- message contains "string"</p> |
|
| 568 |
- </li> |
|
| 569 |
- <li><p align="left"><strong>(:cc "string")</strong> - true if the envelope |
|
| 570 |
- structure's cc field contains this "string".</p> |
|
| 571 |
- </li> |
|
| 572 |
- <li><p align="left"><strong>:deleted</strong> - true if the <strong>:\\deleted</strong> flag |
|
| 573 |
- is set for this message</p> |
|
| 574 |
- </li> |
|
| 575 |
- <li><p align="left"><strong>:draft</strong> - true if the <strong>:\\draft </strong>flag is |
|
| 576 |
- set for this message</p> |
|
| 577 |
- </li> |
|
| 578 |
- <li><p align="left"><strong>:flagged </strong>- true if the <strong>:\\flagged</strong> flag |
|
| 579 |
- is set for this message</p> |
|
| 580 |
- </li> |
|
| 581 |
- <li><p align="left"><strong>(:from "string")</strong> - true if the envelope |
|
| 582 |
- structure's from field contains this "string".</p> |
|
| 583 |
- </li> |
|
| 584 |
- <li><p align="left"><strong>(:header "field" "string")</strong> - true |
|
| 585 |
- if the message contains a header named "field" and its value contains |
|
| 586 |
- "string".</p> |
|
| 587 |
- </li> |
|
| 588 |
- <li><p align="left"><strong>(:keyword flag)</strong> - true if the specified flag is set for |
|
| 589 |
- this message</p> |
|
| 590 |
- </li> |
|
| 591 |
- <li><p align="left"><strong>(:larger N)</strong> - true if the rfc822 size of the message is |
|
| 592 |
- larger than N.</p> |
|
| 593 |
- </li> |
|
| 594 |
- <li><p align="left"><strong>:new </strong>- true if the message has the <strong>:\\recent</strong> |
|
| 595 |
- flag set but not the <strong>:\\seen </strong>flag.</p> |
|
| 596 |
- </li> |
|
| 597 |
- <li><p align="left"><strong>:seen </strong>- true if the message has the <strong>:\\seen </strong>flag |
|
| 598 |
- set.</p> |
|
| 599 |
- </li> |
|
| 600 |
- <li><p align="left"><strong>(:sentbefore date)</strong> - true if the message's Date header |
|
| 601 |
- is earlier than the given date. See the description of :before for the format of |
|
| 602 |
- dates.</p> |
|
| 603 |
- </li> |
|
| 604 |
- <li><p align="left"><strong>(:senton date)</strong> - true if the message's Date header is |
|
| 605 |
- within the specified date.</p> |
|
| 606 |
- </li> |
|
| 607 |
- <li><p align="left"><strong>(:sentsince date) </strong>- true if the message's Date header |
|
| 608 |
- is within or since the given date.</p> |
|
| 609 |
- </li> |
|
| 610 |
- <li><p align="left"><strong>(:smaller N)</strong> - true if the rfc822 size of the message |
|
| 611 |
- is smaller than N</p> |
|
| 612 |
- </li> |
|
| 613 |
- <li><p align="left"><strong>(:subject "string") </strong>- true if the Subject |
|
| 614 |
- header line of the message contains "string"</p> |
|
| 615 |
- </li> |
|
| 616 |
- <li><p align="left"><strong>(:text "string") </strong>- true if the message's |
|
| 617 |
- header or body contains the specified "string"</p> |
|
| 618 |
- </li> |
|
| 619 |
- <li><p align="left"><strong>(:to "string")</strong> - true if the envelope |
|
| 620 |
- structure's to field contains this "string".</p> |
|
| 621 |
- </li> |
|
| 622 |
- <li><p align="left"><strong>(:uid message-set)</strong> - true if the message is one of the |
|
| 623 |
- message denoted by the message set, where the message set describes messages by unique id.</p> |
|
| 624 |
- </li> |
|
| 625 |
- <li><p align="left"><strong>:unanswered</strong> - true if the message does not have the <strong>:\\answered</strong> |
|
| 626 |
- flag set</p> |
|
| 627 |
- </li> |
|
| 628 |
- <li><p align="left"><strong>:undeleted</strong> - true if the message does not have the <strong>:\\deleted</strong> |
|
| 629 |
- flag set</p> |
|
| 630 |
- </li> |
|
| 631 |
- <li><p align="left"><strong>:undraft </strong>- true if the message does not have the <strong>:\\draft |
|
| 632 |
- </strong>flag set.</p> |
|
| 633 |
- </li> |
|
| 634 |
- <li><p align="left"><strong>:unflagged </strong>- true if the message does not have the <strong>:\\flagged</strong> |
|
| 635 |
- flag set.</p> |
|
| 636 |
- </li> |
|
| 637 |
- <li><p align="left"><strong>(:unkeyword flag)</strong> - true if the message does not have |
|
| 638 |
- the specified flag set.</p> |
|
| 639 |
- </li> |
|
| 640 |
- <li><p align="left"><strong>:unseen </strong>- true if the message does not have the <strong>:\\seen |
|
| 641 |
- </strong>flag set.</p> |
|
| 642 |
- </li> |
|
| 643 |
-</ul> |
|
| 644 |
- |
|
| 645 |
-<p align="left"> </p> |
|
| 646 |
- |
|
| 647 |
-<h1 align="left">Examples</h1> |
|
| 648 |
- |
|
| 649 |
-<p align="left">We show an example of using this interface</p> |
|
| 650 |
- |
|
| 651 |
-<p align="left"> </p> |
|
| 652 |
- |
|
| 653 |
-<p align="left"><strong>Connect to the imap server on the machine holding the email:</strong></p> |
|
| 654 |
-<div align="left"> |
|
| 655 |
- |
|
| 656 |
-<pre>user(2): (setq mb (po:make-imap-connection "mailmachine.franz.com" |
|
| 657 |
- :user "myacct" |
|
| 658 |
- :password "mypasswd")) |
|
| 659 |
-#<mailbox::imap-mailbox @ #x2064ca4a></pre> |
|
| 660 |
-</div> |
|
| 661 |
- |
|
| 662 |
-<p align="left"> </p> |
|
| 663 |
- |
|
| 664 |
-<p align="left"><strong>Select the inbox, that's where the incoming mail arrives:</strong></p> |
|
| 665 |
-<div align="left"> |
|
| 666 |
- |
|
| 667 |
-<pre> |
|
| 668 |
-user(3): (po:select-mailbox mb "inbox") |
|
| 669 |
-t</pre> |
|
| 670 |
-</div> |
|
| 671 |
- |
|
| 672 |
-<p align="left"> </p> |
|
| 673 |
- |
|
| 674 |
-<p align="left"><strong>Check how many messages are in the mailbox:</strong></p> |
|
| 675 |
-<div align="left"> |
|
| 676 |
- |
|
| 677 |
-<pre> |
|
| 678 |
-user(4): (po:mailbox-message-count mb) |
|
| 679 |
-7</pre> |
|
| 680 |
-</div> |
|
| 681 |
- |
|
| 682 |
-<p align="left"><strong>There are seven messages at the moment. Fetch the |
|
| 683 |
-whole 4th message. We could call (po:fetch-letter mb 4) here instead and then not |
|
| 684 |
-have to call fetch-field later.</strong></p> |
|
| 685 |
-<div align="left"> |
|
| 686 |
- |
|
| 687 |
-<pre> |
|
| 688 |
-user(5): (setq body (po:fetch-parts mb 4 "body[]")) |
|
| 689 |
-((4 |
|
| 690 |
-("BODY[]" "Return-Path: <jkfmail@tiger.franz.com> |
|
| 691 |
-Received: from tiger.franz.com (jkf@tiger [192.132.95.103]) |
|
| 692 |
- by tiger.franz.com (8.8.7/8.8.7) with SMTP id LAA20261 |
|
| 693 |
- for <jkfmail@tiger.franz.com>; Mon, 13 Sep 1999 11:36:26 -0700 |
|
| 694 |
-Date: Mon, 13 Sep 1999 11:36:26 -0700 |
|
| 695 |
-From: jkf mail tester <jkfmail@tiger.franz.com> |
|
| 696 |
-Message-Id: <199909131836.LAA20261@tiger.franz.com> |
|
| 697 |
- |
|
| 698 |
-message number 5 |
|
| 699 |
-")))</pre> |
|
| 700 |
-</div> |
|
| 701 |
- |
|
| 702 |
-<p align="left"><strong>The value was returned inside a data structure designed to hold |
|
| 703 |
-information about one or more messages. In order to extract the particular |
|
| 704 |
-information we want we use fetch-field:</strong></p> |
|
| 705 |
-<div align="left"> |
|
| 706 |
- |
|
| 707 |
-<pre> |
|
| 708 |
-user(6): (po:fetch-field 4 "body[]" body) |
|
| 709 |
-"Return-Path: <jkfmail@tiger.franz.com> |
|
| 710 |
-Received: from tiger.franz.com (jkf@tiger [192.132.95.103]) |
|
| 711 |
- by tiger.franz.com (8.8.7/8.8.7) with SMTP id LAA20261 |
|
| 712 |
- for <jkfmail@tiger.franz.com>; Mon, 13 Sep 1999 11:36:26 -0700 |
|
| 713 |
-Date: Mon, 13 Sep 1999 11:36:26 -0700 |
|
| 714 |
-From: jkf mail tester <jkfmail@tiger.franz.com> |
|
| 715 |
-Message-Id: <199909131836.LAA20261@tiger.franz.com> |
|
| 716 |
- |
|
| 717 |
-message number 5 |
|
| 718 |
-"</pre> |
|
| 719 |
-</div> |
|
| 720 |
- |
|
| 721 |
-<p align="left"><strong>We use the search function to find all the messages containing the |
|
| 722 |
-word blitzfig. It turns out there is only one. We then extract the contents of |
|
| 723 |
-that message.</strong></p> |
|
| 724 |
-<div align="left"> |
|
| 725 |
- |
|
| 726 |
-<pre> |
|
| 727 |
-user(7): (po:search-mailbox mb '(:text "blitzfig")) |
|
| 728 |
-(7) |
|
| 729 |
-user(8): (po:fetch-field 7 "body[]" (po:fetch-letter mb 7 "body[]")) |
|
| 730 |
-"Return-Path: <jkf@verada.com> |
|
| 731 |
-Received: from main.verada.com (main.verada.com [208.164.216.3]) |
|
| 732 |
- by tiger.franz.com (8.8.7/8.8.7) with ESMTP id NAA20541 |
|
| 733 |
- for <jkfmail@tiger.franz.com>; Mon, 13 Sep 1999 13:37:24 -0700 |
|
| 734 |
-Received: from main.verada.com (IDENT:jkf@localhost [127.0.0.1]) |
|
| 735 |
- by main.verada.com (8.9.3/8.9.3) with ESMTP id NAA06121 |
|
| 736 |
- for <jkfmail@tiger.franz.com>; Mon, 13 Sep 1999 13:36:54 -0700 |
|
| 737 |
-Message-Id: <199909132036.NAA06121@main.verada.com> |
|
| 738 |
-To: jkfmail@tiger.franz.com |
|
| 739 |
-Subject: s test |
|
| 740 |
-Date: Mon, 13 Sep 1999 13:36:54 -0700 |
|
| 741 |
-From: jkf <jkf@verada.com> |
|
| 742 |
- |
|
| 743 |
-secret word: blitzfig |
|
| 744 |
-ok? |
|
| 745 |
-"</pre> |
|
| 746 |
-</div> |
|
| 747 |
- |
|
| 748 |
-<p align="left"><strong>We've been using message sequence numbers up to now. |
|
| 749 |
-The are the simplest to use but if you're concerned with keeping track of messages when |
|
| 750 |
-deletions are being done then using unique id's is useful. Here we do the |
|
| 751 |
-above search example using uids:</strong></p> |
|
| 752 |
-<div align="left"> |
|
| 753 |
- |
|
| 754 |
-<pre> |
|
| 755 |
-user(9): (po:search-mailbox mb '(:text "blitzfig") :uid t) |
|
| 756 |
-(68) |
|
| 757 |
-user(10): (po:fetch-field 68 "body[]" (po:fetch-letter mb 68 "body[]" :uid t) :uid t) |
|
| 758 |
-"Return-Path: <jkf@verada.com> |
|
| 759 |
-Received: from main.verada.com (main.verada.com [208.164.216.3]) |
|
| 760 |
- by tiger.franz.com (8.8.7/8.8.7) with ESMTP id NAA20541 |
|
| 761 |
- for <jkfmail@tiger.franz.com>; Mon, 13 Sep 1999 13:37:24 -0700 |
|
| 762 |
-Received: from main.verada.com (IDENT:jkf@localhost [127.0.0.1]) |
|
| 763 |
- by main.verada.com (8.9.3/8.9.3) with ESMTP id NAA06121 |
|
| 764 |
- for <jkfmail@tiger.franz.com>; Mon, 13 Sep 1999 13:36:54 -0700 |
|
| 765 |
-Message-Id: <199909132036.NAA06121@main.verada.com> |
|
| 766 |
-To: jkfmail@tiger.franz.com |
|
| 767 |
-Subject: s test |
|
| 768 |
-Date: Mon, 13 Sep 1999 13:36:54 -0700 |
|
| 769 |
-From: jkf <jkf@verada.com> |
|
| 770 |
- |
|
| 771 |
-secret word: blitzfig |
|
| 772 |
-ok? |
|
| 773 |
-"</pre> |
|
| 774 |
-</div> |
|
| 775 |
- |
|
| 776 |
-<p align="left"><strong>We'll delete that letter with the secret word and then note that |
|
| 777 |
-we have only six messages in the mailbox.</strong></p> |
|
| 778 |
-<div align="left"> |
|
| 779 |
- |
|
| 780 |
-<pre> |
|
| 781 |
-user(11): (po:delete-letter mb 68 :uid t) |
|
| 782 |
-(7) |
|
| 783 |
-user(12): (po:mailbox-message-count mb) |
|
| 784 |
-6</pre> |
|
| 785 |
-</div> |
|
| 786 |
- |
|
| 787 |
-<p align="left"><strong>Now we assume that a bit of time has passed and we want to see if |
|
| 788 |
-any new messages have been delivered into the mailbox. In order to find out we |
|
| 789 |
-have to send a command to the imap server since it will only notify us of new messages |
|
| 790 |
-when it responds to a command. Since we have nothing to ask the imap server to |
|
| 791 |
-do we issue the noop command, which does nothing on the server.</strong></p> |
|
| 792 |
-<div align="left"> |
|
| 793 |
- |
|
| 794 |
-<pre> |
|
| 795 |
-user(13): (po:noop mb) |
|
| 796 |
-nil |
|
| 797 |
-user(14): (po:mailbox-message-count mb) |
|
| 798 |
-7</pre> |
|
| 799 |
-</div> |
|
| 800 |
- |
|
| 801 |
-<p align="left"><strong>The server told us that there are now 7 messages in the inbox, one |
|
| 802 |
-more than before. Next we create a new mailbox, copy the messages from the inbox to |
|
| 803 |
-the new mailbox and then delete them from the inbox. Note how we use the :seq form |
|
| 804 |
-to specify a sequence of messages.</strong></p> |
|
| 805 |
-<div align="left"> |
|
| 806 |
- |
|
| 807 |
-<pre> |
|
| 808 |
-user(15): (po:create-mailbox mb "tempbox") |
|
| 809 |
-t |
|
| 810 |
-user(18): (let ((count (po:mailbox-message-count mb))) |
|
| 811 |
-(po:copy-to-mailbox mb `(:seq 1 ,count) "tempbox") |
|
| 812 |
-(po:delete-letter mb `(:seq 1 ,count))) |
|
| 813 |
-(1 1 1 1 1 1 1) |
|
| 814 |
-user(19): (po:mailbox-message-count mb) |
|
| 815 |
-0</pre> |
|
| 816 |
-</div> |
|
| 817 |
- |
|
| 818 |
-<p align="left"><strong>When we're done there are 0 messages in the currently selected |
|
| 819 |
-mailbox, which is inbox. We now select the maibox we just created and see that the |
|
| 820 |
-messages are there.</strong></p> |
|
| 821 |
-<div align="left"> |
|
| 822 |
- |
|
| 823 |
-<pre> |
|
| 824 |
-user(22): (po:select-mailbox mb "tempbox") |
|
| 825 |
-t |
|
| 826 |
-user(23): (po:mailbox-message-count mb) |
|
| 827 |
-7</pre> |
|
| 828 |
-</div> |
|
| 829 |
- |
|
| 830 |
-<p align="left"><strong>Finally we shut down the connection. Note that imap |
|
| 831 |
-servers will automatically shut down a connection that's been idle for too long (usually |
|
| 832 |
-around 10 minutes). When that happens, the next time the client tries to use an imap |
|
| 833 |
-function to access the mailbox an error will occur. There is nothing that can |
|
| 834 |
-be done to revive the connection however it is important to call close-imap-connection on |
|
| 835 |
-the lisp side in order to free up the resources still in use for the now dead connection.</strong></p> |
|
| 836 |
-<div align="left"> |
|
| 837 |
- |
|
| 838 |
-<pre> |
|
| 839 |
-user(24): (po:close-connection mb) |
|
| 840 |
-t |
|
| 841 |
-</pre> |
|
| 842 |
-</div> |
|
| 843 |
- |
|
| 844 |
-<p align="left"> </p> |
|
| 845 |
- |
|
| 846 |
-<h1><a name="pop"></a>The Pop interface</h1> |
|
| 847 |
- |
|
| 848 |
-<p>The <strong>pop</strong> protocol is a very simple means for retrieving messages from a |
|
| 849 |
-single mailbox. The functions in the interface are:</p> |
|
| 850 |
- |
|
| 851 |
-<p> </p> |
|
| 852 |
- |
|
| 853 |
-<p align="left"><font face="Courier New">(<strong>make-pop-connection host &key user |
|
| 854 |
-password port timeout)</strong></font></p> |
|
| 855 |
- |
|
| 856 |
-<p align="left">This creates a connection to the <strong>pop</strong> server on machine <strong>host</strong> |
|
| 857 |
-and logs in as <strong>user </strong>with password <strong>password. </strong>The |
|
| 858 |
-<strong>port</strong> argument defaults to 110, which is the port on which the <strong>pop</strong> |
|
| 859 |
-server normally listens. The <strong>timeout</strong> argument defaults |
|
| 860 |
-to 30 (seconds) and this value is used to limit the amount of time this pop interface code |
|
| 861 |
-will wait for a response from the server before giving up. In certain |
|
| 862 |
-circumstances the server may get so busy that you see timeout errors signaled in this |
|
| 863 |
-code. In that case you should specify a larger timeout when connecting. </p> |
|
| 864 |
- |
|
| 865 |
-<p>The value returned by this function is a <strong>mailbox</strong> object. You can |
|
| 866 |
-call <strong>mailbox-message-count</strong> on the <strong>mailbox</strong> object to |
|
| 867 |
-determine how many letters are currently stored in the mailbox.</p> |
|
| 868 |
- |
|
| 869 |
-<p> </p> |
|
| 870 |
- |
|
| 871 |
-<p><font face="Courier New"><strong>(close-connection mb)</strong></font></p> |
|
| 872 |
- |
|
| 873 |
-<p>Disconnect from the pop server. All messages marked for deletion will be deleted.</p> |
|
| 874 |
- |
|
| 875 |
-<p> </p> |
|
| 876 |
- |
|
| 877 |
-<p><strong><font face="Courier New">(delete-letter mb messages)</font></strong></p> |
|
| 878 |
- |
|
| 879 |
-<p>Mark the specified <strong>messages</strong> for deletion. <strong>mb </strong>is |
|
| 880 |
-the mailbox object returned by <strong>make-pop-connection</strong>. The messages |
|
| 881 |
-are only marked for deletion. They are not removed until a <strong>close-connection</strong> |
|
| 882 |
-is done. If the connection to the <strong>pop</strong> server is broken before a <strong>close-connection</strong> |
|
| 883 |
-is done, the messages will <strong>not</strong> be deleted and they will no longer be |
|
| 884 |
-marked for deletion either.</p> |
|
| 885 |
- |
|
| 886 |
-<p><strong>messages</strong> can either be a message number, a list of the form <strong>(:seq |
|
| 887 |
-N M)</strong> meaning messages <strong>N </strong>through <strong>M </strong>or it can be |
|
| 888 |
-a list of message numbers and/or <strong>:seq </strong>specifiers. The |
|
| 889 |
-messages in a mailbox are numbered starting with one. Marking a message for deletion |
|
| 890 |
-does not affect the numbering of other messages in the mailbox.</p> |
|
| 891 |
- |
|
| 892 |
-<p> </p> |
|
| 893 |
- |
|
| 894 |
-<p><font face="Courier New"><strong>(fetch-letter mb message)</strong></font></p> |
|
| 895 |
- |
|
| 896 |
-<p>Fetch from the pop server connection <strong>mb</strong> the letter numbered <strong>message</strong>. |
|
| 897 |
- The letters in a mailbox are numbered starting with one. The entire |
|
| 898 |
-message, including the headers, is returned as a string. It is an |
|
| 899 |
-error to attempt to fetch a letter marked for deletion.</p> |
|
| 900 |
- |
|
| 901 |
-<p> </p> |
|
| 902 |
- |
|
| 903 |
-<p><font face="Courier New"><strong>(make-envelope-from-text text)</strong></font></p> |
|
| 904 |
- |
|
| 905 |
-<p><strong>text</strong> is a string that is the first part of a mail message, including |
|
| 906 |
-at least all of the headers lines and the blank line following the headers. This |
|
| 907 |
-function parses the header lines and return an <strong>envelope</strong> structure |
|
| 908 |
-containing information from the header. </p> |
|
| 909 |
- |
|
| 910 |
-<p> </p> |
|
| 911 |
- |
|
| 912 |
-<p><font face="Courier New"><strong>(noop mb)</strong></font></p> |
|
| 913 |
- |
|
| 914 |
-<p>This is the no-operation command. It is useful for letting the <strong>pop</strong> |
|
| 915 |
-server know that this connection should be kept alive (<strong>pop </strong>servers tend |
|
| 916 |
-to disconnect after a few minutes of inactivity). In order to make <strong>noop</strong> |
|
| 917 |
-have behavior similar to that of the <strong>imap</strong> version of <strong>noop</strong>, |
|
| 918 |
-we don't send a 'noop' command to the pop server, instead we send a 'stat' command. |
|
| 919 |
- This means that after this command is completed the <strong>mailbox-message-count</strong> |
|
| 920 |
-will contain the current count of messages in the mailbox.</p> |
|
| 921 |
- |
|
| 922 |
-<p> </p> |
|
| 923 |
- |
|
| 924 |
-<p><font face="Courier New"><strong>(top-lines mb message line-count)</strong></font></p> |
|
| 925 |
- |
|
| 926 |
-<p>Return a string that contains all the header lines and the first <strong>line-count</strong> |
|
| 927 |
-lines of the body of <strong>message</strong>. To just retrieve the headers a <strong>line-count</strong> |
|
| 928 |
-of zero can be given. See the function <strong>make-envelope-from-text</strong> for |
|
| 929 |
-a means of reading the information in the header.</p> |
|
| 930 |
- |
|
| 931 |
-<p> </p> |
|
| 932 |
- |
|
| 933 |
-<p><font face="Courier New"><strong>(unique-id mb &optional message)</strong></font></p> |
|
| 934 |
- |
|
| 935 |
-<p>Return the unique indentifier for the given message, or for all non-deleted messages if |
|
| 936 |
-<strong>message</strong> is nil. The unique identifier is is a string that is |
|
| 937 |
-different for every message. If <strong> </strong>the <strong>message</strong> |
|
| 938 |
-argument is not given then this command returns a list of lists where each list |
|
| 939 |
-contains two items: the message number and the unique id.</p> |
|
| 940 |
- |
|
| 941 |
-<h1>Cond<a name="conditions"></a>itions</h1> |
|
| 942 |
- |
|
| 943 |
-<p>When an unexpected event occurs a condition is signaled. This applies to |
|
| 944 |
-both the <strong>imap</strong> and <strong>pop</strong> interfaces. There are two |
|
| 945 |
-classes of conditions signaled by this package: |
|
| 946 |
- |
|
| 947 |
-<ul> |
|
| 948 |
- <li><strong>po-condition</strong> - this class denotes conditions that need not and in fact |
|
| 949 |
- should not interrupt program flow. When the mailbox server is responding to a |
|
| 950 |
- command it sometimes sends informational warning messages and we turn them into |
|
| 951 |
- conditions. It's important for all messages from the server to be read |
|
| 952 |
- and processed otherwise the next command issued will see messages in response to the |
|
| 953 |
- previous command. Therefore the user code should never do a non-local-transfer |
|
| 954 |
- in response to a <strong>po-condition.</strong></li> |
|
| 955 |
- <li><strong>po-error - </strong>this class denotes conditions that will prevent execution |
|
| 956 |
- from continuing. If one of these errors is not caught, the interactive debugger will |
|
| 957 |
- be entered.</li> |
|
| 958 |
-</ul> |
|
| 959 |
- |
|
| 960 |
-<p>Instances of both of these condition classes have these slots in addition to the |
|
| 961 |
-standard condition slots: </p> |
|
| 962 |
- |
|
| 963 |
-<table border="1" width="100%"> |
|
| 964 |
- <tr> |
|
| 965 |
- <td width="16%">Name</td> |
|
| 966 |
- <td width="24%">Accessor</td> |
|
| 967 |
- <td width="60%">Value</td> |
|
| 968 |
- </tr> |
|
| 969 |
- <tr> |
|
| 970 |
- <td width="16%">identifier</td> |
|
| 971 |
- <td width="24%">po-condition-identifier</td> |
|
| 972 |
- <td width="60%">keyword describing the kind of condition being signaled. See the |
|
| 973 |
- table below for the possible values.</td> |
|
| 974 |
- </tr> |
|
| 975 |
- <tr> |
|
| 976 |
- <td width="16%">server-string</td> |
|
| 977 |
- <td width="24%">po-condition-server-string</td> |
|
| 978 |
- <td width="60%">If the condition was created because of a messages sent from the mailbox |
|
| 979 |
- server then this is that message.</td> |
|
| 980 |
- </tr> |
|
| 981 |
-</table> |
|
| 982 |
- |
|
| 983 |
-<p>The meaning of the identifier value is as follows</p> |
|
| 984 |
- |
|
| 985 |
-<table border="1" width="100%"> |
|
| 986 |
- <tr> |
|
| 987 |
- <td width="11%"><strong>Identifier</strong></td> |
|
| 988 |
- <td width="13%">Kind</td> |
|
| 989 |
- <td width="76%">Meaning</td> |
|
| 990 |
- </tr> |
|
| 991 |
- <tr> |
|
| 992 |
- <td width="11%"><strong>:problem</strong></td> |
|
| 993 |
- <td width="13%">po-condition</td> |
|
| 994 |
- <td width="76%">The server has responded with a warning message. The most |
|
| 995 |
- likely warning is that the mailbox can only be opened in read-only mode due to another |
|
| 996 |
- processing using it.</td> |
|
| 997 |
- </tr> |
|
| 998 |
- <tr> |
|
| 999 |
- <td width="11%"><strong>:unknown-ok</strong></td> |
|
| 1000 |
- <td width="13%">po-condition</td> |
|
| 1001 |
- <td width="76%">The server has sent an informative message that we don't understand. |
|
| 1002 |
- It's probably safe to ignore this.</td> |
|
| 1003 |
- </tr> |
|
| 1004 |
- <tr> |
|
| 1005 |
- <td width="11%"><strong>:unknown-untagged</strong></td> |
|
| 1006 |
- <td width="13%">po-condition</td> |
|
| 1007 |
- <td width="76%">The server has sent an informative message that we don't understand. |
|
| 1008 |
- It's probably safe to ignore this.</td> |
|
| 1009 |
- </tr> |
|
| 1010 |
- <tr> |
|
| 1011 |
- <td width="11%"><strong>:error-response</strong></td> |
|
| 1012 |
- <td width="13%">po-error</td> |
|
| 1013 |
- <td width="76%">The server cannot execute the requested command.</td> |
|
| 1014 |
- </tr> |
|
| 1015 |
- <tr> |
|
| 1016 |
- <td width="11%"><strong>:syntax-error</strong></td> |
|
| 1017 |
- <td width="13%">po-error</td> |
|
| 1018 |
- <td width="76%">The arguments to a function in this package are malformed.</td> |
|
| 1019 |
- </tr> |
|
| 1020 |
- <tr> |
|
| 1021 |
- <td width="11%"><strong>:unexpected</strong></td> |
|
| 1022 |
- <td width="13%">po-error</td> |
|
| 1023 |
- <td width="76%">The server has responded a way we don't understand and which prevents us |
|
| 1024 |
- from continuing</td> |
|
| 1025 |
- </tr> |
|
| 1026 |
- <tr> |
|
| 1027 |
- <td width="11%"><strong>:server-shutdown-connection</strong></td> |
|
| 1028 |
- <td width="13%">po-error</td> |
|
| 1029 |
- <td width="76%">The connection to the server has been broken. This usually occurs |
|
| 1030 |
- when the connection has been idle for too long and the server intentionally disconnects. |
|
| 1031 |
- Just before this condition is signaled we close down the socket connection to |
|
| 1032 |
- free up the socket resource on our side. When this condition is signaled the user |
|
| 1033 |
- program should not use the mailbox object again (even to call <strong>close-connection</strong> |
|
| 1034 |
- on it).</td> |
|
| 1035 |
- </tr> |
|
| 1036 |
- <tr> |
|
| 1037 |
- <td width="11%"><strong>:timeout</strong></td> |
|
| 1038 |
- <td width="13%">po-error</td> |
|
| 1039 |
- <td width="76%">The server did not respond quickly enough. The timeout value |
|
| 1040 |
- is set in the call to <strong>make-imap-connection.</strong></td> |
|
| 1041 |
- </tr> |
|
| 1042 |
-</table> |
|
| 1043 |
- |
|
| 1044 |
-<h1><a name="smtp"></a>The smtp interface</h1> |
|
| 1045 |
- |
|
| 1046 |
-<p>With the smtp interface, a Lisp program can contact a mail server and send electronic |
|
| 1047 |
-mail. The contents of the message must be a simple text string. There is |
|
| 1048 |
-no provision for encoding binary data and sending it as a Mime attachment.</p> |
|
| 1049 |
- |
|
| 1050 |
-<p> </p> |
|
| 1051 |
- |
|
| 1052 |
-<p><font face="Courier New"><strong>(send-letter mail-server from to message &key |
|
| 1053 |
-subject reply-to)</strong></font></p> |
|
| 1054 |
- |
|
| 1055 |
-<p><strong>mail-server</strong> can be a string naming a machine or an integer IP address. |
|
| 1056 |
- The <strong>mail-server</strong> is contacted and asked to send a <strong>message</strong> |
|
| 1057 |
-(a string) <strong>from</strong> a given email address <strong>to</strong> a given email |
|
| 1058 |
-address or list of addresses. The email addresses must be of the form |
|
| 1059 |
-"foo" or <a href="mailto:foo@bar.com">"foo@bar.com"</a>. You can |
|
| 1060 |
-<strong>not</strong> use addresses like <a href="mailto:Joe%20%3cfoo@bar.com%3e">"Joe |
|
| 1061 |
-<foo@bar.com>"</a> or <a href="mailto:(Joe)%20foo@bar.com">"(Joe) |
|
| 1062 |
-foo@bar.com"</a>. </p> |
|
| 1063 |
- |
|
| 1064 |
-<p>A mail header is built and prepended to the <strong>message</strong> before it is sent. |
|
| 1065 |
- The mail header includes a <strong>From </strong>and <strong>To</strong> line and |
|
| 1066 |
-will optionally include a <strong>Subject</strong> and <strong>Reply-To</strong> |
|
| 1067 |
-line if those are given in the call to <strong>send-letter.</strong>.</p> |
|
| 1068 |
- |
|
| 1069 |
-<p>The text of the <strong>message</strong> should be lines separated by #\newline's. |
|
| 1070 |
- The <strong>smtp</strong> interface will automatically insert the necessary |
|
| 1071 |
-#\returns's when it transmits the message to the mail server.</p> |
|
| 1072 |
- |
|
| 1073 |
-<p> </p> |
|
| 1074 |
- |
|
| 1075 |
-<p> </p> |
|
| 1076 |
- |
|
| 1077 |
-<p><font face="Courier New"><strong>(send-smtp mail-server from to &rest messages)</strong></font></p> |
|
| 1078 |
- |
|
| 1079 |
-<p><strong>mail-server</strong> can be a string naming a machine or an integer IP address. |
|
| 1080 |
- The <strong>mail-server</strong> is contacted and asked to send a message <strong>from</strong> |
|
| 1081 |
-a given email address <strong>to</strong> a given email address or list of addresses. |
|
| 1082 |
- The email addresses must be of the form "foo" or <a |
|
| 1083 |
-href="mailto:foo@bar.com">"foo@bar.com"</a>. You can <strong>not</strong> |
|
| 1084 |
-use addresses like <a href="mailto:Joe%20%3cfoo@bar.com%3e">"Joe |
|
| 1085 |
-<foo@bar.com>"</a> or <a href="mailto:(Joe)%20foo@bar.com">"(Joe) |
|
| 1086 |
-foo@bar.com"</a>. </p> |
|
| 1087 |
- |
|
| 1088 |
-<p>The message sent is a concatenation of all of the <strong>messages</strong> (which |
|
| 1089 |
-should be strings). A header is <strong>not</strong> prepended to the message. |
|
| 1090 |
- This means that the application program can build its own header if it wants to |
|
| 1091 |
-include in that header more than <strong>send-letter</strong> supports (e.g. a Mime |
|
| 1092 |
-encoded attachment). If no header is provided then some mail servers (e.g. <strong>sendmail</strong>) |
|
| 1093 |
-will notice this fact and will automatically create a header.</p> |
|
| 1094 |
- |
|
| 1095 |
-<p>The text of the <strong>messages</strong> should be lines separated by #\newline's. |
|
| 1096 |
- The <strong>smtp</strong> interface will automatically insert the necessary |
|
| 1097 |
-#\returns's when it transmits the message to the mail server.</p> |
|
| 1098 |
- |
|
| 1099 |
-<p> </p> |
|
| 1100 |
- |
|
| 1101 |
-<p> </p> |
|
| 1102 |
- |
|
| 1103 |
-<p> </p> |
|
| 1104 |
- |
|
| 1105 |
-<p> </p> |
|
| 1106 |
-</body> |
|
| 1107 |
-</html> |
|
| 1 |
+<html> |
|
| 2 |
+ |
|
| 3 |
+<head> |
|
| 4 |
+<title>Allegro CL imap and pop interface</title> |
|
| 5 |
+<meta name="GENERATOR" content="Microsoft FrontPage 3.0"> |
|
| 6 |
+</head> |
|
| 7 |
+ |
|
| 8 |
+<body> |
|
| 9 |
+ |
|
| 10 |
+<h1 align="center">Allegro CL imap and pop interface</h1> |
|
| 11 |
+ |
|
| 12 |
+<p align="left">copyright (c) 1999 Franz Inc.</p> |
|
| 13 |
+ |
|
| 14 |
+<p align="left"> </p> |
|
| 15 |
+ |
|
| 16 |
+<p align="left"><strong>imap</strong> is a client-server protocol for processing |
|
| 17 |
+electronic mail boxes. <strong>imap </strong>is the successor to the <strong>pop</strong> |
|
| 18 |
+protocol. It is <strong>not</strong> an upward compatible successor. |
|
| 19 |
+ The main focus of this document is the <strong>imap</strong> |
|
| 20 |
+protocol. Only one small section describes the functions in the <strong>pop</strong> |
|
| 21 |
+interface.</p> |
|
| 22 |
+ |
|
| 23 |
+<p align="left">The contents of this document are:</p> |
|
| 24 |
+ |
|
| 25 |
+<ul> |
|
| 26 |
+ <li><p align="left">the <strong>imap</strong> interface</p> |
|
| 27 |
+ </li> |
|
| 28 |
+ <li><p align="left"><a href="#pop">the <strong>pop</strong> interface</a></p> |
|
| 29 |
+ </li> |
|
| 30 |
+ <li><p align="left"><a href="#conditions">the <strong>conditions</strong> signaled by the <strong>imap</strong> |
|
| 31 |
+ and <strong>pop</strong> interfaces.</a></p> |
|
| 32 |
+ </li> |
|
| 33 |
+ <li><p align="left"><a href="#smtp">the <strong>smtp</strong> interface</a> (used for |
|
| 34 |
+ sending mail)</p> |
|
| 35 |
+ </li> |
|
| 36 |
+</ul> |
|
| 37 |
+ |
|
| 38 |
+<p align="left">The imap interface is based on the Imap4rev1 protocol described in |
|
| 39 |
+rfc2060. Where this document is describing the actions of the imap commands it |
|
| 40 |
+should be considered a secondary source of information about those commands and rfc2060 |
|
| 41 |
+should be considered the primary source.</p> |
|
| 42 |
+ |
|
| 43 |
+<p align="left">The advantages of <strong>imap</strong> over <strong>pop</strong> are:</p> |
|
| 44 |
+ |
|
| 45 |
+<ol> |
|
| 46 |
+ <li><p align="left"><strong>imap </strong>can work with multiple mailboxes (<strong>pop </strong>works |
|
| 47 |
+ with a single mailbox)</p> |
|
| 48 |
+ </li> |
|
| 49 |
+ <li><p align="left">With <strong>imap</strong> you're encouraged to leave mail in mailboxes |
|
| 50 |
+ on the server machine, thus it can be read from any machine on the network. |
|
| 51 |
+ With <strong>pop</strong> you're encouraged to download the mail to the client machine's |
|
| 52 |
+ disk, and it thus becomes inaccessible to all other client machines.</p> |
|
| 53 |
+ </li> |
|
| 54 |
+ <li><p align="left"><strong>imap</strong> parses the headers of messages thus allowing |
|
| 55 |
+ easier analysis of mail messages by the client program.</p> |
|
| 56 |
+ </li> |
|
| 57 |
+ <li><p align="left"><strong>imap</strong> supports searching messages for data and sorting |
|
| 58 |
+ by date.</p> |
|
| 59 |
+ </li> |
|
| 60 |
+ <li><p align="left"><strong>imap </strong>supports annotating messages with flags, thus |
|
| 61 |
+ making subsequent searching easier.</p> |
|
| 62 |
+ </li> |
|
| 63 |
+</ol> |
|
| 64 |
+ |
|
| 65 |
+<p align="left"> </p> |
|
| 66 |
+ |
|
| 67 |
+<h1 align="left">Package</h1> |
|
| 68 |
+ |
|
| 69 |
+<p align="left">The functions in this interface are defined in the <strong>net.post-office</strong> |
|
| 70 |
+package. The previous version of this module gave this package the <strong>po</strong> |
|
| 71 |
+nickname. We've removed that nickname to reduce the possibility of clashing with |
|
| 72 |
+user-defined packages. You are free to add that nickname back if you so desire.</p> |
|
| 73 |
+ |
|
| 74 |
+<p align="left"> </p> |
|
| 75 |
+ |
|
| 76 |
+<h1 align="left">Mailboxes</h1> |
|
| 77 |
+ |
|
| 78 |
+<p align="left">Mailboxes are repositories for messages. Mailboxes are named |
|
| 79 |
+by Lisp strings. The mailbox "inbox" always exists and it is the mailbox |
|
| 80 |
+in which new messages are stored. New mailboxes can be created. |
|
| 81 |
+ They can have simple names, like "foo" or they can have |
|
| 82 |
+hierarchical names (like "clients/california/widgetco"). After |
|
| 83 |
+connecting to an imap server you can determine what string of characters you must use |
|
| 84 |
+between simple names to create a hierarchical name (in this example "/" was the |
|
| 85 |
+separator character). </p> |
|
| 86 |
+ |
|
| 87 |
+<p align="left">Each mailbox has an associated unique number called its <strong>uidvalidity</strong>. |
|
| 88 |
+ This number won't change as long as <strong>imap</strong> is the only |
|
| 89 |
+program used to manipulate the mailbox. In fact if you see that the number has |
|
| 90 |
+changed then that means that some other program has done something to the mailbox that |
|
| 91 |
+destroyed the information that <strong>imap</strong> had been keeping about the |
|
| 92 |
+mailbox. In particular you can't now retrieve messages by their unique |
|
| 93 |
+ids that you had used before.</p> |
|
| 94 |
+ |
|
| 95 |
+<h1 align="left">Messages</h1> |
|
| 96 |
+ |
|
| 97 |
+<p align="left">Messages in a mailbox can be denoted in one of two ways: message |
|
| 98 |
+sequence number or unique id. </p> |
|
| 99 |
+ |
|
| 100 |
+<p align="left">The <em>message sequence number</em> is the normal way. The messages |
|
| 101 |
+in a mailbox are numbered from 1 to N where N is the number of messages in the mailbox. |
|
| 102 |
+ There are never any gaps in the sequence numbers. If you tell <strong>imap</strong> |
|
| 103 |
+to delete messages 3,4 and 5 then it will return a value telling you the it has deleted |
|
| 104 |
+messages 3,3 and 3. This is because when you deleted message 3, message 4 became the |
|
| 105 |
+new message 3 just before it was deleted and then message 5 became message 3 just before |
|
| 106 |
+it was deleted.</p> |
|
| 107 |
+ |
|
| 108 |
+<p align="left">A <em>unique id </em>of a message is a number associated with a message |
|
| 109 |
+that is unique only within a mailbox. As long as the uidvalidity value of a |
|
| 110 |
+mailbox doesn't change, the unique ids used in deleted messages will never be reused for |
|
| 111 |
+new messages. </p> |
|
| 112 |
+ |
|
| 113 |
+<h1 align="left">Flags</h1> |
|
| 114 |
+ |
|
| 115 |
+<p align="left">A flag is a symbol denoting that a message or mailbox has a certain |
|
| 116 |
+property. We use keywords in Lisp to denote flags. There are two |
|
| 117 |
+kinds of flags - System and User flags. System flags begin with the backslash |
|
| 118 |
+character, which is an unfortunate design decision since that means that in Lisp we |
|
| 119 |
+have to remember to use two backslashes (e.g. <strong>:\\deleted</strong>). |
|
| 120 |
+ A subset of the flags can be stored permanently in the mailbox with the |
|
| 121 |
+messages. When a connection is made to an <strong>imap</strong> server it will |
|
| 122 |
+return the list of flags and permanent flags (and these are stored in the mailbox object |
|
| 123 |
+returned for access by the program). If the list of permanent flags includes <strong>:\\*</strong> |
|
| 124 |
+then the program can create its own flag names (not beginning with a backslash) and can |
|
| 125 |
+store them permanently in messages.</p> |
|
| 126 |
+ |
|
| 127 |
+<p align="left">Some of the important system flags are:</p> |
|
| 128 |
+ |
|
| 129 |
+<ul> |
|
| 130 |
+ <li><p align="left"><strong>:\\seen</strong> - this means that the message has been read |
|
| 131 |
+ (a <strong>fetch-letter</strong> has been done that includes the content of the |
|
| 132 |
+ message, not just its headers)</p> |
|
| 133 |
+ </li> |
|
| 134 |
+ <li><p align="left"><strong>:\\deleted </strong>- the message will be deleted the next time |
|
| 135 |
+ an <strong>expunge-mailbox</strong> or <strong>close-mailbox</strong> is done.</p> |
|
| 136 |
+ </li> |
|
| 137 |
+ <li><p align="left"><strong>:\\recent </strong>- this is the first session to have been |
|
| 138 |
+ notified about this message being present in the mailbox.</p> |
|
| 139 |
+ </li> |
|
| 140 |
+</ul> |
|
| 141 |
+ |
|
| 142 |
+<p align="left"> </p> |
|
| 143 |
+ |
|
| 144 |
+<h1 align="left">Connecting to the server</h1> |
|
| 145 |
+ |
|
| 146 |
+<p align="left"> </p> |
|
| 147 |
+ |
|
| 148 |
+<p align="left"><font face="Courier New">(<strong>make-imap-connection host &key user |
|
| 149 |
+password port timeout)</strong></font></p> |
|
| 150 |
+ |
|
| 151 |
+<p align="left">This creates a connection to the <strong>imap</strong> server on machine <strong>host</strong> |
|
| 152 |
+and logs in as <strong>user </strong>with password <strong>password. </strong>The |
|
| 153 |
+<strong>port</strong> argument defaults to143, which is the port on which the <strong>imap</strong> |
|
| 154 |
+server normally listens. The <strong>timeout</strong> argument defaults |
|
| 155 |
+to 30 (seconds) and this value is used to limit the amount of time this imap interface |
|
| 156 |
+code will wait for a response from the server before giving up. In |
|
| 157 |
+certain circumstances the server may get so busy that you see timeout errors signaled in |
|
| 158 |
+this code. In that case you should specify a larger timeout when connecting. </p> |
|
| 159 |
+ |
|
| 160 |
+<p align="left">The <strong>make-imap-connection</strong> function returns a <strong>mailbox</strong> |
|
| 161 |
+object which is then passed to other functions in this interface. From this |
|
| 162 |
+one connection you can access all of the mailboxes owned by <strong>user</strong>.</p> |
|
| 163 |
+ |
|
| 164 |
+<p align="left">After the connection is established a mailbox is <strong>not</strong> |
|
| 165 |
+selected. In this state attempting to execute message access functions may |
|
| 166 |
+result in cryptic error messages from the <strong>imap</strong> server that won't tell you |
|
| 167 |
+what you need to know -- that a mailbox is not selected. Therefore be sure to |
|
| 168 |
+select a mailbox using <strong>select-mailbox</strong> shortly after connecting.</p> |
|
| 169 |
+ |
|
| 170 |
+<p align="left"> </p> |
|
| 171 |
+ |
|
| 172 |
+<p align="left"> </p> |
|
| 173 |
+ |
|
| 174 |
+<p align="left"><strong><font face="Courier New">(close-connection mailbox)</font></strong></p> |
|
| 175 |
+ |
|
| 176 |
+<p align="left">This sends a <strong>logout</strong> command to the <strong>imap</strong> |
|
| 177 |
+server and then closes the socket that's communicating with the <strong>imap</strong> |
|
| 178 |
+server. <strong>mailbox </strong>is the object returned by <strong>make-imap-connection.</strong> |
|
| 179 |
+ This does <em>not</em> close the currently select mailbox before logging out, |
|
| 180 |
+thus messages marked to be deleted in the currently selected mailbox will <em>not</em> be |
|
| 181 |
+removed from the mailbox. Use <strong>close-mailbox</strong> or <strong>expunge-mailbox</strong> |
|
| 182 |
+before calling this <strong>close-connection</strong> to ensure that messages to be |
|
| 183 |
+deleted are deleted.</p> |
|
| 184 |
+ |
|
| 185 |
+<p align="left"> </p> |
|
| 186 |
+ |
|
| 187 |
+<p align="left"> </p> |
|
| 188 |
+ |
|
| 189 |
+<h1 align="left">Mailbox manipulation</h1> |
|
| 190 |
+ |
|
| 191 |
+<p align="left">These functions work on mailboxes as a whole. The <strong>mailbox</strong> |
|
| 192 |
+argument to the functions is is the object returned by <strong>make-imap-connection. |
|
| 193 |
+ </strong>If a return value isn't specified for a function then the return value |
|
| 194 |
+isn't important - if something goes wrong an error will be signaled.</p> |
|
| 195 |
+ |
|
| 196 |
+<p align="left"> </p> |
|
| 197 |
+ |
|
| 198 |
+<p align="left"><font face="Courier New"><strong>(select-mailbox mailbox name)</strong></font></p> |
|
| 199 |
+ |
|
| 200 |
+<p align="left">makes the mailbox named by the string <strong>name</strong> be the current |
|
| 201 |
+mailbox and store statistics about that mailbox in the <strong>mailbox</strong> object |
|
| 202 |
+where they can be retrieved by the accessors described below. The |
|
| 203 |
+selected mailbox is the source for all message manipulation functions.</p> |
|
| 204 |
+ |
|
| 205 |
+<p align="left"> </p> |
|
| 206 |
+ |
|
| 207 |
+<p align="left"><font face="Courier New"><strong>(create-mailbox mailbox name)</strong></font></p> |
|
| 208 |
+ |
|
| 209 |
+<p align="left">creates a new mailbox with the given <strong>name</strong>. It |
|
| 210 |
+is an error if the mailbox already exists. If you want to create a mailbox in a |
|
| 211 |
+hierarchy then you should be sure that it uses the correct hierarchy separator character |
|
| 212 |
+string (see <strong>mailbox-separator)</strong>. You do <strong>not</strong> |
|
| 213 |
+ have to create intermediate levels of the hierarchy yourself -- just provide the |
|
| 214 |
+complete name and the <strong>imap</strong> server will create all necessary levels.</p> |
|
| 215 |
+ |
|
| 216 |
+<p align="left"> </p> |
|
| 217 |
+ |
|
| 218 |
+<p align="left"><font face="Courier New"><strong>(delete-mailbox mailbox name)</strong></font></p> |
|
| 219 |
+ |
|
| 220 |
+<p align="left">deletes the mailbox with the given name.</p> |
|
| 221 |
+ |
|
| 222 |
+<p align="left"> </p> |
|
| 223 |
+ |
|
| 224 |
+<p align="left"><font face="Courier New"><strong>(rename-mailbox mailbox old-name |
|
| 225 |
+new-name)</strong></font></p> |
|
| 226 |
+ |
|
| 227 |
+<p align="left">changes the name of mailbox <strong>old-name</strong> to <strong>new-name</strong>. |
|
| 228 |
+ It's an error if <strong>new-name</strong> already exists. There's a special |
|
| 229 |
+behavior if <strong>old-name</strong> is "inbox". In this case all of the |
|
| 230 |
+messages in "inbox" are moved to <strong>new-name </strong>mailbox, but the |
|
| 231 |
+"inbox" mailbox continues to exist. Note: The <strong>imap </strong>server |
|
| 232 |
+supplied with Linux does <strong>not</strong> support this special behavior of renaming |
|
| 233 |
+"inbox".</p> |
|
| 234 |
+ |
|
| 235 |
+<p align="left"> </p> |
|
| 236 |
+ |
|
| 237 |
+<p align="left"><strong><font face="Courier New">(mailbox-list mailbox &key reference |
|
| 238 |
+pattern)</font></strong></p> |
|
| 239 |
+ |
|
| 240 |
+<p align="left">returns a list of items describing the mailboxes that match the arguments. |
|
| 241 |
+ The <strong>reference</strong> is the root of the hierarchy to |
|
| 242 |
+scan. By default is is the empty string (from which all mailboxes are reachable). |
|
| 243 |
+ The <strong>pattern </strong>is a string matched against all mailbox |
|
| 244 |
+names reachable from <strong>reference. </strong>There are two special characters allowed |
|
| 245 |
+in the <strong>pattern: </strong>Asterisk (*) matches all characters including |
|
| 246 |
+hierarchy delimiters. Percent (%) matches all characters but not the hierarchy |
|
| 247 |
+delimiter. Thus</p> |
|
| 248 |
+ |
|
| 249 |
+<p align="center"><font face="Courier New">(mailbox-list mailbox :pattern "*")</font></p> |
|
| 250 |
+ |
|
| 251 |
+<p align="left">returns a list of all mailboxes at all depths in the hierarchy. |
|
| 252 |
+ </p> |
|
| 253 |
+ |
|
| 254 |
+<p align="left">The value returned is a list of lists, but we've created the <strong>mailbox-list |
|
| 255 |
+</strong>struct definition in order to make accessing the parts of the inner lists |
|
| 256 |
+easier. The accessors for that structure are:</p> |
|
| 257 |
+ |
|
| 258 |
+<p align="left"> </p> |
|
| 259 |
+ |
|
| 260 |
+<p align="left"><font face="Courier New"><strong>(mailbox-list-flags mailbox-list) </strong></font></p> |
|
| 261 |
+ |
|
| 262 |
+<p align="left">returns the flags describing this entry. The most important |
|
| 263 |
+flag to check is <strong>:\\noselect</strong> as this specifies that this is not a mailbox |
|
| 264 |
+but instead just a directory in the hierarchy of mailboxes. The flag <strong>:\\noinferiors</strong> |
|
| 265 |
+specifies that you can't create a hierarchical mailbox name with this as a prefix. |
|
| 266 |
+ This flag is often associated with the special mailbox "inbox".</p> |
|
| 267 |
+ |
|
| 268 |
+<p align="left"> </p> |
|
| 269 |
+ |
|
| 270 |
+<p align="left"><font face="Courier New"><strong>(mailbox-list-separator mailbox-list)</strong></font></p> |
|
| 271 |
+ |
|
| 272 |
+<p align="left">returns a string containing the characters used to separate names in a |
|
| 273 |
+hierarchical name.</p> |
|
| 274 |
+ |
|
| 275 |
+<p align="left"> </p> |
|
| 276 |
+ |
|
| 277 |
+<p align="left"><font face="Courier New"><strong>(mailbox-list-name mailbox-list)</strong></font></p> |
|
| 278 |
+ |
|
| 279 |
+<p align="left">returns the name of the mailbox or directory (see mailbox-list-flags to |
|
| 280 |
+determine which it is).</p> |
|
| 281 |
+ |
|
| 282 |
+<p align="left"> </p> |
|
| 283 |
+ |
|
| 284 |
+<h1 align="left">Message manipulation</h1> |
|
| 285 |
+ |
|
| 286 |
+<p align="left">These functions work with the messages in the currently selected mailbox. |
|
| 287 |
+ The <strong>mailbox</strong> argument is the object returned by <strong>make-imap-connection.</strong> |
|
| 288 |
+ The <strong>messages</strong> argument is either a number (denoting a single |
|
| 289 |
+message), or is the list <strong>(:seq N M) </strong>denoting messages <strong>N</strong> |
|
| 290 |
+through <strong>M, </strong>or is a list of numbers and <strong>:seq </strong>forms |
|
| 291 |
+denoting the messages specified in the list.</p> |
|
| 292 |
+ |
|
| 293 |
+<p align="left"> </p> |
|
| 294 |
+ |
|
| 295 |
+<p align="left">(<font face="Courier New"><strong>alter-flags mailbox messages &key |
|
| 296 |
+flags add-flags remove-flags silent uid)</strong></font></p> |
|
| 297 |
+ |
|
| 298 |
+<p>changes the flags of the messages in the specified way. Exactly one of <strong>flags, |
|
| 299 |
+add-flags</strong>, and <strong>remove-flags</strong> must be specified. <strong>flags</strong> |
|
| 300 |
+specifies the complete set of flags to be stores in the <strong>messages</strong> and the |
|
| 301 |
+other two add or remove flags. If <strong>uid</strong> is true then <strong>messages</strong> |
|
| 302 |
+will be interpreted as unique ids rather than message sequence numbers. |
|
| 303 |
+ Normally <strong>alter-flags</strong> returns a data structure |
|
| 304 |
+that describes the state of the flags after the alternation has been done. This data |
|
| 305 |
+structure can be examined with the <strong>fetch-field</strong> function. |
|
| 306 |
+ If <strong>silent</strong> is true then this data structure won't be created |
|
| 307 |
+thus saving some time and space.</p> |
|
| 308 |
+ |
|
| 309 |
+<p>Removing a message from a mailbox is done by adding the <strong>:\\deleted</strong> |
|
| 310 |
+flag to the message and then either calling <strong>close-mailbox </strong>or <strong>expunge-mailbox.</strong></p> |
|
| 311 |
+ |
|
| 312 |
+<p> </p> |
|
| 313 |
+ |
|
| 314 |
+<p><font face="Courier New"><strong>(close-mailbox mailbox)</strong></font></p> |
|
| 315 |
+ |
|
| 316 |
+<p>permanently removes all messages flagged as <strong>:\\deleted</strong> from the |
|
| 317 |
+currently selected mailbox and then un-selects the currently selected mailbox. After |
|
| 318 |
+this command has finished there is no currently selected mailbox.</p> |
|
| 319 |
+ |
|
| 320 |
+<p align="left"> </p> |
|
| 321 |
+ |
|
| 322 |
+<p align="left"><strong><font face="Courier New">(copy-to-mailbox mailbox messages |
|
| 323 |
+destination &key uid)</font></strong></p> |
|
| 324 |
+ |
|
| 325 |
+<p align="left">copies the specified <strong>messages </strong>from the currently selected |
|
| 326 |
+mailbox to the mailbox named <strong>destination</strong> (given as a string). The |
|
| 327 |
+flags are copied as well. The destination mailbox must already exist. The messages |
|
| 328 |
+are <strong>not</strong> removed from the selected mailbox after the copy .If <strong>uid</strong> |
|
| 329 |
+is true then the <strong>messages</strong> are considered to be unique ids rather than |
|
| 330 |
+message sequence numbers. </p> |
|
| 331 |
+ |
|
| 332 |
+<p align="left"> </p> |
|
| 333 |
+ |
|
| 334 |
+<p align="left"><font face="Courier New"><strong>(delete-letter mailbox messages &key |
|
| 335 |
+expunge uid</strong></font>)</p> |
|
| 336 |
+ |
|
| 337 |
+<p align="left">Mark the <strong>messages</strong> for deletion and then remove them |
|
| 338 |
+permanently (using <strong>expunge-mailbox</strong>) if <strong>expunge</strong> is true. |
|
| 339 |
+ <strong>expunge </strong>defaults to true. If <strong>uid</strong> |
|
| 340 |
+is true then the message numbers are unique ids instead of messages sequence numbers.</p> |
|
| 341 |
+ |
|
| 342 |
+<p align="left"> </p> |
|
| 343 |
+ |
|
| 344 |
+<p align="left"><font face="Courier New"><strong>(expunge-mailbox mailbox)</strong></font></p> |
|
| 345 |
+ |
|
| 346 |
+<p align="left">permanently removes all messages flagged as <strong>:\\deleted</strong> |
|
| 347 |
+from the currently selected mailbox. The currently selected mailbox stays |
|
| 348 |
+selected.</p> |
|
| 349 |
+ |
|
| 350 |
+<p align="left"> </p> |
|
| 351 |
+ |
|
| 352 |
+<p align="left"><font face="Courier New"><strong>(fetch-field message part info &key |
|
| 353 |
+uid)</strong></font></p> |
|
| 354 |
+ |
|
| 355 |
+<p align="left">is used to extract the desired information from the value returned by <strong>fetch-letter</strong>. |
|
| 356 |
+ With <strong>fetch-letter</strong> you can retrieve a variety of |
|
| 357 |
+information about one or more messages and <strong>fetch-field</strong> can search though |
|
| 358 |
+that information and return a particular piece of information about a particular |
|
| 359 |
+letter. <strong>message</strong> is the message number (it's assumed to be a |
|
| 360 |
+message sequence number unless <strong>uid </strong>is true, in which case it's a unique |
|
| 361 |
+id). <strong>part </strong>is the type of information desired. It is a |
|
| 362 |
+string just as used in the call to <strong>fetch-letter</strong>.</p> |
|
| 363 |
+ |
|
| 364 |
+<p align="left"> </p> |
|
| 365 |
+ |
|
| 366 |
+<p align="left"><strong><font face="Courier New">(fetch-letter mailbox message &key |
|
| 367 |
+uid)</font></strong></p> |
|
| 368 |
+ |
|
| 369 |
+<p align="left">Return the complete message, headers and body, as one big string. |
|
| 370 |
+This is a combination of <strong>fetch-field</strong> and <strong>fetch-parts</strong> |
|
| 371 |
+where the part specification is "body[]".</p> |
|
| 372 |
+ |
|
| 373 |
+<p align="left"> </p> |
|
| 374 |
+ |
|
| 375 |
+<p align="left"><font face="Courier New"><strong>(fetch-parts mailbox messages parts |
|
| 376 |
+&key uid)</strong></font></p> |
|
| 377 |
+ |
|
| 378 |
+<p align="left">retrieves the specified <strong>parts</strong> of the specified <strong>messages. |
|
| 379 |
+ </strong>If <strong>uid</strong> is true then the <strong>messages</strong> |
|
| 380 |
+are considered to be unique ids rather than message sequence numbers. |
|
| 381 |
+ The description of what can be specified for <strong>parts </strong>is |
|
| 382 |
+quite complex and is described in the section below "Fetching a Letter".</p> |
|
| 383 |
+ |
|
| 384 |
+<p align="left">The return value from this function is a structure that can be examined |
|
| 385 |
+with <strong>fetch-field</strong>.</p> |
|
| 386 |
+ |
|
| 387 |
+<p align="left">When the result returned includes an envelope value the following |
|
| 388 |
+functions can be used to extract the components of the envelope:</p> |
|
| 389 |
+ |
|
| 390 |
+<ul> |
|
| 391 |
+ <li><p align="left"><font face="Courier New"><strong>envelope-date</strong></font></p> |
|
| 392 |
+ </li> |
|
| 393 |
+ <li><p align="left"><font face="Courier New"><strong>envelope-subject</strong></font></p> |
|
| 394 |
+ </li> |
|
| 395 |
+ <li><p align="left"><font face="Courier New"><strong>envelope-from</strong></font></p> |
|
| 396 |
+ </li> |
|
| 397 |
+ <li><p align="left"><font face="Courier New"><strong>envelope-sender</strong></font></p> |
|
| 398 |
+ </li> |
|
| 399 |
+ <li><p align="left"><font face="Courier New"><strong>envelope-reply-to</strong></font></p> |
|
| 400 |
+ </li> |
|
| 401 |
+ <li><p align="left"><font face="Courier New"><strong>envelope-to</strong></font></p> |
|
| 402 |
+ </li> |
|
| 403 |
+ <li><p align="left"><font face="Courier New"><strong>envelope-cc</strong></font></p> |
|
| 404 |
+ </li> |
|
| 405 |
+ <li><p align="left"><font face="Courier New"><strong>envelope-bcc</strong></font></p> |
|
| 406 |
+ </li> |
|
| 407 |
+ <li><p align="left"><font face="Courier New"><strong>envelope-in-reply-to</strong></font></p> |
|
| 408 |
+ </li> |
|
| 409 |
+ <li><p align="left"><font face="Courier New"><strong>envelope-message-id</strong></font></p> |
|
| 410 |
+ </li> |
|
| 411 |
+</ul> |
|
| 412 |
+ |
|
| 413 |
+<p align="left"> </p> |
|
| 414 |
+ |
|
| 415 |
+<p align="left"> </p> |
|
| 416 |
+ |
|
| 417 |
+<p align="left"><strong><font face="Courier New">(noop mailbox)</font></strong></p> |
|
| 418 |
+ |
|
| 419 |
+<p align="left">does nothing but remind the <strong>imap</strong> server that this |
|
| 420 |
+client is still active, thus resetting the timers used in the server that will |
|
| 421 |
+automatically shut down this connection after a period of inactivity. Like all |
|
| 422 |
+other commands if messages have been added to the currently selected mailbox, the server |
|
| 423 |
+will return the new message count as a response to the <strong>noop</strong> command, and |
|
| 424 |
+this can be check using <strong>mailbox-message-count</strong>. </p> |
|
| 425 |
+ |
|
| 426 |
+<p align="left"> </p> |
|
| 427 |
+ |
|
| 428 |
+<p align="left"><font face="Courier New"><strong>(search-mailbox mailbox search-expression |
|
| 429 |
+&key uid)</strong></font></p> |
|
| 430 |
+ |
|
| 431 |
+<p align="left">return a list of messages in the mailbox that satisfy the<strong> |
|
| 432 |
+search-expression. </strong>If <strong>uid</strong> is true then unique ids |
|
| 433 |
+will be returned instead of message sequence numbers. See the section |
|
| 434 |
+"Searching for messages" for details on the <strong>search-expression</strong>.</p> |
|
| 435 |
+ |
|
| 436 |
+<p align="left"> </p> |
|
| 437 |
+ |
|
| 438 |
+<h1 align="left">Mailbox Accessors</h1> |
|
| 439 |
+ |
|
| 440 |
+<p align="left">The mailbox object contains information about the <strong>imap </strong>server |
|
| 441 |
+it's connected to as well as the currently selected mailbox. This information |
|
| 442 |
+can potentially be updated each time a request is made to the <strong>imap </strong>server. |
|
| 443 |
+ The following functions access values from the mailbox object. </p> |
|
| 444 |
+ |
|
| 445 |
+<p align="left"><font face="Courier New"><strong>(mailbox-flags mailbox)</strong></font></p> |
|
| 446 |
+ |
|
| 447 |
+<p align="left">returns a complete list of flags used in all the messages in this mailbox.</p> |
|
| 448 |
+ |
|
| 449 |
+<p align="left"> </p> |
|
| 450 |
+ |
|
| 451 |
+<p align="left"><font face="Courier New"><strong>(mailbox-permanent-flags mailbox)</strong></font></p> |
|
| 452 |
+ |
|
| 453 |
+<p align="left">returns a list of flags that can be stored permanently in a message. |
|
| 454 |
+ If the flag <strong>:\\*</strong> is present then it means that the client can |
|
| 455 |
+create its own flags.</p> |
|
| 456 |
+ |
|
| 457 |
+<p align="left"> </p> |
|
| 458 |
+ |
|
| 459 |
+<p align="left"><font face="Courier New"><strong>(mailbox-message-count mailbox)</strong></font></p> |
|
| 460 |
+ |
|
| 461 |
+<p align="left">returns the number of messages in the currently selected mailbox</p> |
|
| 462 |
+ |
|
| 463 |
+<p align="left"> </p> |
|
| 464 |
+ |
|
| 465 |
+<p align="left"><font face="Courier New"><strong>(mailbox-recent-messages mailbox)</strong></font></p> |
|
| 466 |
+ |
|
| 467 |
+<p align="left">returns the number of messages have just arrived in the mailbox.</p> |
|
| 468 |
+ |
|
| 469 |
+<p align="left"> </p> |
|
| 470 |
+ |
|
| 471 |
+<p align="left"><font face="Courier New"><strong>(mailbox-separator mailbox)</strong></font></p> |
|
| 472 |
+ |
|
| 473 |
+<p align="left">returns the hierarchy separator string for this <strong>imap </strong>server.</p> |
|
| 474 |
+ |
|
| 475 |
+<p align="left"> </p> |
|
| 476 |
+ |
|
| 477 |
+<p align="left"><font face="Courier New"><strong>(mailbox-uidnext mailbox)</strong></font></p> |
|
| 478 |
+ |
|
| 479 |
+<p align="left">returns the value predicated to be the unique id assigned to the |
|
| 480 |
+next message.</p> |
|
| 481 |
+ |
|
| 482 |
+<p align="left"> </p> |
|
| 483 |
+ |
|
| 484 |
+<p align="left"><font face="Courier New"><strong>(mailbox-uidvalidty mailbox)</strong></font></p> |
|
| 485 |
+ |
|
| 486 |
+<p align="left">returns the uidvalidity value for the currently selected mailbox.</p> |
|
| 487 |
+ |
|
| 488 |
+<p align="left"> </p> |
|
| 489 |
+ |
|
| 490 |
+<p align="left"> </p> |
|
| 491 |
+ |
|
| 492 |
+<h1 align="left">Fetching a Letter</h1> |
|
| 493 |
+ |
|
| 494 |
+<p align="left">When using <strong>fetch-parts</strong> to access letters, you must |
|
| 495 |
+specify the parts of the messages in which you're interested. There are a wide |
|
| 496 |
+variety of specifiers, some redundant and overlapping, described in the imap specification |
|
| 497 |
+in rfe2060. We'll describe the most common ones here. The specification |
|
| 498 |
+is always a string but it may be specified more than one thing by the use of parentheses |
|
| 499 |
+in the string, e.g. "(flags envelope)". </p> |
|
| 500 |
+ |
|
| 501 |
+<p align="left">The most common specifiers are:</p> |
|
| 502 |
+ |
|
| 503 |
+<ul> |
|
| 504 |
+ <li><p align="left"><strong>body[]</strong> - this returns the full message: headers and |
|
| 505 |
+ body. You can use <strong>fetch-letter</strong> if you only want this part and |
|
| 506 |
+ you want to avoid having to call <strong>fetch-field</strong>.</p> |
|
| 507 |
+ </li> |
|
| 508 |
+ <li><p align="left"><strong>body[text]</strong> - this returns just the the text of the body |
|
| 509 |
+ of the message, not the header.</p> |
|
| 510 |
+ </li> |
|
| 511 |
+ <li><p align="left"><strong>body</strong> - this returns a list describing the structure of |
|
| 512 |
+ the message.</p> |
|
| 513 |
+ </li> |
|
| 514 |
+ <li><p align="left"><strong>envelope</strong> - this parses the header and returns a list of |
|
| 515 |
+ information in it. We've defined a set of accessors <strong>(</strong>like<strong> |
|
| 516 |
+ envelope-xxx</strong>) that allow you to retrieve the envelope information easily.</p> |
|
| 517 |
+ </li> |
|
| 518 |
+ <li><p align="left"><strong>flags</strong> - return a list of the flags in the message</p> |
|
| 519 |
+ </li> |
|
| 520 |
+ <li><p align="left"><strong>uid</strong> - the unique identifier of the message</p> |
|
| 521 |
+ </li> |
|
| 522 |
+</ul> |
|
| 523 |
+ |
|
| 524 |
+<p align="left"> </p> |
|
| 525 |
+ |
|
| 526 |
+<p align="left">The result of a <strong>fetch-parts</strong> is a data structure |
|
| 527 |
+containing all of the requested information. The <strong>fetch-field</strong> |
|
| 528 |
+function is then used to extract the particular information for the particular message.</p> |
|
| 529 |
+ |
|
| 530 |
+<p align="left"> </p> |
|
| 531 |
+ |
|
| 532 |
+<h1 align="left">Searching for Messages</h1> |
|
| 533 |
+ |
|
| 534 |
+<p align="left">.The <strong>imap</strong> server is able to search for messages matching |
|
| 535 |
+a search expression. A search-expression is a predicate or one of |
|
| 536 |
+these forms:</p> |
|
| 537 |
+ |
|
| 538 |
+<ul> |
|
| 539 |
+ <li><p align="left">(<strong>and</strong> search-expression ...)</p> |
|
| 540 |
+ </li> |
|
| 541 |
+ <li><p align="left">(<strong>or</strong> search-expression ...)</p> |
|
| 542 |
+ </li> |
|
| 543 |
+ <li><p align="left">(<strong>not</strong> search-expression)</p> |
|
| 544 |
+ </li> |
|
| 545 |
+</ul> |
|
| 546 |
+ |
|
| 547 |
+<p align="left">A predicate is </p> |
|
| 548 |
+ |
|
| 549 |
+<ul> |
|
| 550 |
+ <li><p align="left">a number in which case the predicate is true if and only if we're are |
|
| 551 |
+ considering this message</p> |
|
| 552 |
+ </li> |
|
| 553 |
+ <li><p align="left">a <strong>(:seq N M)</strong> expression that is true if we're |
|
| 554 |
+ considering messages N through M.</p> |
|
| 555 |
+ </li> |
|
| 556 |
+ <li><p align="left"><strong>:all</strong> - this predicate is always true</p> |
|
| 557 |
+ </li> |
|
| 558 |
+ <li><p align="left"><strong>:answered</strong> - true if the message has the <strong>:\\answered</strong> |
|
| 559 |
+ flag</p> |
|
| 560 |
+ </li> |
|
| 561 |
+ <li><p align="left"><strong>(:bcc "string") </strong>- true if the envelope |
|
| 562 |
+ structure's bcc field contains this "string".</p> |
|
| 563 |
+ </li> |
|
| 564 |
+ <li><p align="left"><strong>(:before date)</strong> - true if the messages internal date is |
|
| 565 |
+ before this date. The date can either be a string in the rfc822 form (e.g. |
|
| 566 |
+ "7-Mar-1999") or a lisp universal time.</p> |
|
| 567 |
+ </li> |
|
| 568 |
+ <li><p align="left"><strong>(:body "string") </strong>- true if the body of the |
|
| 569 |
+ message contains "string"</p> |
|
| 570 |
+ </li> |
|
| 571 |
+ <li><p align="left"><strong>(:cc "string")</strong> - true if the envelope |
|
| 572 |
+ structure's cc field contains this "string".</p> |
|
| 573 |
+ </li> |
|
| 574 |
+ <li><p align="left"><strong>:deleted</strong> - true if the <strong>:\\deleted</strong> flag |
|
| 575 |
+ is set for this message</p> |
|
| 576 |
+ </li> |
|
| 577 |
+ <li><p align="left"><strong>:draft</strong> - true if the <strong>:\\draft </strong>flag is |
|
| 578 |
+ set for this message</p> |
|
| 579 |
+ </li> |
|
| 580 |
+ <li><p align="left"><strong>:flagged </strong>- true if the <strong>:\\flagged</strong> flag |
|
| 581 |
+ is set for this message</p> |
|
| 582 |
+ </li> |
|
| 583 |
+ <li><p align="left"><strong>(:from "string")</strong> - true if the envelope |
|
| 584 |
+ structure's from field contains this "string".</p> |
|
| 585 |
+ </li> |
|
| 586 |
+ <li><p align="left"><strong>(:header "field" "string")</strong> - true |
|
| 587 |
+ if the message contains a header named "field" and its value contains |
|
| 588 |
+ "string".</p> |
|
| 589 |
+ </li> |
|
| 590 |
+ <li><p align="left"><strong>(:keyword flag)</strong> - true if the specified flag is set for |
|
| 591 |
+ this message</p> |
|
| 592 |
+ </li> |
|
| 593 |
+ <li><p align="left"><strong>(:larger N)</strong> - true if the rfc822 size of the message is |
|
| 594 |
+ larger than N.</p> |
|
| 595 |
+ </li> |
|
| 596 |
+ <li><p align="left"><strong>:new </strong>- true if the message has the <strong>:\\recent</strong> |
|
| 597 |
+ flag set but not the <strong>:\\seen </strong>flag.</p> |
|
| 598 |
+ </li> |
|
| 599 |
+ <li><p align="left"><strong>:seen </strong>- true if the message has the <strong>:\\seen </strong>flag |
|
| 600 |
+ set.</p> |
|
| 601 |
+ </li> |
|
| 602 |
+ <li><p align="left"><strong>(:sentbefore date)</strong> - true if the message's Date header |
|
| 603 |
+ is earlier than the given date. See the description of :before for the format of |
|
| 604 |
+ dates.</p> |
|
| 605 |
+ </li> |
|
| 606 |
+ <li><p align="left"><strong>(:senton date)</strong> - true if the message's Date header is |
|
| 607 |
+ within the specified date.</p> |
|
| 608 |
+ </li> |
|
| 609 |
+ <li><p align="left"><strong>(:sentsince date) </strong>- true if the message's Date header |
|
| 610 |
+ is within or since the given date.</p> |
|
| 611 |
+ </li> |
|
| 612 |
+ <li><p align="left"><strong>(:smaller N)</strong> - true if the rfc822 size of the message |
|
| 613 |
+ is smaller than N</p> |
|
| 614 |
+ </li> |
|
| 615 |
+ <li><p align="left"><strong>(:subject "string") </strong>- true if the Subject |
|
| 616 |
+ header line of the message contains "string"</p> |
|
| 617 |
+ </li> |
|
| 618 |
+ <li><p align="left"><strong>(:text "string") </strong>- true if the message's |
|
| 619 |
+ header or body contains the specified "string"</p> |
|
| 620 |
+ </li> |
|
| 621 |
+ <li><p align="left"><strong>(:to "string")</strong> - true if the envelope |
|
| 622 |
+ structure's to field contains this "string".</p> |
|
| 623 |
+ </li> |
|
| 624 |
+ <li><p align="left"><strong>(:uid message-set)</strong> - true if the message is one of the |
|
| 625 |
+ message denoted by the message set, where the message set describes messages by unique id.</p> |
|
| 626 |
+ </li> |
|
| 627 |
+ <li><p align="left"><strong>:unanswered</strong> - true if the message does not have the <strong>:\\answered</strong> |
|
| 628 |
+ flag set</p> |
|
| 629 |
+ </li> |
|
| 630 |
+ <li><p align="left"><strong>:undeleted</strong> - true if the message does not have the <strong>:\\deleted</strong> |
|
| 631 |
+ flag set</p> |
|
| 632 |
+ </li> |
|
| 633 |
+ <li><p align="left"><strong>:undraft </strong>- true if the message does not have the <strong>:\\draft |
|
| 634 |
+ </strong>flag set.</p> |
|
| 635 |
+ </li> |
|
| 636 |
+ <li><p align="left"><strong>:unflagged </strong>- true if the message does not have the <strong>:\\flagged</strong> |
|
| 637 |
+ flag set.</p> |
|
| 638 |
+ </li> |
|
| 639 |
+ <li><p align="left"><strong>(:unkeyword flag)</strong> - true if the message does not have |
|
| 640 |
+ the specified flag set.</p> |
|
| 641 |
+ </li> |
|
| 642 |
+ <li><p align="left"><strong>:unseen </strong>- true if the message does not have the <strong>:\\seen |
|
| 643 |
+ </strong>flag set.</p> |
|
| 644 |
+ </li> |
|
| 645 |
+</ul> |
|
| 646 |
+ |
|
| 647 |
+<p align="left"> </p> |
|
| 648 |
+ |
|
| 649 |
+<h1 align="left">Examples</h1> |
|
| 650 |
+ |
|
| 651 |
+<p align="left">We show an example of using this interface</p> |
|
| 652 |
+ |
|
| 653 |
+<p align="left"> </p> |
|
| 654 |
+ |
|
| 655 |
+<p align="left"><strong>Connect to the imap server on the machine holding the email:</strong></p> |
|
| 656 |
+<div align="left"> |
|
| 657 |
+ |
|
| 658 |
+<pre>user(2): (setq mb (make-imap-connection "mailmachine.franz.com" |
|
| 659 |
+ |
|
| 660 |
+ :user "myacct" |
|
| 661 |
+ |
|
| 662 |
+ :password "mypasswd")) |
|
| 663 |
+ |
|
| 664 |
+#<mailbox::imap-mailbox @ #x2064ca4a></pre> |
|
| 665 |
+</div> |
|
| 666 |
+ |
|
| 667 |
+<p align="left"> </p> |
|
| 668 |
+ |
|
| 669 |
+<p align="left"><strong>Select the inbox, that's where the incoming mail arrives:</strong></p> |
|
| 670 |
+<div align="left"> |
|
| 671 |
+ |
|
| 672 |
+<pre> |
|
| 673 |
+ |
|
| 674 |
+user(3): (select-mailbox mb "inbox") |
|
| 675 |
+ |
|
| 676 |
+t</pre> |
|
| 677 |
+</div> |
|
| 678 |
+ |
|
| 679 |
+<p align="left"> </p> |
|
| 680 |
+ |
|
| 681 |
+<p align="left"><strong>Check how many messages are in the mailbox:</strong></p> |
|
| 682 |
+<div align="left"> |
|
| 683 |
+ |
|
| 684 |
+<pre> |
|
| 685 |
+ |
|
| 686 |
+user(4): (mailbox-message-count mb) |
|
| 687 |
+ |
|
| 688 |
+7</pre> |
|
| 689 |
+</div> |
|
| 690 |
+ |
|
| 691 |
+<p align="left"><strong>There are seven messages at the moment. Fetch the |
|
| 692 |
+whole 4th message. We could call (fetch-letter mb 4) here instead and then not |
|
| 693 |
+have to call fetch-field later.</strong></p> |
|
| 694 |
+<div align="left"> |
|
| 695 |
+ |
|
| 696 |
+<pre> |
|
| 697 |
+ |
|
| 698 |
+user(5): (setq body (fetch-parts mb 4 "body[]")) |
|
| 699 |
+ |
|
| 700 |
+((4 |
|
| 701 |
+ |
|
| 702 |
+("BODY[]" "Return-Path: <jkfmail@tiger.franz.com> |
|
| 703 |
+ |
|
| 704 |
+Received: from tiger.franz.com (jkf@tiger [192.132.95.103]) |
|
| 705 |
+ |
|
| 706 |
+ by tiger.franz.com (8.8.7/8.8.7) with SMTP id LAA20261 |
|
| 707 |
+ |
|
| 708 |
+ for <jkfmail@tiger.franz.com>; Mon, 13 Sep 1999 11:36:26 -0700 |
|
| 709 |
+ |
|
| 710 |
+Date: Mon, 13 Sep 1999 11:36:26 -0700 |
|
| 711 |
+ |
|
| 712 |
+From: jkf mail tester <jkfmail@tiger.franz.com> |
|
| 713 |
+ |
|
| 714 |
+Message-Id: <199909131836.LAA20261@tiger.franz.com> |
|
| 715 |
+ |
|
| 716 |
+ |
|
| 717 |
+ |
|
| 718 |
+message number 5 |
|
| 719 |
+ |
|
| 720 |
+")))</pre> |
|
| 721 |
+</div> |
|
| 722 |
+ |
|
| 723 |
+<p align="left"><strong>The value was returned inside a data structure designed to hold |
|
| 724 |
+information about one or more messages. In order to extract the particular |
|
| 725 |
+information we want we use fetch-field:</strong></p> |
|
| 726 |
+<div align="left"> |
|
| 727 |
+ |
|
| 728 |
+<pre> |
|
| 729 |
+ |
|
| 730 |
+user(6): (fetch-field 4 "body[]" body) |
|
| 731 |
+ |
|
| 732 |
+"Return-Path: <jkfmail@tiger.franz.com> |
|
| 733 |
+ |
|
| 734 |
+Received: from tiger.franz.com (jkf@tiger [192.132.95.103]) |
|
| 735 |
+ |
|
| 736 |
+ by tiger.franz.com (8.8.7/8.8.7) with SMTP id LAA20261 |
|
| 737 |
+ |
|
| 738 |
+ for <jkfmail@tiger.franz.com>; Mon, 13 Sep 1999 11:36:26 -0700 |
|
| 739 |
+ |
|
| 740 |
+Date: Mon, 13 Sep 1999 11:36:26 -0700 |
|
| 741 |
+ |
|
| 742 |
+From: jkf mail tester <jkfmail@tiger.franz.com> |
|
| 743 |
+ |
|
| 744 |
+Message-Id: <199909131836.LAA20261@tiger.franz.com> |
|
| 745 |
+ |
|
| 746 |
+ |
|
| 747 |
+ |
|
| 748 |
+message number 5 |
|
| 749 |
+ |
|
| 750 |
+"</pre> |
|
| 751 |
+</div> |
|
| 752 |
+ |
|
| 753 |
+<p align="left"><strong>We use the search function to find all the messages containing the |
|
| 754 |
+word blitzfig. It turns out there is only one. We then extract the contents of |
|
| 755 |
+that message.</strong></p> |
|
| 756 |
+<div align="left"> |
|
| 757 |
+ |
|
| 758 |
+<pre> |
|
| 759 |
+ |
|
| 760 |
+user(7): (search-mailbox mb '(:text "blitzfig")) |
|
| 761 |
+ |
|
| 762 |
+(7) |
|
| 763 |
+ |
|
| 764 |
+user(8): (fetch-field 7 "body[]" (fetch-letter mb 7 "body[]")) |
|
| 765 |
+ |
|
| 766 |
+"Return-Path: <jkf@verada.com> |
|
| 767 |
+ |
|
| 768 |
+Received: from main.verada.com (main.verada.com [208.164.216.3]) |
|
| 769 |
+ |
|
| 770 |
+ by tiger.franz.com (8.8.7/8.8.7) with ESMTP id NAA20541 |
|
| 771 |
+ |
|
| 772 |
+ for <jkfmail@tiger.franz.com>; Mon, 13 Sep 1999 13:37:24 -0700 |
|
| 773 |
+ |
|
| 774 |
+Received: from main.verada.com (IDENT:jkf@localhost [127.0.0.1]) |
|
| 775 |
+ |
|
| 776 |
+ by main.verada.com (8.9.3/8.9.3) with ESMTP id NAA06121 |
|
| 777 |
+ |
|
| 778 |
+ for <jkfmail@tiger.franz.com>; Mon, 13 Sep 1999 13:36:54 -0700 |
|
| 779 |
+ |
|
| 780 |
+Message-Id: <199909132036.NAA06121@main.verada.com> |
|
| 781 |
+ |
|
| 782 |
+To: jkfmail@tiger.franz.com |
|
| 783 |
+ |
|
| 784 |
+Subject: s test |
|
| 785 |
+ |
|
| 786 |
+Date: Mon, 13 Sep 1999 13:36:54 -0700 |
|
| 787 |
+ |
|
| 788 |
+From: jkf <jkf@verada.com> |
|
| 789 |
+ |
|
| 790 |
+ |
|
| 791 |
+ |
|
| 792 |
+secret word: blitzfig |
|
| 793 |
+ |
|
| 794 |
+ok? |
|
| 795 |
+ |
|
| 796 |
+"</pre> |
|
| 797 |
+</div> |
|
| 798 |
+ |
|
| 799 |
+<p align="left"><strong>We've been using message sequence numbers up to now. |
|
| 800 |
+The are the simplest to use but if you're concerned with keeping track of messages when |
|
| 801 |
+deletions are being done then using unique id's is useful. Here we do the |
|
| 802 |
+above search example using uids:</strong></p> |
|
| 803 |
+<div align="left"> |
|
| 804 |
+ |
|
| 805 |
+<pre> |
|
| 806 |
+ |
|
| 807 |
+user(9): (search-mailbox mb '(:text "blitzfig") :uid t) |
|
| 808 |
+ |
|
| 809 |
+(68) |
|
| 810 |
+ |
|
| 811 |
+user(10): (fetch-field 68 "body[]" (fetch-letter mb 68 "body[]" :uid t) :uid t) |
|
| 812 |
+ |
|
| 813 |
+"Return-Path: <jkf@verada.com> |
|
| 814 |
+ |
|
| 815 |
+Received: from main.verada.com (main.verada.com [208.164.216.3]) |
|
| 816 |
+ |
|
| 817 |
+ by tiger.franz.com (8.8.7/8.8.7) with ESMTP id NAA20541 |
|
| 818 |
+ |
|
| 819 |
+ for <jkfmail@tiger.franz.com>; Mon, 13 Sep 1999 13:37:24 -0700 |
|
| 820 |
+ |
|
| 821 |
+Received: from main.verada.com (IDENT:jkf@localhost [127.0.0.1]) |
|
| 822 |
+ |
|
| 823 |
+ by main.verada.com (8.9.3/8.9.3) with ESMTP id NAA06121 |
|
| 824 |
+ |
|
| 825 |
+ for <jkfmail@tiger.franz.com>; Mon, 13 Sep 1999 13:36:54 -0700 |
|
| 826 |
+ |
|
| 827 |
+Message-Id: <199909132036.NAA06121@main.verada.com> |
|
| 828 |
+ |
|
| 829 |
+To: jkfmail@tiger.franz.com |
|
| 830 |
+ |
|
| 831 |
+Subject: s test |
|
| 832 |
+ |
|
| 833 |
+Date: Mon, 13 Sep 1999 13:36:54 -0700 |
|
| 834 |
+ |
|
| 835 |
+From: jkf <jkf@verada.com> |
|
| 836 |
+ |
|
| 837 |
+ |
|
| 838 |
+ |
|
| 839 |
+secret word: blitzfig |
|
| 840 |
+ |
|
| 841 |
+ok? |
|
| 842 |
+ |
|
| 843 |
+"</pre> |
|
| 844 |
+</div> |
|
| 845 |
+ |
|
| 846 |
+<p align="left"><strong>We'll delete that letter with the secret word and then note that |
|
| 847 |
+we have only six messages in the mailbox.</strong></p> |
|
| 848 |
+<div align="left"> |
|
| 849 |
+ |
|
| 850 |
+<pre> |
|
| 851 |
+ |
|
| 852 |
+user(11): (delete-letter mb 68 :uid t) |
|
| 853 |
+ |
|
| 854 |
+(7) |
|
| 855 |
+ |
|
| 856 |
+user(12): (mailbox-message-count mb) |
|
| 857 |
+ |
|
| 858 |
+6</pre> |
|
| 859 |
+</div> |
|
| 860 |
+ |
|
| 861 |
+<p align="left"><strong>Now we assume that a bit of time has passed and we want to see if |
|
| 862 |
+any new messages have been delivered into the mailbox. In order to find out we |
|
| 863 |
+have to send a command to the imap server since it will only notify us of new messages |
|
| 864 |
+when it responds to a command. Since we have nothing to ask the imap server to |
|
| 865 |
+do we issue the noop command, which does nothing on the server.</strong></p> |
|
| 866 |
+<div align="left"> |
|
| 867 |
+ |
|
| 868 |
+<pre> |
|
| 869 |
+ |
|
| 870 |
+user(13): (noop mb) |
|
| 871 |
+ |
|
| 872 |
+nil |
|
| 873 |
+ |
|
| 874 |
+user(14): (mailbox-message-count mb) |
|
| 875 |
+ |
|
| 876 |
+7</pre> |
|
| 877 |
+</div> |
|
| 878 |
+ |
|
| 879 |
+<p align="left"><strong>The server told us that there are now 7 messages in the inbox, one |
|
| 880 |
+more than before. Next we create a new mailbox, copy the messages from the inbox to |
|
| 881 |
+the new mailbox and then delete them from the inbox. Note how we use the :seq form |
|
| 882 |
+to specify a sequence of messages.</strong></p> |
|
| 883 |
+<div align="left"> |
|
| 884 |
+ |
|
| 885 |
+<pre> |
|
| 886 |
+ |
|
| 887 |
+user(15): (create-mailbox mb "tempbox") |
|
| 888 |
+ |
|
| 889 |
+t |
|
| 890 |
+ |
|
| 891 |
+user(18): (let ((count (mailbox-message-count mb))) |
|
| 892 |
+ |
|
| 893 |
+(copy-to-mailbox mb `(:seq 1 ,count) "tempbox") |
|
| 894 |
+ |
|
| 895 |
+(delete-letter mb `(:seq 1 ,count))) |
|
| 896 |
+ |
|
| 897 |
+(1 1 1 1 1 1 1) |
|
| 898 |
+ |
|
| 899 |
+user(19): (mailbox-message-count mb) |
|
| 900 |
+ |
|
| 901 |
+0</pre> |
|
| 902 |
+</div> |
|
| 903 |
+ |
|
| 904 |
+<p align="left"><strong>When we're done there are 0 messages in the currently selected |
|
| 905 |
+mailbox, which is inbox. We now select the maibox we just created and see that the |
|
| 906 |
+messages are there.</strong></p> |
|
| 907 |
+<div align="left"> |
|
| 908 |
+ |
|
| 909 |
+<pre> |
|
| 910 |
+ |
|
| 911 |
+user(22): (select-mailbox mb "tempbox") |
|
| 912 |
+ |
|
| 913 |
+t |
|
| 914 |
+ |
|
| 915 |
+user(23): (mailbox-message-count mb) |
|
| 916 |
+ |
|
| 917 |
+7</pre> |
|
| 918 |
+</div> |
|
| 919 |
+ |
|
| 920 |
+<p align="left"><strong>Finally we shut down the connection. Note that imap |
|
| 921 |
+servers will automatically shut down a connection that's been idle for too long (usually |
|
| 922 |
+around 10 minutes). When that happens, the next time the client tries to use an imap |
|
| 923 |
+function to access the mailbox an error will occur. There is nothing that can |
|
| 924 |
+be done to revive the connection however it is important to call close-imap-connection on |
|
| 925 |
+the lisp side in order to free up the resources still in use for the now dead connection.</strong></p> |
|
| 926 |
+<div align="left"> |
|
| 927 |
+ |
|
| 928 |
+<pre> |
|
| 929 |
+ |
|
| 930 |
+user(24): (close-connection mb) |
|
| 931 |
+ |
|
| 932 |
+t |
|
| 933 |
+ |
|
| 934 |
+</pre> |
|
| 935 |
+</div> |
|
| 936 |
+ |
|
| 937 |
+<p align="left"> </p> |
|
| 938 |
+ |
|
| 939 |
+<h1><a name="pop"></a>The Pop interface</h1> |
|
| 940 |
+ |
|
| 941 |
+<p>The <strong>pop</strong> protocol is a very simple means for retrieving messages from a |
|
| 942 |
+single mailbox. The functions in the interface are:</p> |
|
| 943 |
+ |
|
| 944 |
+<p> </p> |
|
| 945 |
+ |
|
| 946 |
+<p align="left"><font face="Courier New">(<strong>make-pop-connection host &key user |
|
| 947 |
+password port timeout)</strong></font></p> |
|
| 948 |
+ |
|
| 949 |
+<p align="left">This creates a connection to the <strong>pop</strong> server on machine <strong>host</strong> |
|
| 950 |
+and logs in as <strong>user </strong>with password <strong>password. </strong>The |
|
| 951 |
+<strong>port</strong> argument defaults to 110, which is the port on which the <strong>pop</strong> |
|
| 952 |
+server normally listens. The <strong>timeout</strong> argument defaults |
|
| 953 |
+to 30 (seconds) and this value is used to limit the amount of time this pop interface code |
|
| 954 |
+will wait for a response from the server before giving up. In certain |
|
| 955 |
+circumstances the server may get so busy that you see timeout errors signaled in this |
|
| 956 |
+code. In that case you should specify a larger timeout when connecting. </p> |
|
| 957 |
+ |
|
| 958 |
+<p>The value returned by this function is a <strong>mailbox</strong> object. You can |
|
| 959 |
+call <strong>mailbox-message-count</strong> on the <strong>mailbox</strong> object to |
|
| 960 |
+determine how many letters are currently stored in the mailbox.</p> |
|
| 961 |
+ |
|
| 962 |
+<p> </p> |
|
| 963 |
+ |
|
| 964 |
+<p><font face="Courier New"><strong>(close-connection mb)</strong></font></p> |
|
| 965 |
+ |
|
| 966 |
+<p>Disconnect from the pop server. All messages marked for deletion will be deleted.</p> |
|
| 967 |
+ |
|
| 968 |
+<p> </p> |
|
| 969 |
+ |
|
| 970 |
+<p><strong><font face="Courier New">(delete-letter mb messages)</font></strong></p> |
|
| 971 |
+ |
|
| 972 |
+<p>Mark the specified <strong>messages</strong> for deletion. <strong>mb </strong>is |
|
| 973 |
+the mailbox object returned by <strong>make-pop-connection</strong>. The messages |
|
| 974 |
+are only marked for deletion. They are not removed until a <strong>close-connection</strong> |
|
| 975 |
+is done. If the connection to the <strong>pop</strong> server is broken before a <strong>close-connection</strong> |
|
| 976 |
+is done, the messages will <strong>not</strong> be deleted and they will no longer be |
|
| 977 |
+marked for deletion either.</p> |
|
| 978 |
+ |
|
| 979 |
+<p><strong>messages</strong> can either be a message number, a list of the form <strong>(:seq |
|
| 980 |
+N M)</strong> meaning messages <strong>N </strong>through <strong>M </strong>or it can be |
|
| 981 |
+a list of message numbers and/or <strong>:seq </strong>specifiers. The |
|
| 982 |
+messages in a mailbox are numbered starting with one. Marking a message for deletion |
|
| 983 |
+does not affect the numbering of other messages in the mailbox.</p> |
|
| 984 |
+ |
|
| 985 |
+<p> </p> |
|
| 986 |
+ |
|
| 987 |
+<p><font face="Courier New"><strong>(fetch-letter mb message)</strong></font></p> |
|
| 988 |
+ |
|
| 989 |
+<p>Fetch from the pop server connection <strong>mb</strong> the letter numbered <strong>message</strong>. |
|
| 990 |
+ The letters in a mailbox are numbered starting with one. The entire |
|
| 991 |
+message, including the headers, is returned as a string. It is an |
|
| 992 |
+error to attempt to fetch a letter marked for deletion.</p> |
|
| 993 |
+ |
|
| 994 |
+<p> </p> |
|
| 995 |
+ |
|
| 996 |
+<p><font face="Courier New"><strong>(make-envelope-from-text text)</strong></font></p> |
|
| 997 |
+ |
|
| 998 |
+<p><strong>text</strong> is a string that is the first part of a mail message, including |
|
| 999 |
+at least all of the headers lines and the blank line following the headers. This |
|
| 1000 |
+function parses the header lines and return an <strong>envelope</strong> structure |
|
| 1001 |
+containing information from the header. </p> |
|
| 1002 |
+ |
|
| 1003 |
+<p> </p> |
|
| 1004 |
+ |
|
| 1005 |
+<p><font face="Courier New"><strong>(noop mb)</strong></font></p> |
|
| 1006 |
+ |
|
| 1007 |
+<p>This is the no-operation command. It is useful for letting the <strong>pop</strong> |
|
| 1008 |
+server know that this connection should be kept alive (<strong>pop </strong>servers tend |
|
| 1009 |
+to disconnect after a few minutes of inactivity). In order to make <strong>noop</strong> |
|
| 1010 |
+have behavior similar to that of the <strong>imap</strong> version of <strong>noop</strong>, |
|
| 1011 |
+we don't send a 'noop' command to the pop server, instead we send a 'stat' command. |
|
| 1012 |
+ This means that after this command is completed the <strong>mailbox-message-count</strong> |
|
| 1013 |
+will contain the current count of messages in the mailbox.</p> |
|
| 1014 |
+ |
|
| 1015 |
+<p> </p> |
|
| 1016 |
+ |
|
| 1017 |
+<p><font face="Courier New"><strong>(top-lines mb message line-count)</strong></font></p> |
|
| 1018 |
+ |
|
| 1019 |
+<p>Return a string that contains all the header lines and the first <strong>line-count</strong> |
|
| 1020 |
+lines of the body of <strong>message</strong>. To just retrieve the headers a <strong>line-count</strong> |
|
| 1021 |
+of zero can be given. See the function <strong>make-envelope-from-text</strong> for |
|
| 1022 |
+a means of reading the information in the header.</p> |
|
| 1023 |
+ |
|
| 1024 |
+<p> </p> |
|
| 1025 |
+ |
|
| 1026 |
+<p><font face="Courier New"><strong>(unique-id mb &optional message)</strong></font></p> |
|
| 1027 |
+ |
|
| 1028 |
+<p>Return the unique indentifier for the given message, or for all non-deleted messages if |
|
| 1029 |
+<strong>message</strong> is nil. The unique identifier is is a string that is |
|
| 1030 |
+different for every message. If the <strong>message</strong> argument is |
|
| 1031 |
+not given then this command returns a list of lists where each list contains two items: |
|
| 1032 |
+the message number and the unique id.</p> |
|
| 1033 |
+ |
|
| 1034 |
+<h1>Cond<a name="conditions"></a>itions</h1> |
|
| 1035 |
+ |
|
| 1036 |
+<p>When an unexpected event occurs a condition is signaled. This applies to |
|
| 1037 |
+both the <strong>imap</strong> and <strong>pop</strong> interfaces. There are two |
|
| 1038 |
+classes of conditions signaled by this package: |
|
| 1039 |
+ |
|
| 1040 |
+<ul> |
|
| 1041 |
+ <li><strong>po-condition</strong> - this class denotes conditions that need not and in fact |
|
| 1042 |
+ should not interrupt program flow. When the mailbox server is responding to a |
|
| 1043 |
+ command it sometimes sends informational warning messages and we turn them into |
|
| 1044 |
+ conditions. It's important for all messages from the server to be read |
|
| 1045 |
+ and processed otherwise the next command issued will see messages in response to the |
|
| 1046 |
+ previous command. Therefore the user code should never do a non-local-transfer |
|
| 1047 |
+ in response to a <strong>po-condition.</strong></li> |
|
| 1048 |
+ <li><strong>po-error - </strong>this class denotes conditions that will prevent execution |
|
| 1049 |
+ from continuing. If one of these errors is not caught, the interactive debugger will |
|
| 1050 |
+ be entered.</li> |
|
| 1051 |
+</ul> |
|
| 1052 |
+ |
|
| 1053 |
+<p>Instances of both of these condition classes have these slots in addition to the |
|
| 1054 |
+standard condition slots: </p> |
|
| 1055 |
+ |
|
| 1056 |
+<table border="1" width="100%"> |
|
| 1057 |
+ <tr> |
|
| 1058 |
+ <td width="16%">Name</td> |
|
| 1059 |
+ <td width="24%">Accessor</td> |
|
| 1060 |
+ <td width="60%">Value</td> |
|
| 1061 |
+ </tr> |
|
| 1062 |
+ <tr> |
|
| 1063 |
+ <td width="16%">identifier</td> |
|
| 1064 |
+ <td width="24%">po-condition-identifier</td> |
|
| 1065 |
+ <td width="60%">keyword describing the kind of condition being signaled. See the |
|
| 1066 |
+ table below for the possible values.</td> |
|
| 1067 |
+ </tr> |
|
| 1068 |
+ <tr> |
|
| 1069 |
+ <td width="16%">server-string</td> |
|
| 1070 |
+ <td width="24%">po-condition-server-string</td> |
|
| 1071 |
+ <td width="60%">If the condition was created because of a messages sent from the mailbox |
|
| 1072 |
+ server then this is that message.</td> |
|
| 1073 |
+ </tr> |
|
| 1074 |
+</table> |
|
| 1075 |
+ |
|
| 1076 |
+<p>The meaning of the identifier value is as follows</p> |
|
| 1077 |
+ |
|
| 1078 |
+<table border="1" width="100%"> |
|
| 1079 |
+ <tr> |
|
| 1080 |
+ <td width="11%"><strong>Identifier</strong></td> |
|
| 1081 |
+ <td width="13%">Kind</td> |
|
| 1082 |
+ <td width="76%">Meaning</td> |
|
| 1083 |
+ </tr> |
|
| 1084 |
+ <tr> |
|
| 1085 |
+ <td width="11%"><strong>:problem</strong></td> |
|
| 1086 |
+ <td width="13%">po-condition</td> |
|
| 1087 |
+ <td width="76%">The server has responded with a warning message. The most |
|
| 1088 |
+ likely warning is that the mailbox can only be opened in read-only mode due to another |
|
| 1089 |
+ processing using it.</td> |
|
| 1090 |
+ </tr> |
|
| 1091 |
+ <tr> |
|
| 1092 |
+ <td width="11%"><strong>:unknown-ok</strong></td> |
|
| 1093 |
+ <td width="13%">po-condition</td> |
|
| 1094 |
+ <td width="76%">The server has sent an informative message that we don't understand. |
|
| 1095 |
+ It's probably safe to ignore this.</td> |
|
| 1096 |
+ </tr> |
|
| 1097 |
+ <tr> |
|
| 1098 |
+ <td width="11%"><strong>:unknown-untagged</strong></td> |
|
| 1099 |
+ <td width="13%">po-condition</td> |
|
| 1100 |
+ <td width="76%">The server has sent an informative message that we don't understand. |
|
| 1101 |
+ It's probably safe to ignore this.</td> |
|
| 1102 |
+ </tr> |
|
| 1103 |
+ <tr> |
|
| 1104 |
+ <td width="11%"><strong>:error-response</strong></td> |
|
| 1105 |
+ <td width="13%">po-error</td> |
|
| 1106 |
+ <td width="76%">The server cannot execute the requested command.</td> |
|
| 1107 |
+ </tr> |
|
| 1108 |
+ <tr> |
|
| 1109 |
+ <td width="11%"><strong>:syntax-error</strong></td> |
|
| 1110 |
+ <td width="13%">po-error</td> |
|
| 1111 |
+ <td width="76%">The arguments to a function in this package are malformed.</td> |
|
| 1112 |
+ </tr> |
|
| 1113 |
+ <tr> |
|
| 1114 |
+ <td width="11%"><strong>:unexpected</strong></td> |
|
| 1115 |
+ <td width="13%">po-error</td> |
|
| 1116 |
+ <td width="76%">The server has responded a way we don't understand and which prevents us |
|
| 1117 |
+ from continuing</td> |
|
| 1118 |
+ </tr> |
|
| 1119 |
+ <tr> |
|
| 1120 |
+ <td width="11%"><strong>:server-shutdown-connection</strong></td> |
|
| 1121 |
+ <td width="13%">po-error</td> |
|
| 1122 |
+ <td width="76%">The connection to the server has been broken. This usually occurs |
|
| 1123 |
+ when the connection has been idle for too long and the server intentionally disconnects. |
|
| 1124 |
+ Just before this condition is signaled we close down the socket connection to |
|
| 1125 |
+ free up the socket resource on our side. When this condition is signaled the user |
|
| 1126 |
+ program should not use the mailbox object again (even to call <strong>close-connection</strong> |
|
| 1127 |
+ on it).</td> |
|
| 1128 |
+ </tr> |
|
| 1129 |
+ <tr> |
|
| 1130 |
+ <td width="11%"><strong>:timeout</strong></td> |
|
| 1131 |
+ <td width="13%">po-error</td> |
|
| 1132 |
+ <td width="76%">The server did not respond quickly enough. The timeout value |
|
| 1133 |
+ is set in the call to <strong>make-imap-connection.</strong></td> |
|
| 1134 |
+ </tr> |
|
| 1135 |
+</table> |
|
| 1136 |
+ |
|
| 1137 |
+<h1><a name="smtp"></a>The smtp interface</h1> |
|
| 1138 |
+ |
|
| 1139 |
+<p>With the smtp interface, a Lisp program can contact a mail server and send electronic |
|
| 1140 |
+mail. The contents of the message must be a simple text string. There is |
|
| 1141 |
+no provision for encoding binary data and sending it as a Mime attachment.</p> |
|
| 1142 |
+ |
|
| 1143 |
+<p> </p> |
|
| 1144 |
+ |
|
| 1145 |
+<p><font face="Courier New"><strong>(send-letter mail-server from to message &key |
|
| 1146 |
+subject reply-to)</strong></font></p> |
|
| 1147 |
+ |
|
| 1148 |
+<p><strong>mail-server</strong> can be a string naming a machine or an integer IP address. |
|
| 1149 |
+ The <strong>mail-server</strong> is contacted and asked to send a <strong>message</strong> |
|
| 1150 |
+(a string) <strong>from</strong> a given email address <strong>to</strong> a given email |
|
| 1151 |
+address or list of addresses. The email addresses must be of the form |
|
| 1152 |
+"foo" or <a href="mailto:foo@bar.com">"foo@bar.com"</a>. You can |
|
| 1153 |
+<strong>not</strong> use addresses like <a href="mailto:Joe%20%3cfoo@bar.com%3e">"Joe |
|
| 1154 |
+<foo@bar.com>"</a> or <a href="mailto:(Joe)%20foo@bar.com">"(Joe) |
|
| 1155 |
+foo@bar.com"</a>. </p> |
|
| 1156 |
+ |
|
| 1157 |
+<p>A mail header is built and prepended to the <strong>message</strong> before it is sent. |
|
| 1158 |
+ The mail header includes a <strong>From </strong>and <strong>To</strong> line and |
|
| 1159 |
+will optionally include a <strong>Subject</strong> and <strong>Reply-To</strong> |
|
| 1160 |
+line if those are given in the call to <strong>send-letter.</strong>.</p> |
|
| 1161 |
+ |
|
| 1162 |
+<p>The text of the <strong>message</strong> should be lines separated by #\newline's. |
|
| 1163 |
+ The <strong>smtp</strong> interface will automatically insert the necessary |
|
| 1164 |
+#\returns's when it transmits the message to the mail server.</p> |
|
| 1165 |
+ |
|
| 1166 |
+<p> </p> |
|
| 1167 |
+ |
|
| 1168 |
+<p> </p> |
|
| 1169 |
+ |
|
| 1170 |
+<p><font face="Courier New"><strong>(send-smtp mail-server from to &rest messages)</strong></font></p> |
|
| 1171 |
+ |
|
| 1172 |
+<p><strong>mail-server</strong> can be a string naming a machine or an integer IP address. |
|
| 1173 |
+ The <strong>mail-server</strong> is contacted and asked to send a message <strong>from</strong> |
|
| 1174 |
+a given email address <strong>to</strong> a given email address or list of addresses. |
|
| 1175 |
+ The email addresses must be of the form "foo" or <a |
|
| 1176 |
+href="mailto:foo@bar.com">"foo@bar.com"</a>. You can <strong>not</strong> |
|
| 1177 |
+use addresses like <a href="mailto:Joe%20%3cfoo@bar.com%3e">"Joe |
|
| 1178 |
+<foo@bar.com>"</a> or <a href="mailto:(Joe)%20foo@bar.com">"(Joe) |
|
| 1179 |
+foo@bar.com"</a>. </p> |
|
| 1180 |
+ |
|
| 1181 |
+<p>The message sent is a concatenation of all of the <strong>messages</strong> (which |
|
| 1182 |
+should be strings). A header is <strong>not</strong> prepended to the message. |
|
| 1183 |
+ This means that the application program can build its own header if it wants to |
|
| 1184 |
+include in that header more than <strong>send-letter</strong> supports (e.g. a Mime |
|
| 1185 |
+encoded attachment). If no header is provided then some mail servers (e.g. <strong>sendmail</strong>) |
|
| 1186 |
+will notice this fact and will automatically create a header.</p> |
|
| 1187 |
+ |
|
| 1188 |
+<p>The text of the <strong>messages</strong> should be lines separated by #\newline's. |
|
| 1189 |
+ The <strong>smtp</strong> interface will automatically insert the necessary |
|
| 1190 |
+#\returns's when it transmits the message to the mail server.</p> |
|
| 1191 |
+ |
|
| 1192 |
+<p> </p> |
|
| 1193 |
+ |
|
| 1194 |
+<p> </p> |
|
| 1195 |
+ |
|
| 1196 |
+<p> </p> |
|
| 1197 |
+ |
|
| 1198 |
+<p> </p> |
|
| 1199 |
+</body> |
|
| 1200 |
+</html> |