postoffice.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">&nbsp;</p>
  15
  16 <p align="left"><strong>imap</strong> is a client-server protocol for processing
  17 electronic mail boxes.&nbsp; <strong>imap </strong>is the successor to the <strong>pop</strong>
  18 protocol.&nbsp;&nbsp; It is <strong>not</strong> an upward compatible successor.
  19 &nbsp;&nbsp;&nbsp;&nbsp; The main focus of this document is the <strong>imap</strong>
  20 protocol.&nbsp;&nbsp;&nbsp; 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.&nbsp;&nbsp; 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. &nbsp;&nbsp;
  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">&nbsp;</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.&nbsp;&nbsp; The previous version of this module gave this package the <strong>po</strong>
  71 nickname.&nbsp; We've removed that nickname to reduce the possibility of clashing with
  72 user-defined packages.&nbsp; You are free to add that nickname back if you so desire.</p>
  73
  74 <p align="left">&nbsp;</p>
  75
  76 <h1 align="left">Mailboxes</h1>
  77
  78 <p align="left">Mailboxes are repositories for messages.&nbsp;&nbsp; Mailboxes are named
  79 by Lisp strings.&nbsp; The mailbox &quot;inbox&quot; always exists and it is the mailbox
  80 in which new messages are stored.&nbsp;&nbsp; New mailboxes can be created.
  81 &nbsp;&nbsp;&nbsp; They can have simple names, like &quot;foo&quot; or they can have
  82 hierarchical names (like &quot;clients/california/widgetco&quot;).&nbsp;&nbsp; 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 &quot;/&quot; was the
  85 separator character). </p>
  86
  87 <p align="left">Each mailbox has an associated unique number called its <strong>uidvalidity</strong>.
  88 &nbsp;&nbsp;&nbsp; This number won't change as long as <strong>imap</strong> is the only
  89 program used to manipulate the mailbox.&nbsp;&nbsp; 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.&nbsp;&nbsp;&nbsp; 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:&nbsp; message
  98 sequence number or&nbsp; unique id.&nbsp;&nbsp; </p>
  99
 100 <p align="left">The <em>message sequence number</em> is the normal way.&nbsp; The messages
 101 in a mailbox are numbered from 1 to N where N is the number of messages in the mailbox.
 102 &nbsp;&nbsp; There are never any gaps in the sequence numbers.&nbsp; 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.&nbsp; 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.&nbsp;&nbsp; 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.&nbsp; </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.&nbsp;&nbsp; We use keywords in Lisp to denote flags.&nbsp;&nbsp; There are two
 117 kinds of flags - System and User flags.&nbsp; System flags begin with the backslash
 118 character, which is an unfortunate design decision&nbsp; since that means that in Lisp we
 119 have to remember to use two backslashes (e.g.&nbsp; <strong>:\\deleted</strong>).
 120 &nbsp;&nbsp; A subset of the flags can be stored permanently in the mailbox with the
 121 messages.&nbsp; 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).&nbsp;&nbsp; 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     &nbsp; (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">&nbsp;</p>
 143
 144 <h1 align="left">Connecting to the server</h1>
 145
 146 <p align="left">&nbsp;</p>
 147
 148 <p align="left"><font face="Courier New">(<strong>make-imap-connection host &amp;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.&nbsp;&nbsp; </strong>The
 153 <strong>port</strong> argument defaults to143, which is the port on which the <strong>imap</strong>
 154 server normally listens.&nbsp;&nbsp;&nbsp; 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.&nbsp;&nbsp;&nbsp; In
 157 certain circumstances the server may get so busy that you see timeout errors signaled in
 158 this code.&nbsp; 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.&nbsp;&nbsp; From this
 162 one connection you can access all of the mailboxes owned by <strong>user</strong>.</p>
 163
 164 <p align="left">After&nbsp; the connection is&nbsp; established a mailbox is <strong>not</strong>
 165 selected.&nbsp;&nbsp; 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.&nbsp;&nbsp; Therefore be sure to
 168 select a mailbox using <strong>select-mailbox</strong> shortly after connecting.</p>
 169
 170 <p align="left">&nbsp;</p>
 171
 172 <p align="left">&nbsp;</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.&nbsp;&nbsp;&nbsp; <strong>mailbox </strong>is the object returned by <strong>make-imap-connection.</strong>
 179 &nbsp;&nbsp; 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&nbsp; mailbox.&nbsp; 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">&nbsp;</p>
 186
 187 <p align="left">&nbsp;</p>
 188
 189 <h1 align="left">Mailbox manipulation</h1>
 190
 191 <p align="left">These functions work on mailboxes as a whole.&nbsp;&nbsp;&nbsp; The <strong>mailbox</strong>
 192 argument to the functions is is the object returned by <strong>make-imap-connection.
 193 &nbsp; </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">&nbsp;</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.&nbsp;&nbsp;&nbsp;&nbsp; The
 203 selected mailbox is the source for all message manipulation functions.</p>
 204
 205 <p align="left">&nbsp;</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>.&nbsp;&nbsp; It
 210 is an error if the mailbox already exists.&nbsp; 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>.&nbsp;&nbsp; You do <strong>not</strong>
 213 &nbsp; 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">&nbsp;</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">&nbsp;</p>
 223
 224 <p align="left"><font face="Courier New"><strong>(rename-mailbox mailbox&nbsp; 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 &nbsp; It's an error if <strong>new-name</strong> already exists.&nbsp; There's a special
 229 behavior if <strong>old-name</strong> is &quot;inbox&quot;.&nbsp; In this case all of the
 230 messages in &quot;inbox&quot; are moved to <strong>new-name </strong>mailbox, but the
 231 &quot;inbox&quot; mailbox continues to exist.&nbsp;&nbsp; Note: The <strong>imap </strong>server
 232 supplied with Linux does <strong>not</strong> support this special behavior of renaming
 233 &quot;inbox&quot;.</p>
 234
 235 <p align="left">&nbsp;</p>
 236
 237 <p align="left"><strong><font face="Courier New">(mailbox-list mailbox &amp;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 &nbsp;&nbsp;&nbsp;&nbsp; The <strong>reference</strong> is the root of the hierarchy to
 242 scan.&nbsp; By default is is the empty string (from which all mailboxes are reachable).
 243 &nbsp;&nbsp;&nbsp; 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:&nbsp; </strong>Asterisk (*) matches all characters including
 246 hierarchy delimiters.&nbsp;&nbsp; Percent (%) matches all characters but not the hierarchy
 247 delimiter.&nbsp; Thus</p>
 248
 249 <p align="center"><font face="Courier New">(mailbox-list mailbox :pattern &quot;*&quot;)</font></p>
 250
 251 <p align="left">returns a list of all mailboxes at all depths in the hierarchy.
 252 &nbsp;&nbsp; </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 &nbsp;
 256 easier.&nbsp;&nbsp; The accessors for that structure are:</p>
 257
 258 <p align="left">&nbsp;</p>
 259
 260 <p align="left"><font face="Courier New"><strong>(mailbox-list-flags mailbox-list)&nbsp; </strong></font></p>
 261
 262 <p align="left">returns the flags describing this entry.&nbsp;&nbsp; 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.&nbsp;&nbsp; The flag <strong>:\\noinferiors</strong>
 265 specifies that you can't create a hierarchical mailbox name with this as a prefix.
 266 &nbsp;&nbsp; This flag is often associated with the special mailbox &quot;inbox&quot;.</p>
 267
 268 <p align="left">&nbsp;</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">&nbsp;</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">&nbsp;</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 &nbsp;&nbsp;&nbsp; The <strong>mailbox</strong> argument is the object returned by <strong>make-imap-connection.</strong>
 288 &nbsp; 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">&nbsp;</p>
 294
 295 <p align="left">(<font face="Courier New"><strong>alter-flags mailbox messages &amp;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.&nbsp; Exactly one of&nbsp; <strong>flags,
 299 add-flags</strong>, and <strong>remove-flags</strong> must&nbsp; be specified.&nbsp; <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.&nbsp;&nbsp; If <strong>uid</strong> is true then <strong>messages</strong>
 302 will be interpreted as unique ids rather than message sequence numbers.
 303 &nbsp;&nbsp;&nbsp;&nbsp; Normally <strong>alter-flags</strong> returns a data structure
 304 that describes the state of the flags after the alternation has been done.&nbsp; This data
 305 structure can be examined&nbsp; with the <strong>fetch-field</strong> function.
 306 &nbsp;&nbsp; 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>&nbsp;</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.&nbsp; After
 318 this command has finished there is no currently selected mailbox.</p>
 319
 320 <p align="left">&nbsp;</p>
 321
 322 <p align="left"><strong><font face="Courier New">(copy-to-mailbox mailbox messages
 323 destination &amp;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). &nbsp; The
 327 flags are copied as well. The destination mailbox must already exist.&nbsp; The messages
 328 are <strong>not</strong> removed from the selected mailbox after the copy &nbsp; .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">&nbsp;</p>
 333
 334 <p align="left"><font face="Courier New"><strong>(delete-letter mailbox messages &amp;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 &nbsp;&nbsp; <strong>expunge </strong>defaults to true.&nbsp;&nbsp;&nbsp; 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">&nbsp;</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.&nbsp;&nbsp; The currently selected mailbox stays
 348 selected.</p>
 349
 350 <p align="left">&nbsp;</p>
 351
 352 <p align="left"><font face="Courier New"><strong>(fetch-field message part info &amp;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 &nbsp;&nbsp;&nbsp; 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&nbsp; particular piece of information about a particular
 359 letter.&nbsp;&nbsp; <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).&nbsp;&nbsp; <strong>part </strong>is the type of information desired.&nbsp; It is a
 362 string just as used in the call to <strong>fetch-letter</strong>.</p>
 363
 364 <p align="left">&nbsp;</p>
 365
 366 <p align="left"><strong><font face="Courier New">(fetch-letter mailbox message &amp;key
 367 uid)</font></strong></p>
 368
 369 <p align="left">Return the complete message, headers and body, as one big string. &nbsp;
 370 This is a combination of <strong>fetch-field</strong> and <strong>fetch-parts</strong>
 371 where the part specification is &quot;body[]&quot;.</p>
 372
 373 <p align="left">&nbsp;</p>
 374
 375 <p align="left"><font face="Courier New"><strong>(fetch-parts mailbox messages parts
 376 &amp;key uid)</strong></font></p>
 377
 378 <p align="left">retrieves the specified <strong>parts</strong> of the specified <strong>messages.
 379 &nbsp;&nbsp; </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 &nbsp;&nbsp;&nbsp;&nbsp; The description of what can be specified for <strong>parts </strong>is
 382 quite complex and is described in the section below &quot;Fetching a Letter&quot;.</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&nbsp; 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">&nbsp;</p>
 414
 415 <p align="left">&nbsp;</p>
 416
 417 <p align="left"><strong><font face="Courier New">(noop mailbox)</font></strong></p>
 418
 419 <p align="left">does nothing but&nbsp; 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.&nbsp;&nbsp; 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>.&nbsp;&nbsp;&nbsp; </p>
 425
 426 <p align="left">&nbsp;</p>
 427
 428 <p align="left"><font face="Courier New"><strong>(search-mailbox mailbox search-expression
 429 &amp;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.&nbsp;&nbsp; </strong>If <strong>uid</strong> is true then unique ids
 433 will be returned instead of message sequence numbers.&nbsp; See the section
 434 &quot;Searching for messages&quot; for details on the <strong>search-expression</strong>.</p>
 435
 436 <p align="left">&nbsp;</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.&nbsp;&nbsp; This information
 442 can potentially be updated each time a request is made to the <strong>imap </strong>server.
 443 &nbsp;&nbsp; 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">&nbsp;</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 &nbsp; 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">&nbsp;</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">&nbsp;</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">&nbsp;</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">&nbsp;</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&nbsp; unique id assigned to the
 480 next message.</p>
 481
 482 <p align="left">&nbsp;</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">&nbsp;</p>
 489
 490 <p align="left">&nbsp;</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.&nbsp;&nbsp; There are a wide
 496 variety of specifiers, some redundant and overlapping, described in the imap specification
 497 in rfe2060.&nbsp; We'll describe the most common ones here.&nbsp;&nbsp; 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. &quot;(flags envelope)&quot;.&nbsp;&nbsp; </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.&nbsp;&nbsp; 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.&nbsp;&nbsp; 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">&nbsp;</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.&nbsp;&nbsp; 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">&nbsp;</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.&nbsp;&nbsp;&nbsp;&nbsp; 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>&nbsp; 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 &quot;string&quot;) </strong>- true if the envelope
 562     structure's bcc field contains this &quot;string&quot;.</p>
 563   </li>
 564   <li><p align="left"><strong>(:before date)</strong> - true if the messages internal date is
 565     before this date.&nbsp; The date can either be a string in the rfc822 form (e.g.
 566     &quot;7-Mar-1999&quot;) or a lisp universal time.</p>
 567   </li>
 568   <li><p align="left"><strong>(:body &quot;string&quot;) </strong>- true if the body of the
 569     message contains &quot;string&quot;</p>
 570   </li>
 571   <li><p align="left"><strong>(:cc &quot;string&quot;)</strong> -&nbsp; true if the envelope
 572     structure's cc field contains this &quot;string&quot;.</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 &quot;string&quot;)</strong> -&nbsp; true if the envelope
 584     structure's from&nbsp; field contains this &quot;string&quot;.</p>
 585   </li>
 586   <li><p align="left"><strong>(:header &quot;field&quot; &quot;string&quot;)</strong> - true
 587     if the message contains a header named &quot;field&quot; and its value contains
 588     &quot;string&quot;.</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.&nbsp; 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 &quot;string&quot;) </strong>- true if the Subject
 616     header line of the message contains &quot;string&quot;</p>
 617   </li>
 618   <li><p align="left"><strong>(:text &quot;string&quot;) </strong>- true if the message's
 619     header or body contains the specified &quot;string&quot;</p>
 620   </li>
 621   <li><p align="left"><strong>(:to &quot;string&quot;)</strong> - true if the envelope
 622     structure's to field contains this &quot;string&quot;.</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">&nbsp;</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">&nbsp;</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 &quot;mailmachine.franz.com&quot;
 659
 660                             :user &quot;myacct&quot;
 661
 662                             :password &quot;mypasswd&quot;))
 663
 664 #&lt;mailbox::imap-mailbox @ #x2064ca4a&gt;</pre>
 665 </div>
 666
 667 <p align="left">&nbsp;</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 &quot;inbox&quot;)
 675
 676 t</pre>
 677 </div>
 678
 679 <p align="left">&nbsp;</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.&nbsp;&nbsp; Fetch the
 692 whole 4th message.&nbsp; We could call (fetch-letter mb 4) here instead and then not have
 693 to call fetch-field later.</strong></p>
 694 <div align="left">
 695
 696 <pre>
 697
 698 user(5): (setq body (fetch-parts mb 4 &quot;body[]&quot;))
 699
 700 ((4
 701
 702 (&quot;BODY[]&quot; &quot;Return-Path: &lt;jkfmail@tiger.franz.com&gt;
 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 &lt;jkfmail@tiger.franz.com&gt;; 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 &lt;jkfmail@tiger.franz.com&gt;
 713
 714 Message-Id: &lt;199909131836.LAA20261@tiger.franz.com&gt;
 715
 716
 717
 718 message number 5
 719
 720 &quot;)))</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.&nbsp;&nbsp; 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 &quot;body[]&quot; body)
 731
 732 &quot;Return-Path: &lt;jkfmail@tiger.franz.com&gt;
 733
 734 Received: from tiger.franz.com (jkf@tiger [192.132.95.103])
 735
 736 &nbsp;&nbsp;&nbsp; by tiger.franz.com (8.8.7/8.8.7) with SMTP id LAA20261
 737
 738 &nbsp;&nbsp;&nbsp; for &lt;jkfmail@tiger.franz.com&gt;; 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 &lt;jkfmail@tiger.franz.com&gt;
 743
 744 Message-Id: &lt;199909131836.LAA20261@tiger.franz.com&gt;
 745
 746
 747
 748 message number 5
 749
 750 &quot;</pre>
 751 </div>
 752
 753 <p align="left"><strong>We use the search function to find all the messages containing the
 754 word blitzfig.&nbsp; It turns out there is only one.&nbsp; 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 &quot;blitzfig&quot;))
 761
 762 (7)
 763
 764 user(8): (fetch-field 7 &quot;body[]&quot; (fetch-letter mb 7 &quot;body[]&quot;))
 765
 766 &quot;Return-Path: &lt;jkf@verada.com&gt;
 767
 768 Received: from main.verada.com (main.verada.com [208.164.216.3])
 769
 770 &nbsp;&nbsp;&nbsp; by tiger.franz.com (8.8.7/8.8.7) with ESMTP id NAA20541
 771
 772 &nbsp;&nbsp;&nbsp; for &lt;jkfmail@tiger.franz.com&gt;; Mon, 13 Sep 1999 13:37:24 -0700
 773
 774 Received: from main.verada.com (IDENT:jkf@localhost [127.0.0.1])
 775
 776 &nbsp;&nbsp;&nbsp; by main.verada.com (8.9.3/8.9.3) with ESMTP id NAA06121
 777
 778 &nbsp;&nbsp;&nbsp; for &lt;jkfmail@tiger.franz.com&gt;; Mon, 13 Sep 1999 13:36:54 -0700
 779
 780 Message-Id: &lt;199909132036.NAA06121@main.verada.com&gt;
 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 &lt;jkf@verada.com&gt;
 789
 790
 791
 792 secret word: blitzfig
 793
 794 ok?
 795
 796 &quot;</pre>
 797 </div>
 798
 799 <p align="left"><strong>We've been using message sequence numbers up to now. &nbsp;&nbsp;
 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.&nbsp;&nbsp; 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 &quot;blitzfig&quot;) :uid t)
 808
 809 (68)
 810
 811 user(10): (fetch-field 68 &quot;body[]&quot; (fetch-letter mb 68 &quot;body[]&quot; :uid t) :uid t)
 812
 813 &quot;Return-Path: &lt;jkf@verada.com&gt;
 814
 815 Received: from main.verada.com (main.verada.com [208.164.216.3])
 816
 817 &nbsp;&nbsp;&nbsp; by tiger.franz.com (8.8.7/8.8.7) with ESMTP id NAA20541
 818
 819 &nbsp;&nbsp;&nbsp; for &lt;jkfmail@tiger.franz.com&gt;; Mon, 13 Sep 1999 13:37:24 -0700
 820
 821 Received: from main.verada.com (IDENT:jkf@localhost [127.0.0.1])
 822
 823 &nbsp;&nbsp;&nbsp; by main.verada.com (8.9.3/8.9.3) with ESMTP id NAA06121
 824
 825 &nbsp;&nbsp;&nbsp; for &lt;jkfmail@tiger.franz.com&gt;; Mon, 13 Sep 1999 13:36:54 -0700
 826
 827 Message-Id: &lt;199909132036.NAA06121@main.verada.com&gt;
 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 &lt;jkf@verada.com&gt;
 836
 837
 838
 839 secret word: blitzfig
 840
 841 ok?
 842
 843 &quot;</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.&nbsp;&nbsp; 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.&nbsp;&nbsp; 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.&nbsp; Next we create a new mailbox, copy the messages from the inbox to
 881 the new mailbox and then delete them from the inbox.&nbsp; 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 &quot;tempbox&quot;)
 888
 889 t
 890
 891 user(18): (let ((count (mailbox-message-count mb)))
 892
 893 (copy-to-mailbox mb `(:seq 1 ,count) &quot;tempbox&quot;)
 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.&nbsp; 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 &quot;tempbox&quot;)
 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.&nbsp;&nbsp; Note that imap
 921 servers will automatically shut down a connection that's been idle for too long (usually
 922 around 10 minutes).&nbsp; When that happens, the next time the client tries to use an imap
 923 function to access the mailbox an error will occur.&nbsp;&nbsp; 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">&nbsp;</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.&nbsp;&nbsp;&nbsp;&nbsp; The functions in the interface are:</p>
 943
 944 <p>&nbsp;</p>
 945
 946 <p align="left"><font face="Courier New">(<strong>make-pop-connection host &amp;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.&nbsp;&nbsp; </strong>The
 951 <strong>port</strong> argument defaults to 110, which is the port on which the <strong>pop</strong>
 952 server normally listens.&nbsp;&nbsp;&nbsp; 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.&nbsp;&nbsp;&nbsp; In certain
 955 circumstances the server may get so busy that you see timeout errors signaled in this
 956 code.&nbsp; 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.&nbsp; 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>&nbsp;</p>
 963
 964 <p><font face="Courier New"><strong>(close-connection mb)</strong></font></p>
 965
 966 <p>Disconnect from the pop server.&nbsp; All messages marked for deletion will be deleted.</p>
 967
 968 <p>&nbsp;</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.&nbsp; <strong>mb </strong>is
 973 the mailbox object returned by <strong>make-pop-connection</strong>.&nbsp; The messages
 974 are only&nbsp; marked for deletion.&nbsp; They are not removed until a <strong>close-connection</strong>
 975 is done.&nbsp; 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.&nbsp;&nbsp; The
 982 messages in a mailbox are numbered starting with one.&nbsp; Marking a message for deletion
 983 does not affect the numbering of other messages in the mailbox.</p>
 984
 985 <p>&nbsp;</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 &nbsp;&nbsp; The letters in a mailbox are numbered starting with one.&nbsp; The entire
 991 message, including the headers,&nbsp; is returned as a string.&nbsp;&nbsp;&nbsp; It is an
 992 error to attempt to fetch a letter marked for deletion.</p>
 993
 994 <p>&nbsp;</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.&nbsp; This
1000 function parses the header lines and return an <strong>envelope</strong> structure
1001 containing information from the header.&nbsp;&nbsp;&nbsp; </p>
1002
1003 <p>&nbsp;</p>
1004
1005 <p><font face="Courier New"><strong>(noop mb)</strong></font></p>
1006
1007 <p>This is the no-operation command.&nbsp; 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).&nbsp;&nbsp; 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 &nbsp;&nbsp; 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>&nbsp;</p>
1016
1017 <p><font face="Courier New"><strong>(parse-mail-header text)</strong></font></p>
1018
1019 <p><strong>text</strong> is a string that is the first part of a mail message, including
1020 at least all of the headers lines and the blank line following the headers.&nbsp; This
1021 function parses the header lines and returns an assoc list where each item has the form <strong>(header
1022 . value)</strong>.&nbsp;&nbsp; Both the <strong>header</strong> and <strong>value</strong>
1023 are strings.&nbsp; Note that header names will most likely be mixed case (but this is not
1024 a requirment) so you'll want to use <strong>:test #'equalp</strong> when searching for a
1025 particular header with <strong>assoc</strong>.&nbsp;&nbsp; <strong>parse-mail-header</strong>
1026 returns as a second value a string that is everything after the headers (which is often
1027 referred to as the body of the message).</p>
1028
1029 <p>&nbsp;</p>
1030
1031 <p><font face="Courier New"><strong>(top-lines mb message line-count)</strong></font></p>
1032
1033 <p>Return a string that contains all the header lines and the first <strong>line-count</strong>
1034 lines of the body of <strong>message</strong>.&nbsp;&nbsp; To just retrieve the headers a <strong>line-count</strong>
1035 of zero can be given.&nbsp; See the function <strong>make-envelope-from-text</strong> for
1036 a means of reading the information in the header.</p>
1037
1038 <p>&nbsp;</p>
1039
1040 <p><font face="Courier New"><strong>(unique-id mb &amp;optional message)</strong></font></p>
1041
1042 <p>Return the unique indentifier for the given message, or for all non-deleted messages if
1043 <strong>message</strong> is nil.&nbsp;&nbsp; The unique identifier is is a string that is
1044 different for every message.&nbsp;&nbsp; If the <strong>message</strong> argument&nbsp; is
1045 not given then this command returns a list of lists where each list contains two items:
1046 the message number and the unique id.</p>
1047
1048 <h1>Cond<a name="conditions"></a>itions</h1>
1049
1050 <p>When an unexpected event occurs a condition is signaled.&nbsp;&nbsp; This applies to
1051 both the <strong>imap</strong> and <strong>pop</strong> interfaces.&nbsp; There are two
1052 classes of conditions signaled by this package:
1053
1054 <ul>
1055   <li><strong>po-condition</strong> - this class denotes conditions that need not and in fact
1056     should not interrupt program flow.&nbsp;&nbsp; When the mailbox server is responding to a
1057     command it sometimes sends informational warning messages and we turn them into
1058     conditions.&nbsp;&nbsp;&nbsp; It's important for all messages from the server to be read
1059     and processed otherwise the next command issued will see messages in response to the
1060     previous command.&nbsp;&nbsp; Therefore the user code should never do a non-local-transfer
1061     in response to a <strong>po-condition.</strong></li>
1062   <li><strong>po-error - </strong>this class denotes conditions that will prevent execution
1063     from continuing.&nbsp; If one of these errors is not caught, the interactive debugger will
1064     be entered.</li>
1065 </ul>
1066
1067 <p>Instances of both of these condition classes have these slots in addition to the
1068 standard condition slots:&nbsp; </p>
1069
1070 <table border="1" width="100%">
1071   <tr>
1072     <td width="16%">Name</td>
1073     <td width="24%">Accessor</td>
1074     <td width="60%">Value</td>
1075   </tr>
1076   <tr>
1077     <td width="16%">identifier</td>
1078     <td width="24%">po-condition-identifier</td>
1079     <td width="60%">keyword describing the kind of condition being signaled.&nbsp; See the
1080     table below for the possible values.</td>
1081   </tr>
1082   <tr>
1083     <td width="16%">server-string</td>
1084     <td width="24%">po-condition-server-string</td>
1085     <td width="60%">If the condition was created because of a messages sent from the mailbox
1086     server then this is that message.</td>
1087   </tr>
1088 </table>
1089
1090 <p>The meaning of the identifier value is as follows</p>
1091
1092 <table border="1" width="100%">
1093   <tr>
1094     <td width="11%"><strong>Identifier</strong></td>
1095     <td width="13%">Kind</td>
1096     <td width="76%">Meaning</td>
1097   </tr>
1098   <tr>
1099     <td width="11%"><strong>:problem</strong></td>
1100     <td width="13%">po-condition</td>
1101     <td width="76%">The server has responded with a warning message.&nbsp;&nbsp; The most
1102     likely warning is that the mailbox can only be opened in read-only mode due to another
1103     processing using it.</td>
1104   </tr>
1105   <tr>
1106     <td width="11%"><strong>:unknown-ok</strong></td>
1107     <td width="13%">po-condition</td>
1108     <td width="76%">The server has sent an informative message that we don't understand.
1109     &nbsp; It's probably safe to ignore this.</td>
1110   </tr>
1111   <tr>
1112     <td width="11%"><strong>:unknown-untagged</strong></td>
1113     <td width="13%">po-condition</td>
1114     <td width="76%">The server has sent an informative message that we don't understand.
1115     &nbsp; It's probably safe to ignore this.</td>
1116   </tr>
1117   <tr>
1118     <td width="11%"><strong>:error-response</strong></td>
1119     <td width="13%">po-error</td>
1120     <td width="76%">The server cannot execute the requested command.</td>
1121   </tr>
1122   <tr>
1123     <td width="11%"><strong>:syntax-error</strong></td>
1124     <td width="13%">po-error</td>
1125     <td width="76%">The arguments to a function in this package are malformed.</td>
1126   </tr>
1127   <tr>
1128     <td width="11%"><strong>:unexpected</strong></td>
1129     <td width="13%">po-error</td>
1130     <td width="76%">The server has responded a way we don't understand and which prevents us
1131     from continuing</td>
1132   </tr>
1133   <tr>
1134     <td width="11%"><strong>:server-shutdown-connection</strong></td>
1135     <td width="13%">po-error</td>
1136     <td width="76%">The connection to the server has been broken.&nbsp; This usually occurs
1137     when the connection has been idle for too long and the server intentionally disconnects.
1138     &nbsp;&nbsp; Just before this condition is signaled we close down the socket connection to
1139     free up the socket resource on our side.&nbsp; When this condition is signaled the user
1140     program should not use the mailbox object&nbsp; again (even to call <strong>close-connection</strong>
1141     on it).</td>
1142   </tr>
1143   <tr>
1144     <td width="11%"><strong>:timeout</strong></td>
1145     <td width="13%">po-error</td>
1146     <td width="76%">The server did not respond quickly enough.&nbsp;&nbsp; The timeout value
1147     is set in the call to <strong>make-imap-connection.</strong></td>
1148   </tr>
1149 </table>
1150
1151 <h1><a name="smtp"></a>The smtp interface</h1>
1152
1153 <p>With the smtp interface, a Lisp program can contact a mail server and send electronic
1154 mail.&nbsp;&nbsp; The contents of the message must be a simple text string.&nbsp; There is
1155 no provision for encoding binary data and sending it as a Mime attachment.</p>
1156
1157 <p>&nbsp;</p>
1158
1159 <p><font face="Courier New"><strong>(send-letter mail-server from to message &amp;key
1160 subject reply-to)</strong></font></p>
1161
1162 <p><strong>mail-server</strong> can be a string naming a machine or an integer IP address.
1163 &nbsp; The <strong>mail-server</strong> is contacted and asked to send a <strong>message</strong>
1164 (a string) <strong>from</strong> a given email address <strong>to</strong> a given email
1165 address or list of addresses.&nbsp;&nbsp; The email addresses must be of the form
1166 &quot;foo&quot; or <a href="mailto:foo@bar.com">&quot;foo@bar.com&quot;</a>.&nbsp; You can
1167 <strong>not</strong> use addresses like <a href="mailto:Joe%20%3cfoo@bar.com%3e">&quot;Joe
1168 &lt;foo@bar.com&gt;&quot;</a> or <a href="mailto:(Joe)%20foo@bar.com">&quot;(Joe)
1169 foo@bar.com&quot;</a>.&nbsp;&nbsp; </p>
1170
1171 <p>A mail header is built and prepended to the <strong>message</strong> before it is sent.
1172 &nbsp; The mail header includes a <strong>From </strong>and <strong>To</strong> line and
1173 will optionally include a&nbsp; <strong>Subject</strong> and <strong>Reply-To</strong>
1174 line if those are given in the call to <strong>send-letter.</strong>.</p>
1175
1176 <p>The text of the <strong>message</strong> should be lines separated by #\newline's.
1177 &nbsp;&nbsp; The <strong>smtp</strong> interface will automatically insert the necessary
1178 #\returns's when it transmits the message to the mail server.</p>
1179
1180 <p>&nbsp;</p>
1181
1182 <p>&nbsp;</p>
1183
1184 <p><font face="Courier New"><strong>(send-smtp mail-server from to &amp;rest messages)</strong></font></p>
1185
1186 <p><strong>mail-server</strong> can be a string naming a machine or an integer IP address.
1187 &nbsp; The <strong>mail-server</strong> is contacted and asked to send a&nbsp; message <strong>from</strong>
1188 a given email address <strong>to</strong> a given email address or list of addresses.
1189 &nbsp;&nbsp; The email addresses must be of the form &quot;foo&quot; or <a
1190 href="mailto:foo@bar.com">&quot;foo@bar.com&quot;</a>.&nbsp; You can <strong>not</strong>
1191 use addresses like <a href="mailto:Joe%20%3cfoo@bar.com%3e">&quot;Joe
1192 &lt;foo@bar.com&gt;&quot;</a> or <a href="mailto:(Joe)%20foo@bar.com">&quot;(Joe)
1193 foo@bar.com&quot;</a>.&nbsp;&nbsp; </p>
1194
1195 <p>The message sent is a concatenation of all of the <strong>messages</strong> (which
1196 should be strings).&nbsp;&nbsp; A header is <strong>not</strong> prepended to the message.
1197 &nbsp; This means that the application program can build its own header if it wants to
1198 include in that header more than <strong>send-letter</strong> supports (e.g. a Mime
1199 encoded attachment).&nbsp; If no header is provided then some mail servers (e.g. <strong>sendmail</strong>)
1200 will notice this fact and will automatically create a header.</p>
1201
1202 <p>The text of the <strong>messages</strong> should be lines separated by #\newline's.
1203 &nbsp;&nbsp; The <strong>smtp</strong> interface will automatically insert the necessary
1204 #\returns's when it transmits the message to the mail server.</p>
1205
1206 <p>&nbsp;</p>
1207
1208 <p>&nbsp;</p>
1209
1210 <p>&nbsp;</p>
1211
1212 <p>&nbsp;</p>
1213 </body>
1214 </html>