Retrieving Email¶

POP Methods¶

The following describes the email_pop type and some of its member methods:

type email_pop¶

email_pop(-server=?, -port=?, -username=?, -password=?, -APOP=?, -timeout=?, -log=?, -debug=?, -get=?, -host=?, -ssl=?, ...)

Creates a new POP connection object. Requires a -host parameter. Accepts optional -port and -timeout parameters. The -APOP parameter selects authentication method. If -username and -password are specified then a connection is opened to the server with authentication. The -get parameter specifies which command to perform when calling email_pop->get.

email_pop->size()¶

Returns the number of messages available for download.

email_pop->get(command::string=?)¶

Performs the command specified when the object was created. “UniqueID” by default, or can be set to “Retrieve”, “Headers”, or “Delete”.

email_pop->retrieve(position::integer=?)¶

email_pop->retrieve(position::integer, maxLines::integer)

Retrieves the current message from the server. Optionally accepts a position to retrieve a specific message. An optional second parameter specifies the maximum number of lines to fetch for each email.

email_pop->headers(position::integer=?)¶

Retrieves the headers of the current message from the server. Optionally accepts a position to get the headers of a specific message.

email_pop->uniqueID(position::integer=?)¶

Retrieves the unique ID of the current message from the server. Optionally accepts a position to get the unique ID of a specific message.

email_pop->delete(position::integer=?)¶

Marks the current message for deletion. Optionally accepts a position to mark a specific message.

email_pop->close()¶

Closes the POP connection, performing any specified deletes.

email_pop->cancel()¶

Closes the POP connection, but does not perform any deletes.

email_pop->noOp()¶

Sends a ping to the server. Allows the connection to be kept open without timing out.

email_pop->authorize(-username::string, -password::string, -APOP::boolean=true)¶

Requires a -username and -password parameter. An optional -APOP parameter specifies whether APOP authentication should be used or not. Opens a connection to the server if one is not already established.

Message Retrieval¶

The email_pop type is intended to be used with the iterate method to quickly loop through all available messages on the server. The email_pop->size method returns the number of available messages. The email_pop->get method fetches the “UniqueID” of the current message by default or can be set to “Retrieve” the current message, the “Headers” of the current message, or even to “Delete” the current message.

The -host, -username, and -password should be passed to the email_pop object when it is created. The -get parameter specifies what command the email_pop->get method will perform. In this case it is set to “UniqueID” (the default).

local(myPOP) = email_pop(
   -host     = 'mail.example.com',
   -username = 'POPUSER',
   -password = 'MySecretPassword',
   -get      = 'UniqueID'
)

The iterate method can then be used on the “myPOP” variable. For example, this code will download and delete every message from the target server. The variable “myID” is set to the unique ID of each message in turn. The email_pop->retrieve method fetches the current message and the email_pop->delete method marks it for deletion.

iterate(#myPOP, local(myID)) => {^
   #myID
   '<br />'
   #myPOP->retrieve
   #myPOP->delete
   '<hr />'
^}

// =>
// 000000025280dd26
// <br />
// Return-Path: <joe@example.com>
// X-Original-To: jane@example.com
// Delivered-To: jane@example.com
// Received: from mail.example.com (mail.example.com [127.0.0.1])
//     by mail.example.com (Postfix) with ESMTP id 1B11410A37
//     for <jane@example.com>; Mon, 11 Nov 2013 08:33:59 -0500 (EST)
// Received: (qmail 4313 invoked from network); 11 Nov 2013 08:36:28 -0500
// Message-ID: <5280DCC0.6070809@example.com>
// Date: Mon, 11 Nov 2013 08:33:52 -0500
// From: joe@example.com
// MIME-Version: 1.0
// To: jane@example.com
// Subject: Test
// Content-Type: text/plain; charset=ISO-8859-1; format=flowed
// Content-Transfer-Encoding: 7bit
//
// Testing
// <hr />

Both email_pop->retrieve and email_pop->delete could be specified with the current loop_count as a parameter, but it is unnecessary since they pick up the loop count from the surrounding iterate method. This example only downloads and displays the text of each message. Most solutions will use the email_parse type defined below to parse and process the downloaded :messages.

None of the deletes will actually be performed until the connection to the remote server is closed. The email_pop->close method performs all deletes and closes the connection. The email_pop->cancel method closes the connection, but cancels all of the marked deletes.

#myPOP->close

Using Email_Pop¶

This section includes examples of the most common tasks that are performed using the email_pop type. See the section Parsing Email for examples of downloading messages and parsing them for storage in a database.

local(myPOP) = email_pop(
   -host     = 'mail.example.com',
   -username = 'POPUSER',
   -password = 'MySecretPassword'
)

iterate(#myPOP, local(myID)) => {
   local(myMsg) = #myPOP->retrieve

   // ... process message ...

   #myPOP->delete
}
#myPOP->close

local(myPOP) = email_pop(
   -host     = 'mail.example.com',
   -username = 'POPUSER',
   -password = 'MySecretPassword'
)
iterate(#myPOP, local(myID)) => {
   #myUniqueIDs->contains(#myID) ? loop_continue

   #myUniqueIDs->insert(#myID)

   // ... process message ...

}
#myPOP->close

local(myPOP) = email_pop(
   -host     = 'mail.example.com',
   -username = 'POPUSER',
   -password = 'MySecretPassword',
   -get      = 'UniqueID'
)
iterate(#myPOP, local(myID)) => {
   local(needDownload) = false
   local(needDelete)   = false
   local(myHeaders)    = #myPOP->headers

   // ... process headers and set #needDownload or #needDelete to true ...

   #needDownload ? #myPOP->retrieve
   #needDelete ? #myPOP->delete
}
#myPOP->close

Email Structure¶

The basic structure of a simple email message is shown below. The message starts with a series of headers. The headers of the message are followed by a blank line, then the body of the message.

Each server that handles the message adds its own Received headers, so there may be many of them. The Mime-Version, Content-Type, and Content-Transfer-Encoding headers specify what type of email message it is and how it is encoded. The Message-ID is a unique ID given to the message by the email server. The To, From, Subject, and Date headers are all specified by the sending user in their email client (or in Lasso using email_send).

Received: From [127.0.0.1] BY example.com ([127.0.0.1]) WITH ESMTP;
   Thu, 08 Jul 2004 08:07:42 -0700
Mime-Version: 1.0
Content-Type: text/plain; charset=US-ASCII;
Message-Id: <8F6A8289-D0F0-11D8-B21D-0003936AD948@example.com>
Content-Transfer-Encoding: 7bit
From: Example Sender <example@example.com>
Subject: Test Message
Date: Thu, 8 Jul 2004 08:07:42 -0700
To: Example Recipient <example@example.com>

This is the email message!

The order of headers is unimportant and each header is usually specified only once (except for the Received headers which are in reverse chronological order). A header can be continued on the following line by starting the second line with a space or tab. Beyond those standard headers shown here, email messages can also contain many other headers identifying the sending software, logging spam and virus filtering actions, or even adding meta information like a picture of the sender.

A more complex email message is shown below. This message has a Content-Type of multipart/alternative. The body of the message is divided into two parts, one text part and one HTML part. The parts are divided using the boundary specified in the Content-Type header (---=_NEXT_fda4fcaab6).

Each of the parts is formatted similarly to an email message. They have several headers followed by a blank line and the body of the part. Each part has a Content-Type and a Content-Transfer-Encoding which specify the type part (either text/plain or text/html) and encoding.

Received: From [127.0.0.1] BY example.com ([127.0.0.1]) WITH ESMTP;
Thu, 08 Jul 2004 08:07:42 -0700
Mime-Version: 1.0
Message-Id: <14501276655.1089394748105@example.com>
From: Example Sender <example@example.com>
Subject: Test Message
Date: Thu, 8 Jul 2004 08:07:42 -0700
To: Example Recipient <example@example.com>
Content-Type: multipart/alternative; boundary="---=_NEXT_fda4fcaab6";

-----=_NEXT_fda4fcaab6
Content-Type: text/plain; charset=ISO-8859-1
Content-Transfer-Encoding: 8bit

This is the text part of the email message!

-----=_NEXT_fda4fcaab6
Content-Type: text/html; charset=ISO-8859-1
Content-Transfer-Encoding: 8bit

<html>
<body>
<h3>This is the HTML part of the email message!</h3>
</body>
</html>
-----=_NEXT_fda4fcaab6--

Attachments to an email message are included as additional parts. Typically, the file that is attached is encoded using Base64 encoding so it appears as a block of random letters and numbers. It is possible for one part of an email to itself have a Content-Type of multipart/alternative and its own boundary. In this way, very complex recursive email structures can be created.

Lasso allows access to the headers and each part (including recursive parts) of downloaded email messages through the email_parse type.

Parsing Methods¶

The email_parse type requires the raw MIME text of an email message as a parameter when it is created. It returns an object whose member methods can inspect the headers and parts of the email message. Outputting an email_parse object to the page will result in a message formatted with the most common headers and the default body part. An email_parse object can be used with the iterate method to inspect each part of the message in turn.

type email_parse¶

email_parse(mime::string)

Parses the raw MIME text of an email. Requires a single string parameter. Outputs the raw data of the email if displayed on the page or converted to a string.

email_parse->headers()¶

Returns an array of pairs containing all the headers of the message.

email_parse->header(name::string, ...)¶

Returns a single specified header. Requires one parameter, the name of the header to be returned. See also the shortcuts for specific headers listed below. If -extract is specified then any comments in the header will be stripped. If -comment is specified then only the comments will be returned. If -safeEmail is specified then the email address will be obscured for display on the web. If -noDecode is specified then the raw header is returned without Quoted-Printable or BinHex decoding. It will return an array if multiple headers with the same name are found. Optionally, -join can specify a character to be used to combine the values in the array into a string.

email_parse->mode()¶

Returns the mode from the Content-Type for the message. Usually either text or multipart.

email_parse->body(-type=void, -preamble=void, -array=void, ...)¶

Returns the body of the message. An optional parameter specifies the preferred type of body to return (e.g. text/plain or text/html). If the body is encoded using Quoted-Printable or Base64 encoding then it is automatically decoded before being returned by this method.

email_parse->size() → integer¶

Returns the number of parts in the message.

email_parse->get(position::integer)¶

Returns the specified part of the message. Requires an integer parameter. The part is returned as an email_parse object that can be further inspected.

email_parse->data()¶

Returns the raw data of the message.

email_parse->rawHeaders()¶

Returns the raw data of the headers.

email_parse->recipients()¶

Returns an array containing all of the email addresses in the To, Cc, and Bcc headers.

email_parse->to(...)¶

email_parse->from(...)¶

email_parse->cc(...)¶

email_parse->bcc(...)¶

email_parse->subject()¶

email_parse->date()¶

email_parse->content_type()¶

email_parse->boundary()¶

email_parse->charset()¶

email_parse->content_disposition()¶

email_parse->content_transfer_encoding()¶

These are shortcuts that return the value for the corresponding header from the email message. The table below maps the method to the header. (The Bcc header will always be empty for received emails.)

Email Header Methods¶

Email Header Method	Email Header
email_parse->to	To
email_parse->from	From
email_parse->cc	Cc
email_parse->bcc	Bcc
email_parse->subject	Subject
email_parse->date	Date
email_parse->content_type	Content-Type (MIME Type)
email_parse->boundary	Content-Type (boundary)
email_parse->charset	Content-Type (charset)
email_parse->content_disposition	Content-Disposition
email_parse->content_transfer_encoding	Content-Transfer-Encoding

The methods to, from, cc, and bcc also accept -extract, -comment, and -safeEmail parameters like the email_parse->header method. These methods join multiple parameters by default, but -join=null can be specified to return an array instead.

Using Email_Parse¶

This section includes examples of the most common tasks that are performed using the email_parse type. See the preceding section on the email_pop type for examples of downloading messages from a POP email server.

<?lasso
   local(myPOP) = email_pop(
      -host     = 'mail.example.com',
      -username = 'POPUSER',
      -password = 'MySecretPassword'
   )
   iterate(#myPOP, local(myID))
      local(myMsg) = #myPOP->retrieve
?>
<h3>Message: [#myID]</h3>
<pre>[email_parse(#myMsg)]</pre>
<hr />
<?lasso
   /iterate
   #myPOP->close
?>

// =>
// <h3>Message: 000000045280dd26</h3>
// <pre>Date: Mon 11 Nov 2008 9:0:0 -0500
// From: joe@example.com
// To: jane@example.com
// Subject: Test
// Content-Type: text/plain; charset=ISO-8859-1; format=flowed
// Content-Transfer-Encoding: 7bit
//
// Just Testing
// </pre>
// <hr />

local(myParse) = email_parse(#myMsg)
'<pre>' + #myParse->body(-type='text/plain')->encodeHtml + '</pre>'
'<hr />' + #myParse->body(-type='text/html')->encodeHtml + '<hr />'

local(myParse) = email_parse(#myMsg)
iterate(#myParse, local(myPart))
   iterate(#myPart->header, local(header))
      '<br />' + #header->first->encodeHtml + ': ' + #header->second->encodeHtml + '\n'
   /iterate
   '<br />' + #myPart->body->encodeHtml + '\n'
   '<hr />\n'
/iterate

// =>
// <br />Content-Type: text/plain; charset=ISO-8859-1
// <br />Content-Transfer-Encoding: 8bit
// <br />This is the text part of the email message!
// <hr />
// <br />Content-Type: text/html; charset=ISO-8859-1
// <br />Content-Transfer-Encoding: 8bit
// <br />&lt;html&gt;
// &lt;body&gt;
// &lt;h3&gt;This is the HTML part of the email message!&lt;/h3&gt;
// &lt;/body&gt;
// &lt;/html&gt;
// <hr />

local(myParse) = email_parse(#myMsg)
if(#myParse->mode >> 'multipart') => {
   iterate(#myParse, local(myPart)) => {
      if(#myPart->content_disposition >> 'attachment') => {
         local(myFile)     = file('/Attachments/' + #myPart->content_type('name'))
         local(myFileData) = #myPart->body
         #myFile->doWithClose => {
            #myFile->openWrite&writeBytes(#myFileData)
         }
      }
   }
}