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"

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.

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:

• a content type,
• a content subtype,
• options.

Example:

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

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)))

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.

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:

• utf-8
• iso-latin-1
• cp-1252

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"

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.

• photo is a flat list of strings.
• x-thumbnail an optional thumbnail image.
• x-color an optional color.
• xx-extras a list of non standard properties.
• phones is an alist whose elements are pairs of two strings.
• addresses is a list composed of:
• the postoffice, a string,
• a list of strings denoting the street address,
• a string denoting the city,
• a string denoting the region,
• a string denoting the zip code,
• a string denoting the zip country.
All street values are required and must be provided. The empty string should be used to denote empty values.

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.

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])"))

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"

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"

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.

&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.

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))

mailbox-separator mailboxbigloo mail procedure

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

mailbox-prefix mailboxbigloo mail procedure

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

mailbox-hostname mailboxbigloo mail procedure

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

mailbox-folders mailboxbigloo mail procedure

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

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.

mailbox-folder-unselect! mailboxbigloo mail procedure

Unselects the mailbox current selected folder.

mailbox-folder-create! mailbox folderbigloo mail procedure

Creates a new folder denotes by a fully qualified name.

Example

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

mailbox-folder-delete! mailbox folderbigloo mail procedure

Deletes an empty folder.

mailbox-folder-rename! mailbox old newbigloo mail procedure

Renames a folder.

mailbox-folder-move! mailbox folder destbigloo mail procedure

Moves the folder into the destination folder dest.

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.

mailbox-folder-exists? mailbox folderbigloo mail procedure

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

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.

mailbox-folder-uids mailboxbigloo mail procedure

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

mailbox-folder-dates mailboxbigloo mail procedure

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

mailbox-folder-delete-messages! mailboxbigloo mail procedure

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

mailbox-folder-header-fields mailbox fieldbigloo mail procedure

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

mailbox-message mailbox uidbigloo mail procedure

Returns the message uid in the current folder.

mailbox-message-path mailbox uidbigloo mail procedure

Returns the full path name of the message uid.

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.

mailbox-message-header mailbox uidbigloo mail procedure

Returns the header as a string of the message uid.

mailbox-message-header-list mailbox uidbigloo mail procedure

Returns the header as an alist of the message uid.

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

Extracts one field from the message header.

mailbox-message-size mailbox uidbigloo mail procedure

Returns the size of the message.

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.

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:

• \Flagged
• \Answered
• \Deleted
• \Seen

mailbox-message-delete! mailbox uidbigloo mail procedure

Deletes the message uid.

mailbox-message-move! mailbox uid folderbigloo mail procedure

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

mailbox-message-create! mailbox folder contentbigloo mail procedure

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

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"))))

&imap-parse-errorbigloo mail class

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

&imap-errorbigloo mail class

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

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))

imap-logout socketbigloo mail procedure

Closes an imap connection.

imap-capability socketbigloo mail procedure

Returns the list of capabilities supported the imap server.

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))

&maildir-errorbigloo mail class

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