Mail

Bigloo provides various facilities for handling mails. It provides facilities for parsing many formats commonly used in composing mails (quoted printable, vcard, mime types). It also provides facilities for dealing with mail servers. For that it proposes an abstracted view of mail servers with two implementations: imap and maildir.

RFC 2045 -- MIME, Part one

This section described the functions offered by Bigloo to encode and decode some of the formats specified in the RFC 2045 http://tools.ietf.org/html/rfc2045.

quoted-printable-encode stringbigloo mail procedure

quoted-printable-decode stringbigloo mail procedure

These functions encode/decode a string into and from the quoted-printable format.

Examples:

(quoted-printable-encode "foo bar")  "foobar=20"
(quoted-printable-decode "foobar=20")  "foo bar"
.keep

quoted-printable-encode-port ip opbigloo mail procedure

quoted-printable-decode-port ip op [rfc2047]bigloo mail procedure

These functions are similar to quoted-printable-encode and quoted-printable-decode except that they operate on input-ports and output-ports.

The function quoted-printable-decode-port accepts an optional argument: rfc2047. If this argument is #t, then the parsing stops on the prefix ?=, which is a marker in the mail subject as specified by the RFC 2047, (see http://tools.ietf.org/html/rfc2047) is found.
.keep

mime-content-decode string bigloo mail procedure

mime-content-decode-port input-portbigloo mail procedure

These two functions parse respectively a string and an input-port and return a list of three elements:

Example:

(mime-content-type-decode "text/plain; boundary=Apple-Mail-11") 
   (text plain ((boundary . Apple-Mail-11)))
.keep

mime-content-disposition-decode stringbigloo mail procedure

mime-content-disposition-decode-port input-portbigloo mail procedure

These two functions parse respectively a string and an input-port and return a list describing the content disposition.

Example:

(mime-content-disposition-decode "attachment; filename=\"smine.p7s\"")
   (attachment ((filename . smine.p7s)))
.keep

mime-multipart-decode string boundary [recursive]bigloo mail procedure

mime-multipart-decode-port input-port boundary [recursive]bigloo mail procedure

These two functions parse respectively a string and an input-port and return a list of mime sections.

If the optional argument recursive controls whether subparts of a multipart section must be decoded are not. If the recursive is #t then all subparts of the multipart content are decoded. The result is a fully decoded multipart section. If recursive is #f subparts are not decoded and included in the result as plain strings.
.keep

RFC 2047 -- MIME, Part three

This section described the function offered by Bigloo to decode the RFC 2047 encoding used in mail headers (see http://tools.ietf.org/html/rfc2047).

rfc2047-decode-port ip op [:charset iso-latin-1]bigloo mail procedure

rfc2047-decode string [:charset iso-latin-1]bigloo mail procedure

These functions decode mail header fields encoded using the RFC 2047 specification. The optional argument charset specified in which charset the result should be encoded. The allowed values are:

Example:

(map char->integer
  (string->list (rfc2047-decode "Poste =?ISO-8859-1?Q?t=E9l=E9phonique?=")))
   (80 111 115 116 101 32 116 233 108 233 112 104 111 110 105 113 117 101)
(string-for-read (rfc2047-decode "Poste =?ISO-8859-1?Q?t=E9l=E9phonique?=" :charset 'utf8))
   "Poste t\303\251l\303\251phonique"
.keep

RFC 2426 -- MIME, Part three

This section presents the facilities supported by Bigloo for dealing with vcards.

vcardbigloo mail class

(class vcard
  (version::bstring (default "2.1"))
  (uid (default #f))
  (fn (default #f))
  (familyname (default #f))
  (firstname (default #f))
  (nickname (default #f))
  (photo (default #f))
  (sound (default #f))
  (url (default #f))
  (org (default #f))
  (emails::pair-nil (default '()))
  (phones::pair-nil (default '()))
  (birthday (default #f))
  (addresses::pair-nil (default '()))
  (lang (default #f))
  (related (default #f))
  (key (default #f))
  (notes::pair-nil (default '()))
  (x-thumbnail (default #f))
  (x-color (default #f))
  (xx-extras::pair-nil (default '())))
The class vard is used to reify in memory a vcard as parsed by the functions port->vcard, read-vcard, and string->vcard.

Except emails, phones, and addresses, all fields are optional. They should be either #f or a string. Field meanings are given by the RFC 2426 specification, apart the x-thumbnail, x-color, and xx-extras that are Bigloo specific.

.keep

read-vcard::vcard ip [:charset-encoder]bigloo mail function

port->vcard::vcard ip [:charset-encoder]bigloo mail function

string->vcard::vcard str [:charset-encoder]bigloo mail function

These three functions parse a vcard to produce a vcard instance. The optional argument charset-encoder, when provided, must be a function of argument: a string to be decoded. Vcard strings are UTF-8 encoded. The charset-encoder can be used to encode on-the-fly the strings found in the vcard in a difference encoding.

port->vcard is similar to read-vcard but it returns #f on end-of-file, while read-vcard returns the eof-object.
.keep

RFC 2822 -- Internet Message Format

This section described the functions offered by Bigloo to encode and decode some of the formats specified in the RFC 2822 (http://tools.ietf.org/html/rfc2045). It mainly supports functions for parsing email headers and for decoding email addresses.

mail-header->list objbigloo mail procedure

The function mail-header->list parses a mail header that can either be implemented as a string or an input port. It returns a list of fields.

Example:

(mail-header->list "Return-Path: <foo.bar@inria.fr>
Received: from eurus.inria.fr ([unix socket])")
  
  ((return-path . "<foo.bar@inria.fr>") (received . "from eurus.inria.fr ([unix socket])"))
.keep

email-normalize stringbigloo mail procedure

The function email-normalize extracts the actual email address from an email representation.

Example:
(email-normalize "foo bar <foo.bar@inria.fr>")  "foo.bar@inria.fr"
.keep

rfc2822-address-display-name stringbigloo mail procedure

Extract the name component of an email.

Example:
(rfc2822-address-display-name "Foo Bar <foo.bar@inria.fr>")  "Foo Bar"
(rfc2822-address-display-name "<foo.bar@inria.fr>")  "foo bar"
.keep

Mail servers -- imap and maildir

Bigloo implements the imap protocol (http://tools.ietf.org/html/rfc3501) and the maildir format. This section presents the API for manipulating them both.

Mailboxes

mailboxbigloo mail class

(abstract-class mailbox
  (label::bstring (default "")))
The abstract class mailbox is the common ancestors to all the mailbox implementations. It allows the definitions of various generic functions that deal with mail messages and mail folders.
.keep

&mailbox-errorbigloo mail class

(abstract-class &mailbox-error::&error)
The &mailbox-error is the super class of all the errors that can be raised when accessing mail servers, except the parsing errors that inherit from the &parse-error super class.
.keep

mailbox-close mailboxbigloo mail procedure

Close the mailbox connection.

Example:
(let ((mbox (if (network-up?)
                (instantiate::imap (socket ...))
                (instantiate::maildir (path my-local-cache)))))
   (mailbox-close mbox))
.keep

mailbox-separator mailboxbigloo mail procedure

Returns a string denoting the separator (commonly " or .) used by the mailbox.
.keep

mailbox-prefix mailboxbigloo mail procedure

Returns the prefix of the mailbox, a string or #f.
.keep

mailbox-hostname mailboxbigloo mail procedure

Returns the hostname of the mailbox, a string or #f.
.keep

mailbox-folders mailboxbigloo mail procedure

Returns a list of strings denoting the folder names of the mailbox.
.keep

mailbox-folder-select! mailbox stringbigloo mail procedure

Selects one folder of the mailbox. This function is central to mailboxes because all messages are referenced relatively to the folder selection. All the functions that operates on uid implicitly access the current folder selection.
.keep

mailbox-folder-unselect! mailboxbigloo mail procedure

Unselects the mailbox current selected folder.
.keep

mailbox-folder-create! mailbox folderbigloo mail procedure

Creates a new folder denotes by a fully qualified name.

Example
(mailbox-create! mbox "INBOX.scheme.bigloo")
.keep

mailbox-folder-delete! mailbox folderbigloo mail procedure

Deletes an empty folder.
.keep

mailbox-folder-rename! mailbox old newbigloo mail procedure

Renames a folder.
.keep

mailbox-folder-move! mailbox folder destbigloo mail procedure

Moves the folder into the destination folder dest.
.keep

mailbox-subscribe! mailbox folderbigloo mail procedure

mailbox-unsubscribe! mailbox folderbigloo mail procedure

Subscribe/unsubscribe to a folder. This allows imap servers not to present the entire list of folders. Only subscribed folders are returned by mailbox-folders. These functions have no effect on maildir servers.
.keep

mailbox-folder-exists? mailbox folderbigloo mail procedure

Returns #t if and only if folder exists in mailbox. Returns #f otherwise.
.keep

mailbox-folder-status mailbox folderbigloo mail procedure

Returns the status of the folder. A status is an alist made of the number of unseen mail, the uid validity information, the uid next value, the number of recent messages, and the overall number of messages.
.keep

mailbox-folder-uids mailboxbigloo mail procedure

Returns the list of UIDs (a list of integers) of the messages contained in the currently selected folder.
.keep

mailbox-folder-dates mailboxbigloo mail procedure

Returns the list of dates of the messages contained in the currently selected folder.
.keep

mailbox-folder-delete-messages! mailboxbigloo mail procedure

Deletes the messages marked as deleted of the currently selected folder.
.keep

mailbox-folder-header-fields mailbox fieldbigloo mail procedure

Returns the list of headers fields of the message of the current folder.
.keep

mailbox-message mailbox uidbigloo mail procedure

Returns the message uid in the current folder.
.keep

mailbox-message-path mailbox uidbigloo mail procedure

Returns the full path name of the message uid.
.keep

mailbox-message-body mailbox uid [len]bigloo mail procedure

Returns the body of the message uid. If len is provided, only returns the first len characters of the body.
.keep

mailbox-message-header mailbox uidbigloo mail procedure

Returns the header as a string of the message uid.
.keep

mailbox-message-header-list mailbox uidbigloo mail procedure

Returns the header as an alist of the message uid.
.keep

mailbox-message-header-field mailbox uid fieldbigloo mail procedure

Extracts one field from the message header.
.keep

mailbox-message-size mailbox uidbigloo mail procedure

Returns the size of the message.
.keep

mailbox-message-info mailbox uidbigloo mail procedure

Returns the information relative to the message uid. This a list containing the message identifier, its uid, the message date, the message size, and the message flags.
.keep

mailbox-message-flags mailbox uidbigloo mail procedure

mailbox-message-flags-set! mailbox uid lstbigloo mail procedure

Sets/Gets the flags of the message uid. This is a list of strings. Typical flags are:

.keep

mailbox-message-delete! mailbox uidbigloo mail procedure

Deletes the message uid.
.keep

mailbox-message-move! mailbox uid folderbigloo mail procedure

Moves the message uid into the new folder (denoted by a string).
.keep

mailbox-message-create! mailbox folder contentbigloo mail procedure

Creates a new message in the folder whose content is given the string content.
.keep

IMAP (RFC 3501)

imapbigloo mail class

(class imap::mailbox
  (socket::socket read-only))

(define mbox
  (instantiate::maildir
    (label "My Remote Mailbox")
    (socket (imap-login (make-client-socket "imap.inria.fr" 993)
                        "serrano" "XXX"))))
.keep

&imap-parse-errorbigloo mail class

(class &imap-parse-error::&io-parse-error)
.keep

&imap-errorbigloo mail class

(class &imap-error::&mailbox-error)
.keep

imap-login socket user passwordbigloo mail procedure

Log a user into an imap server. The socket must have been created first. The argument user is a string and denotes the user name. The argument password is a string too and it contains the user password. This function returns as value the socket it has received. If the operation fails the function raises a &imap-error exception.

Example:

(define mbox
   (imap-login (make-client-socket "imap.inria.fr" 993 :timeout 200000) 
               "serrano" "XXX"))

(print (mailbox-folders mbox))
.keep

imap-logout socketbigloo mail procedure

Closes an imap connection.
.keep

imap-capability socketbigloo mail procedure

Returns the list of capabilities supported the imap server.
.keep

Maildir

maildirbigloo mail class

(class maildir::mailbox
  (prefix::bstring read-only (default "INBOX"))
  (path::bstring read-only))
Example:

(define mbox
  (instantiate::maildir
    (label "My Mailbox")
    (path (make-file-name (getenv "HOME") ".maildir"))))

(tprint (mailbox-folders mbox))
.keep

&maildir-errorbigloo mail class

(class &maildir-error::&mailbox-error)
.keep