ToC | DocOverview | CGDoc | RelNotes | FAQ | Index | PermutedIndex
| Allegro CL version 9.0 Moderate update since 9.0 release. 8.2 version

# The Allegro CL imap and pop interface

This document contains the following sections:

1.0 The IMAP interface
1.1 IMAP facility package
1.2 Mailboxes
1.3 Messages
1.4 Flags
1.5 Connecting to the server
1.6 Mailbox manipulation
1.7 Message manipulation
1.8 Mailbox Accessors
1.9 Fetching a Letter
1.10 Searching for Messages
1.11 Examples
1.11.1 Connect to the imap server on the machine holding the email
1.11.2 Select the inbox, that's where the incoming mail arrives
1.11.3 Check how many messages are in the mailbox
2.0 The Pop interface
3.0 Conditions signaled by the IMAP and Pop interfaces
4.0 MIME support
5.0 The SMTP interface (used for sending mail)
6.0 The net.mail interface for parsing and validating email addresses

imap is a client-server protocol for processing electronic mail boxes. imap is the successor to the pop protocol. It is not an upward compatible successor. The main focus of this document is the imap protocol. Only one small section describes the functions in the pop interface.

## 1.0 The IMAP interface

The imap interface is based on the Imap4rev1 protocol described in rfc2060. Where this document is describing the actions of the imap commands it should be considered a secondary source of information about those commands and rfc2060 should be considered the primary source. (We have not given a link to rfc2060 or other rfc's mentioned in this document because such links tend to become stale. To see them, use a web search site such as Google (tm).)

The advantages of imap over pop are:

1. imap can work with multiple mailboxes (pop works with a single mailbox)
2. imap typically allows mail to be read from any machine while pop typically allows mail to be read on one machine only. With imap you're encouraged to leave mail in mailboxes on the server machine, thus it can be read from any machine on the network. With pop you're encouraged to download the mail to the client machine's disk, and it thus becomes inaccessible to all other client machines.
3. imap parses the headers of messages thus allowing easier analysis of mail messages by the client program.
4. imap supports searching messages for data and sorting by date.
5. imap supports annotating messages with flags, thus making subsequent searching easier.

## 1.1 IMAP facility package

The symbols defining operators and other objects in this interface are in the net.post-office package. The functionality is in various modules. The IMAP/POP message retrieval functionality is in the :imap module. The functionality for sending messages is in the :smtp module. MIME support is in the :mime module. Symbols in the net.mail package are in the `:rfc2822` module. The :mime module is loaded automatically when the :smtp module is loaded. (Note it is not an error to require a module that is already loaded.) Sample requires are:

    (require :imap)    ;; For message retrieval
    (require :smtp)    ;; for sending messages. MIME module is
                       ;; loaded as well
    (require :mime)    ;; for MIME functionality (does not load :smtp)
    (require :rfc2822) ;; for net.mail symbols

The net.mail package and associated symbols are loaded by the :rfc2822 module (load with (require :rfc2822)). It is described in section Section 6.0 The net.mail interface for parsing and validating email addresses.

## 1.2 Mailboxes

Mailboxes are repositories for messages. Mailboxes are named by Lisp strings. The mailbox "inbox" always exists and it is the mailbox in which new messages are stored. New mailboxes can be created. They can have simple names, like "foo" or they can have hierarchical names (like "clients/california/widgetco"). After connecting to an imap server you can determine what string of characters you must use between simple names to create a hierarchical name (in this example "/" was the separator character).

Each mailbox has an associated unique number called its uidvalidity. This number won't change as long as imap is the only program used to manipulate the mailbox. In fact if you see that the number has changed then that means that some other program has done something to the mailbox that destroyed the information that imap had been keeping about the mailbox. In particular you can't now retrieve messages by their unique ids that you had used before.

## 1.3 Messages

Messages in a mailbox can be denoted in one of two ways: message sequence number or unique id.

The message sequence number is the normal way. The messages in a mailbox are numbered from 1 to N where N is the number of messages in the mailbox. There are never any gaps in the sequence numbers. If you tell imap to delete messages 3, 4, and 5 then it will return a value telling you that it has deleted messages 3, 3, and 3. This is because when you deleted message 3, message 4 became the new message 3 just before it was deleted and then message 5 became message 3 just before it was deleted.

A unique id of a message is a number associated with a message that is unique only within a mailbox. As long as the uidvalidity value of a mailbox doesn't change, the unique ids used in deleted messages will never be reused for new messages.

## 1.4 Flags

A flag is a symbol denoting that a message or mailbox has a certain property. We use keywords in Lisp to denote flags. There are two kinds of flags - System and User flags. System flags begin with the backslash character, which is an unfortunate design decision since that means that in Lisp we have to remember to use two backslashes (e.g. :\\deleted). A subset of the flags can be stored permanently in the mailbox with the messages. When a connection is made to an imap server it will return the list of flags and permanent flags (and these are stored in the mailbox server object returned for access by the program). If the list of permanent flags includes :\\* then the program can create its own flag names (not beginning with a backslash) and can store them permanently in messages.

Some of the important system flags are:

- :\\seen - this means that the message has been read (a fetch-letter has been done that includes the content of the message, not just its headers)
- :\\deleted - the message will be deleted the next time an expunge-mailbox or close-mailbox is done.
- :\\recent - this is the first session to have been notified about this message being present in the mailbox.

## 1.5 Connecting to the server

Use the function make-imap-connection to connect to the imap server of a host machine. close-connection closes the connection. with-imap-connection is a macro that connects and then closes the connection after executing body forms.

## 1.6 Mailbox manipulation

These functions work on mailboxes as a whole. The mailbox argument to the functions is the object returned by make-imap-connection. If a return value isn't specified for a function then the return value isn't important - if something goes wrong an error will be signaled.

The functions are select-mailbox, create-mailbox, delete-mailbox, and rename-mailbox.

The function mailbox-list returns information about a mailbox.

## 1.7 Message manipulation

The following functions work with the messages in the currently selected mailbox. The mailbox argument is the object returned by make-imap-connection. The messages argument is either a number (denoting a single message), or is the list (:seq N M) denoting messages N through M, or is a list of numbers and :seq forms denoting the messages specified in the list.

- alter-flags
- close-mailbox
- copy-to-mailbox
- delete-letter
- expunge-mailbox
- fetch-field
- fetch-letter
- fetch-parts
- noop
- search-mailbox

## 1.8 Mailbox Accessors

The mailbox object contains information about the imap server it's connected to as well as the currently selected mailbox. This information can potentially be updated each time a request is made to the imap server. The following functions access values from the mailbox object.

- mailbox-flags
- mailbox-permanent-flags
- mailbox-message-count
- mailbox-recent-messages
- mailbox-separator
- mailbox-uidnext
- mailbox-uidvalidity

## 1.9 Fetching a Letter

When using fetch-parts to access letters, you must specify the parts of the messages in which you are interested. There are a wide variety of specifiers, some redundant and overlapping, described in the imap specification in rfc2060. We will describe the most common ones here. The specification is always a string. It may specify more than one thing by the use of parentheses in the string, e.g. "(flags envelope)".

The most common specifiers are:

- body[] - this returns the full message: headers and body. You can use fetch-letter if you only want this part and you want to avoid having to call fetch-field.
- body[text] - this returns just the the text of the body of the message, not the header.
- body - this returns a list describing the structure of the message.
- envelope - this parses the header and returns a list of information in it. We've defined a set of accessors (like envelope-xxx, listed in the description of fetch-parts) that allow you to retrieve the envelope information easily.
- flags - return a list of the flags in the message
- uid - the unique identifier of the message

The result of a fetch-parts is a data structure containing all of the requested information. The fetch-field function is then used to extract the particular information for the particular message.

## 1.10 Searching for Messages

The imap server is able, using search-mailbox, to search for messages matching a search expression. A search-expression is a predicate (described below), or one of these forms:

- (and search-expression ...)
- (or search-expression ...)
- (not search-expression)

A predicate is

- a number in which case the predicate is true for that message number only.
- a (:seq N M) expression that is true for messages with numbers N through M.
- :all - this predicate is always true
- :answered - true if the message has the :\\answered flag
- (:bcc "string") - true if the envelope structure's bcc field contains this "string".
- (:before date) - true if the messages internal date is before this date. The date can either be a string in the rfc822 form (e.g. "7-Mar-1999") or a lisp universal time. (We have not given a link to rfc822 or other rfc's mentioned in this document because such links tend to become stale. To see them, use a web search site such as Google (tm).)
- (:body "string") - true if the body of the message contains "string"
- (:cc "string") - true if the envelope structure's cc field contains this "string".
- :deleted - true if the :\\deleted flag is set for this message
- :draft - true if the :\\draft flag is set for this message
- :flagged - true if the :\\flagged flag is set for this message
- (:from "string") - true if the envelope structure's from field contains this "string".
- (:header "field" "string") - true if the message contains a header named "field" and its value contains "string".
- (:keyword flag) - true if the specified flag is set for this message
- (:larger N) - true if the rfc822 size of the message is larger than N.
- :new - true if the message has the :\\recent flag set but not the :\\seen flag.
- :seen - true if the message has the :\\seen flag set.
- (:sentbefore date) - true if the message's Date header is earlier than the given date. See the description of :before for the format of dates.
- (:senton date) - true if the message's Date header is within the specified date.
- (:sentsince date) - true if the message's Date header is within or since the given date.
- (:smaller N) - true if the rfc822 size of the message is smaller than N
- (:subject "string") - true if the Subject header line of the message contains "string"
- (:text "string") - true if the message's header or body contains the specified "string"
- (:to "string") - true if the envelope structure's to field contains this "string".
- (:uid message-set) - true if the message is one of the messages denoted by the message set, where the message set describes messages by unique id.
- :unanswered - true if the message does not have the :\\answered flag set
- :undeleted - true if the message does not have the :\\deleted flag set
- :undraft - true if the message does not have the :\\draft flag set.
- :unflagged - true if the message does not have the :\\flagged flag set.
- (:unkeyword flag) - true if the message does not have the specified flag set.
- :unseen - true if the message does not have the :\\seen flag set.

## 1.11 Examples

We show an example of using this interface.

## 1.11.1 Connect to the imap server on the machine holding the email

The mailbox object, the value of `mb`, will be used in subsequent examples.

    user(2): (setq mb (make-imap-connection "mailmachine.franz.com"
                                :user "myacct"
                                :password "mypasswd"))
    #<mailbox::imap-mailbox @ #x2064ca4a>

## 1.11.2 Select the inbox, that's where the incoming mail arrives

The value of `mb` is the mailbox object returned by make-imap-connection in Section 1.11.1 Connect to the imap server on the machine holding the email.

    user(3): (select-mailbox mb "inbox")
    t

## 1.11.3 Check how many messages are in the mailbox

The value of `mb` is the mailbox object returned by make-imap-connection in Section 1.11.1 Connect to the imap server on the machine holding the email.

    user(4): (mailbox-message-count mb)

    7

There are seven messages at the moment. Fetch the whole 4th message. We could evaluate `(fetch-letter mb 4)` here (see fetch-letter) instead and then not have to call fetch-field later.

    user(5): (setq body (fetch-parts mb 4 "body[]"))

    ((4
     ("BODY[]" "Return-Path: <jkfmail@tiger.franz.com>
      Received: from tiger.franz.com (jkf@tiger [192.132.95.103])
        by tiger.franz.com (8.8.7/8.8.7) with SMTP id LAA20261
        for <jkfmail@tiger.franz.com>; Mon, 13 Sep 1999 11:36:26 -0700
      Date: Mon, 13 Sep 1999 11:36:26 -0700
      From: jkf mail tester <jkfmail@tiger.franz.com>
      Message-Id: <199909131836.LAA20261@tiger.franz.com>

      message number 5
      ")))

The value was returned inside a data structure designed to hold information about one or more messages. In order to extract the particular information we want we use fetch-field:

    user(6): (fetch-field 4 "body[]" body)

     "Return-Path: <jkfmail@tiger.franz.com>
     Received: from tiger.franz.com (jkf@tiger [192.132.95.103])
        by tiger.franz.com (8.8.7/8.8.7) with SMTP id LAA20261
        for <jkfmail@tiger.franz.com>; Mon, 13 Sep 1999 11:36:26 -0700
     Date: Mon, 13 Sep 1999 11:36:26 -0700
     From: jkf mail tester <jkfmail@tiger.franz.com>
     Message-Id: <199909131836.LAA20261@tiger.franz.com>

     message number 5
     "

We use the search function to find all the messages containing the word blitzfig. It turns out there is only one. We then extract the contents of that message.

    user(7): (search-mailbox mb '(:text "blitzfig"))
    (7)
    user(8): (fetch-field 7 "body[]"
               (fetch-letter mb 7 "body[]"))
    "Return-Path: <jkf@verada.com>
    Received: from main.verada.com (main.verada.com [208.164.216.3])
        by tiger.franz.com (8.8.7/8.8.7) with ESMTP id NAA20541
        for <jkfmail@tiger.franz.com>; Mon, 13 Sep 1999 13:37:24 -0700
    Received: from main.verada.com (IDENT:jkf@localhost [127.0.0.1])
        by main.verada.com (8.9.3/8.9.3) with ESMTP id NAA06121
        for <jkfmail@tiger.franz.com>; Mon, 13 Sep 1999 13:36:54 -0700
    Message-Id: <199909132036.NAA06121@main.verada.com>
    To: jkfmail@tiger.franz.com
    Subject: s test
    Date: Mon, 13 Sep 1999 13:36:54 -0700
    From: jkf <jkf@verada.com>
    secret word: blitzfig

    ok?

    "

We've been using message sequence numbers up to now. They are the simplest to use but if you're concerned with keeping track of messages when deletions are being done then using unique id's is useful. Here we do the above search example using uids:

    user(9): (search-mailbox mb '(:text "blitzfig") :uid t)
    (68)
    user(10): (fetch-field 68 "body[]"
                (fetch-letter mb 68 "body[]" :uid t) :uid t)
    "Return-Path: <jkf@verada.com>
    Received: from main.verada.com (main.verada.com [208.164.216.3])
        by tiger.franz.com (8.8.7/8.8.7) with ESMTP id NAA20541
        for <jkfmail@tiger.franz.com>; Mon, 13 Sep 1999 13:37:24 -0700
    Received: from main.verada.com (IDENT:jkf@localhost [127.0.0.1])
        by main.verada.com (8.9.3/8.9.3) with ESMTP id NAA06121
        for <jkfmail@tiger.franz.com>; Mon, 13 Sep 1999 13:36:54 -0700
    Message-Id: <199909132036.NAA06121@main.verada.com>
    To: jkfmail@tiger.franz.com
    Subject: s test
    Date: Mon, 13 Sep 1999 13:36:54 -0700
    From: jkf <jkf@verada.com>

    secret word: blitzfig
    ok?
    "

We'll delete that letter with the secret word. Note that after we have deleted that one, only six messages are left in the mailbox.

    user(11): (delete-letter mb 68 :uid t)
    (7)
    user(12): (mailbox-message-count mb)
    6

Now we assume that a bit of time has passed and we want to see if any new messages have been delivered into the mailbox. In order to find out we have to send a command to the imap server since it will only notify us of new messages when it responds to a command. Since we have nothing to ask the imap server to do we issue the noop command, which does nothing on the server.

    user(13): (noop mb)
    nil
    user(14): (mailbox-message-count mb)
    7

The server told us that there are now 7 messages in the inbox, one more than before. Next we create a new mailbox, copy the messages from the inbox to the new mailbox and then delete them from the inbox. Note how we use the :seq form to specify a sequence of messages.

    user(15): (create-mailbox mb "tempbox")
    t
    user(18): (let ((count (mailbox-message-count mb)))
    (copy-to-mailbox mb `(:seq 1 ,count) "tempbox")
    (delete-letter mb `(:seq 1 ,count)))
    (1 1 1 1 1 1 1)
    user(19): (mailbox-message-count mb)
    0

When we're done there are 0 messages in the currently selected mailbox, which is inbox. We now select the maibox we just created and see that the messages are there.

    user(22): (select-mailbox mb "tempbox")
    t
    user(23): (mailbox-message-count mb)
    7

Finally we shut down the connection. Note that imap servers will automatically shut down a connection that's been idle for too long (usually around 10 minutes). When that happens, the next time the client tries to use an imap function to access the mailbox an error will occur. There is nothing that can be done to revive the connection however it is important to call close-imap-connection on the lisp side in order to free up the resources still in use for the now dead connection.

    user(24): (close-connection mb)
    t

## 2.0 The Pop interface

The pop protocol is a very simple means for retrieving messages from a single mailbox. The functions in the interface are:

- make-pop-connection
- close-connection
- delete-letter
- fetch-letter
- noop
- make-envelope-from-text
- parse-mail-header
- top-lines
- unique-id
- with-pop-connection
- with-fetch-letter-sequence
- fetch-letter-sequence
- end-of-letter-p
- reset-mailbox
- mailbox-message-count

## 3.0 Conditions signaled by the IMAP and Pop interfaces

When an unexpected event occurs a condition is signaled. This applies to both the imap and pop interfaces. There are two classes of conditions signaled by this package:

- po-condition - this class denotes conditions that need not and in fact should not interrupt program flow. When the mailbox server is responding to a command it sometimes sends informational warning messages and we turn them into conditions. It is important for all messages from the server to be read and processed otherwise the next command issued will see messages in response to the previous command. Therefore the user code should never do a non-local-transfer in response to a po-condition.
- po-error - this class denotes conditions that will prevent execution from continuing. If one of these errors is not caught, the interactive debugger will be entered.

Instances of both of these condition classes have these slots in addition to the standard condition slots:

Name | Accessor | Value
identifier | po-condition-identifier | keyword describing the kind of condition being signaled. See the table below for the possible values.
server-string | po-condition-server-string | If the condition was created because of a message sent from the mailbox server then this is that message.

The meaning of the identifier value is as follows

Identifier | Kind | Meaning
:problem | po-condition | The server has responded with a warning message. The most likely warning is that the mailbox can only be opened in read-only mode because another process is using it.
:unknown-ok | po-condition | The server has sent an informative message that we don't understand. It's probably safe to ignore this.
:unknown-untagged | po-condition | The server has sent an informative message that we don't understand. It's probably safe to ignore this.
:error-response | po-error | The server cannot execute the requested command.
:syntax-error | po-error | The arguments to a function in this package are malformed.
:unexpected | po-error | The server has responded in a way we don't understand and which prevents us from continuing
:server-shutdown-connection | po-error | The connection to the server has been broken. This usually occurs when the connection has been idle for too long and the server intentionally disconnects. Just before this condition is signaled we close down the socket connection to free up the socket resource on our side. When this condition is signaled the user program should not use the mailbox object again (even to call close-connection on it).
:timeout | po-error | The server did not respond quickly enough. The timeout value is set in the call to make-imap-connection.
:response-too-large | po-error | The value returned by a command is too large to fit in a lisp array. When this occurs you should close the connection and reopen it since the imap/pop interface code has gotten out of sync with the imap/pop server.

## 4.0 MIME support

Allegro CL supports constructing MIME (Multipurpose Internet Mail Extensions) compliant email messages. The Allegro CL MIME API, combined with the send-letter and/or send-smtp functions make it easy to construct simple or complex MIME messages.

A full explanation of MIME is beyond the scope of this documention. MIME is defined and specified in RFC 2045 (http://www.faqs.org/rfcs/rfc2045.html). However, some of the basic concepts are described here to facilitate immediate experimentation and use.

If you want a simplified interface for sending emails with attachments, please see send-letter.

#### The MIME module

MIME functionality is in the :mime module. The :mime module is loaded automatically when the :smtp module is loaded (the :smtp module has functionality for sending messages). Use one of these require forms to load the MIME module:

    (require :mime)  ;; for MIME functionality (does not load :smtp)
    (require :smtp)  ;; for sending messages. MIME module is
                     ;; loaded as well

## MIME concepts

MIME messages can be composed of multiple pieces. In Allegro CL, these pieces are referred to as parts. Messages have at least one part. Messages that contain more than one part are called multipart messages.

There are two types of parts, multipart-parts and non-multipart parts:

- Non-multipart parts have an associated piece of information called the Content Type. The content type tells the receiver what type of information is contained in the part. Content type information is composed of a type and a subtype. The most common content type is "text/plain". The second most common is probably "text/html", for HTML emails. Another common content type is "application/octet-stream" which is a generic type that is used to indicate that information is binary data of some sort (like a program or a binary data file). RFC 2046 defines some standard content types and there are many others that are well known.
- Multipart parts have a content type that begins with "multipart". This indicates that the part exists solely to contain other parts. The subtype usually describes the relationship of the subparts. "multipart/mixed" is the most common multipart content type. It indicates that the subparts are simply different types of information, one after the other. This is typically used when a message has one or more file attachments. "multipart/alternative" is another common multipart content type that indicates that the subparts convey the same meaning but they may convey it by different means. The most common use of "multipart/alternative" is when an HTML (text/html) email message also contains a plain text (text/plain) version of the email to allow for recipients that aren't using an HTML-enabled email program. Multipart parts can contain any number and type of subparts, including other multipart parts. This allows for the construction of complex MIME messages.

### The Allegro CL MIME API

The interface contains the following classes and associated operators:

- `mime-part`: the superclass of mime part objects. (Currently, the only user-visible subclass is `mime-part-constructed`.)
- `mime-part-constructed`: the class of user-visible mime parts.
- make-mime-part: creates a MIME part (a `mime-part-constructed` object).
- mime-part-writer
- mime-part-p
- mime-part-constructed-p
- with-mime-part-constructed-stream
- mime-part-type: mime-part/mime-part-constructed slot accessor.
- mime-part-subtype: mime-part/mime-part-constructed slot accessor.
- mime-part-parameters: mime-part/mime-part-constructed slot accessor.
- mime-part-id: mime-part/mime-part-constructed slot accessor.
- mime-part-description: mime-part/mime-part-constructed slot accessor.
- mime-part-encoding: mime-part/mime-part-constructed slot accessor.
- mime-part-headers: mime-part/mime-part-constructed slot accessor.
- mime-part-parts: mime-part/mime-part-constructed slot accessor.
- mime-part-boundary: mime-part/mime-part-constructed slot accessor.

### MIME examples

    (require :smtp)  ;; Note: this loads the :mime module as well
    (use-package :net.post-office)

    ;; Construct a simple part.
    cl-user(168): (setf p1 (make-mime-part :text "This is a simple
    single-part message with text contents"))
    RETURNS #<net.post-office::mime-part-constructed @ #x71c849f2>

    ;; Let's see what it looks like when rendered

    cl-user(169): (mime-part-writer p1)
    MIME-Version: 1.0
    Content-Type: text/plain;
        charset="utf-8"
    Content-Transfer-Encoding: 7bit

    This is a simple single-part message
    with text contents
    RETURNS nil

    ;; As you can see, the headers contain only information specified by
    ;; the MIME specification.  If you want to make a top level part with
    ;; fuller headers, you can do something like the following:

    cl-user(170): (setf p1 (make-mime-part
                   :text "This is a simple message with more headers."
    	       :headers '(("From" . "Test User <joe@example.com>")
    			  ("To" . "Recipient <jimmy@yahoo.com>")
    			  ("Subject" . "This is a test email"))))
    RETURNS #<net.post-office::mime-part-constructed @ #x71c87ab2>
    cl-user(171): (mime-part-writer p1)
    MIME-Version: 1.0
    From: Test User <joe@example.com>
    To: Recipient <jimmy@yahoo.com>
    Subject: This is a test email
    Content-Type: text/plain;
        charset="utf-8"
    Content-Transfer-Encoding: 7bit

    This is a simple message with more headers.
    RETURNS nil

    ;; Or you can use send-letter which will add in these headers for you
    ;; using a simpler interface.

    cl-user(172): (setf p1 (make-mime-part :text "Simple again"))
    RETURNS #<net.post-office::mime-part-constructed @ #x71c89d9a>

    ;; send-letter will accept a mime-part as the message data and it will
    ;; fill in the headers based on the arguments you supply.
    ;; Replace "mail-server" and the sender/recipient addresses with ones
    ;; suitable for your environment.
    cl-user(173): (send-letter "mail-server"
                               "joe@example.com" "jimmy@yahoo.com" p1
                                :subject "Just testing")

    ;; You can specify the content-type if the default is not suitable.
    cl-user(176): (setf p1 (make-mime-part :text "<html><h3>Hello!</h3></html>"
    				       :content-type "text/html"))
    RETURNS #<net.post-office::mime-part-constructed @ #x71c9671a>
    cl-user(177): (mime-part-writer p1)
    MIME-Version: 1.0
    Content-Type: text/html;
        charset="utf-8"
    Content-Transfer-Encoding: 7bit

    <html><h3>Hello!</h3></html>
    nil

    ;; Now let's construct a simple multipart message.  The first part
    ;; will be introductory text and the second part will be a file
    ;; attachment.

    ;; Make the text part
    cl-user(178): (setf p1 (make-mime-part :text "Here is the file you requested"))
    RETURNS #<net.post-office::mime-part-constructed @ #x71c989f2>
    ;; Make the file attachment part, specifying the file we want to use.
    ;; You should use a small file for testing purposes.
    cl-user(179): (setf p2 (make-mime-part :file "/tmp/quickref.pdf"))
    RETURNS #<net.post-office::mime-part-constructed @ #x71c9a38a>
    ;; And finally we need a top level part to contain these two
    ;; individual parts
    cl-user(180): (setf p0 (make-mime-part :subparts (list p1 p2)))
    RETURNS #<net.post-office::mime-part-constructed @ #x71c9e34a>
    ;; Let's see what that gives us.  If the size of the file attachment
    ;; is large, then you will generate a large amount of data.
    cl-user(181): (mime-part-writer p0)
    MIME-Version: 1.0
    Content-Type: multipart/mixed;
        boundary="----------_4299707ac57b86bae36a01272cde43d0"

    This is a multi-part message in MIME format.

    - ------------_4299707ac57b86bae36a01272cde43d0
    Content-Type: text/plain;
        charset="utf-8"
    Content-Transfer-Encoding: 7bit

    Here is the file you requested
    - ------------_4299707ac57b86bae36a01272cde43d0
    Content-Type: application/pdf
    Content-Transfer-Encoding: base64
    Content-Disposition: attachment;
        filename="quickref.pdf"

    JVBERi0xLjIKJcfsj6IKNiAwIG9iago8PC9MZW5ndGggNyAwIFIvRmlsdGVyIC9GbGF0ZURl
    [ ... many lines deleted ... ]
    NzMgL1Jvb3QgMSAwIFIgL0luZm8gMiAwIFIKPj4Kc3RhcnR4cmVmCjY5MTMzCiUlRU9GCg==

    - ------------_4299707ac57b86bae36a01272cde43d0--
    RETURNS nil

    ;; When looking at the rendered output (above), you can see that you
    ;; generated a multipart/mixed message.  You can also see that the
    ;; content-type of the second part was determined to be
    ;; "application/pdf".  This was based on the filename (which ended
    ;; with .pdf).  If no suitable guess can be made,
    ;; "application/octet-stream" will be used.
    ;; You can also see that base64 encoding was used.  Base64 encoding is
    ;; always used for file attachments unless the content-type is
    ;; specified as a text-type.

    ;; Here is a more complex multipart message structured like so:
    ;;  top-level   (multipart/mixed):
    ;;    part1:    (multipart/alternative)
    ;;      part1:  (text/html)
    ;;      part2:  (text/plain)
    ;;    part2:    (application/pdf)
    ;;
    ;; This is a common arrangement for a message that includes both html
    ;; and plain text versions of the message text (so that both HTML and
    ;; non-HTML email clients can show whichever version works best).  The
    ;; message also contains a file attachment.

    cl-user(187): (setf html (make-mime-part
          :text "<html><font color=red>You have won big prizes!</font><html>"
          :content-type "text/html"))
    RETURNS #<net.post-office::mime-part-constructed @ #x71cbc4da>
    cl-user(188): (setf plain (make-mime-part :text "You have won big prizes!"))
    RETURNS #<net.post-office::mime-part-constructed @ #x71cbde1a>
    cl-user(191): (setf file (make-mime-part :file "/tmp/quickref.pdf"))
    RETURNS #<net.post-office::mime-part-constructed @ #x71cc0a5a>
    cl-user(192): (setf alternatives-container
                     (make-mime-part :content-type "multipart/alternative"
                                     :subparts (list html plain)))
    RETURNS #<net.post-office::mime-part-constructed @ #x71cc5d5a>
    cl-user(193): (setf top
                     (make-mime-part :subparts (list alternatives-container file)))
    RETURNS #<net.post-office::mime-part-constructed @ #x71cc7e92>

    ;; Fill in the To, From and Subject headers and send it off.
    cl-user(194): (send-letter "mail-server"
                               "joe@example.com" "jimmy@yahoo.com" top
                               :subject "Test email")

## 5.0 The SMTP interface (used for sending mail)

With the SMTP interface, a Lisp program can contact a mail server and send electronic mail.

The `smtp` module is not loaded automatically when the `imap` is. To load SMTP functionality into a running image, evaluate:

    (require :smtp)

The interface contains these functions:

- send-letter
- send-smtp
- send-smtp-auth
- test-email-address

## 6.0 The net.mail interface for parsing and validating email addresses

The net.mail interface allows parsing and cursory validation of portions of email addresses. Symbols in the interface are in the net.mail package. The interface is loaded with the :rfc2822 module with `(require :rfc2822)`. The interface implements part of RFC2822 (that link is to a URL outside the Allegro CL documentation).

The parse-email-address function parses an email address string. The valid-email-domain-p function provides information on whether a string naming a domain appears valid (this function is most useful in identifying obviously invalid strings since seemingly valid strings may still fail to accept email for any number of reasons). extract-email-addresses parses a string representing an email header and returns information about the email addresses found.

An email address consists of a username part, followed by @, followed by a domain name.

### parse-email-address

### Function

#### Package: net.mail

Arguments: string &key require-domain require-dotted-domain

Parses an email address string and, if the address has valid syntax, returns two values: the local part of the address and the domain part of the address. If address is invalid, the single value `nil` is returned. The keyword arguments provide some control over what is or is not considered invalid.

The parser is RFC2822 compliant except:

- It optionally allows for domain-less addresses.
- By default, it requires the domain part to have two components.
- It does not allow domain literals (e.g., "joe-user@[192.132.95.23]")
- It does not allow quoted strings.

#### Keyword arguments

require-domain, which defaults to `t`, controls whether or not domainless email addresses (i.e., addresses without the @domain part) are accepted.

require-dotted-domain, which defaults to `t`, controls whether or not non-dotted domain parts will be accepted. When `nil`, a single-component domain part will be accepted (e.g., "com"). If true, then the domain part of the email address must have at least two dotted components (e.g., "franz.com" or "mymachine.franz.com"), else `nil` is returned.

### Examples

    (require :rfc2822)
    (use-package :net.mail)
    (parse-email-address "support@franz.com")
    returns
    "support"
    "franz.com"

    (parse-email-address "david;m@franz.com")
    returns
    nil              ;; ';' is not allowed in email addresses.

    (parse-email-address "support")
    returns
    nil

    (parse-email-address "support" :require-domain nil)
    returns
    "support"
    nil

### valid-email-domain-p

### Function

#### Package: net.mail

Arguments: domain

domain should be a string (such as the second return value of parse-email-address). This function returns information on whether or not the DNS configuration for domain is configured properly for Internet email reception.

The possible return values are:

- `nil`: this means that the DNS records for domain are not properly configured for Internet email.
- `:unknown`: this means that no information was successfully collected. No conclusion can be drawn.
- `t`: this means that domain has DNS records that are suitable for Internet email reception. However, this does not necessarily mean that email delivery will succeed (it could fail for reasons unrelated to the validity of the domain).

### Note

This function is more useful for its negative response (`nil`) than any other response. If it returns `nil`, it means that no standard mail transfer agent would be able to locate the mail server for the domain. As noted above, a non-`nil` value does not guarantee that the mail will be delivered.

### Examples

    (require :rfc2822)
    (use-package :net.mail)
    (valid-email-domain-p "franz.com")
    returns
    t             ;; Under normal circumstances

    (valid-email-domain-p "xnosuchdomainx.com")
    returns
    nil           ;; at least when this document was written as
                  ;; "xnosuchdomainx.com" is a currently nonexistent
                  ;; domain name.

    (valid-email-domain-p "nosuchdomain.com")
    returns
    t             ;; under normal circumstances as at the time
                  ;; this document was written, "nosuchdomain.com"
                  ;; does exist and has a DNS MX record.

### extract-email-addresses

### Function

#### Package: net.mail

Arguments: string &key start end require-domain errorp compact

extract-email-addresses parses string and returns a list of entries describing the email addresses and display names found. This function is suitable for use on RFC2822-compliant email headers such as the To:, From:, and Cc: headers. Compliant folded lines are acceptable.

#### Keyword arguments

start and end specify the subsequence of string to operate on. start defaults to 0 and end defaults to the length of the string.

require-domain, which defaults to `t`, controls whether or not domainless email addresses (i.e., addresses without the @domain part) are accepted.

errorp, which defaults to `t`, controls whether or not to signal an error if there is a syntax error or other problem during parsing. If errorp is `nil`, then `nil` is returned if there is a problem during parsing.

compact: when true, causes extract-email-addresses to return its results as a list of `user@domain` strings (the `@domain` part may not exist if the require-domain keyword arg was `nil`).

#### Return value:

extract-email-addresses returns a list of `mailbox` and/or `group` lists, depending on the contents of string.

A `mailbox` list has the following form:

>     (:mailbox display-name user-part domain-part)

`display-name` may be `nil` if no display name was found. If `require-domain` is `nil`, `domain-part` may be `nil` if no domain part was found.

A `group` list has the following form:

>     (:group display-name mailbox-list)

`mailbox-list` will be a list of `mailbox` lists. If no mailboxes were supplied, `mailbox-list` may be `nil`.

### Examples:

    ;; Simple folded list of addresses which display names.
    cl-user(186): (extract-email-addresses "Tech Support <support@franz.com>,
                                            Sales Department <sales@franz.com>")
    returns
    ((:mailbox "Tech Support" "support" "franz.com")
     (:mailbox "Sales Department" "sales" "franz.com"))

    ;; A group commonly seen in emails.  There are no mailboxes in the group.
    cl-user(187): (extract-email-addresses "Undisclosed Recipients:;")
    returns
    ((:group "Undisclosed Recipients" nil))

    ;; A variety of legal formats:
    cl-user(188): (extract-email-addresses "root@example.com (Cron Daemon),
    Mailing List: Bill Johnson <customer1@example.com>, customer2@example.com ;")
    returns
    ((:mailbox "Cron Daemon" "root" "example.com")
     (:group "Mailing List"
      ((:mailbox "Bill Johnson" "customer1" "example.com")
       (:mailbox nil "customer2" "example.com"))))

    ;; Use of the COMPACT keyword argument:
    cl-user(13): (extract-email-addresses "root@example.com (Cron Daemon),
    Mailing List: Bill Johnson <customer1@example.com>,
    customer2@example.com ;"
                  :compact t)
    returns
    ("root@example.com" "customer1@example.com" "customer2@example.com")

    cl-user(11): (extract-email-addresses "Undisclosed Recipients:;" :compact t)

    returns
    nil

Copyright (c) 1998-2019, Franz Inc. Oakland, CA., USA. All rights reserved.
This page was not revised from the 8.2 page.
Created 2012.5.30.

ToC | DocOverview | CGDoc | RelNotes | FAQ | Index | PermutedIndex
| Allegro CL version 9.0 Moderate update since 9.0 release. 8.2 version