Previous Next

Reading Mail Messages

Zend_Mail can read mail messages from several local or remote mail storages. All of them have the same basic API to count and fetch messages and some of them implement additional interfaces for not so common features. For a feature overview of the implemented storages see the following table.

Mail Read Feature Overview
Feature Mbox Maildir Pop3 IMAP
Storage type local local remote remote
Fetch message Yes Yes Yes Yes
Fetch mime-part emulated emulated emulated emulated
Folders Yes Yes No Yes
Create message/folder No todo No todo
Flags No Yes No Yes
Quota No Yes No No

Simple example using Pop3

$mail = new Zend_Mail_Storage_Pop3(array('host'     => 'localhost',
                                         'user'     => 'test',
                                         'password' => 'test'));

echo $mail->countMessages() . " messages found\n";
foreach ($mail as $message) {
    echo "Mail from '{$message->from}': {$message->subject}\n";
}

Opening a local storage

Mbox and Maildir are the two supported formats for local mail storages, both in their most simple formats.

If you want to read from a Mbox file you only need to give the filename to the constructor of Zend_Mail_Storage_Mbox:

$mail = new Zend_Mail_Storage_Mbox(array('filename' =>
                                             '/home/test/mail/inbox'));

Maildir is very similar but needs a dirname:

$mail = new Zend_Mail_Storage_Maildir(array('dirname' =>
                                                '/home/test/mail/'));

Both constructors throw a Zend_Mail_Exception if the storage can't be read.

Opening a remote storage

For remote storages the two most popular protocols are supported: Pop3 and Imap. Both need at least a host and a user to connect and login. The default password is an empty string, the default port as given in the protocol RFC.

// connecting with Pop3
$mail = new Zend_Mail_Storage_Pop3(array('host'     => 'example.com'
                                         'user'     => 'test',
                                         'password' => 'test'));

// connecting with Imap
$mail = new Zend_Mail_Storage_Imap(array('host'     => 'example.com'
                                         'user'     => 'test',
                                         'password' => 'test'));

// example for a none standard port
$mail = new Zend_Mail_Storage_Pop3(array('host'     => 'example.com',
                                         'port'     => 1120
                                         'user'     => 'test',
                                         'password' => 'test'));

For both storages SSL and TLS are supported. If you use SSL the default port changes as given in the RFC.

// examples for Zend_Mail_Storage_Pop3, same works for Zend_Mail_Storage_Imap

// use SSL on different port (default is 995 for Pop3 and 993 for Imap)
$mail = new Zend_Mail_Storage_Pop3(array('host'     => 'example.com'
                                         'user'     => 'test',
                                         'password' => 'test',
                                         'ssl'      => 'SSL'));

// use TLS
$mail = new Zend_Mail_Storage_Pop3(array('host'     => 'example.com'
                                         'user'     => 'test',
                                         'password' => 'test',
                                         'ssl'      => 'TLS'));

Both constructors can throw Zend_Mail_Exception or Zend_Mail_Protocol_Exception (extends Zend_Mail_Exception), depending on the type of error.

Fetching messages and simple methods

Once you've opened the storage messages can be fetched. You need the message number, which is a counter starting with 1 for the first message. To fetch the message you use the method getMessage():

$message = $mail->getMessage($messageNum);

Array access is also supported, but won't supported any additional parameters that could be added to getMessage(). As long as you don't mind and can live with defaults you may use:

$message = $mail[$messageNum];

For iterating over all messages the Iterator interface is implemented:

foreach ($mail as $messageNum => $message) {
    // do stuff ...
}

To count the messages in the storage you can either use the method countMessages() or use array access:

// method
$maxMessage = $mail->countMessages();

// array access
$maxMessage = count($mail);

To remove a mail you use the method removeMessage() or again array access:

// method
$mail->removeMessage($messageNum);

// array access
unset($mail[$messageNum]);

Working with messages

After you fetched the messages with getMessage() you want to fetch headers, the content or single parts of a multipart message. All headers can be accessed via properties or the method getHeader() if you want more control or have unusual header names. The header names are lower-cased internally, thus the case of the header name in the mail message doesn't matter. Also headers with a dash can be written in camel-case.

// get the message object
$message = $mail->getMessage(1);

// output subject of message
echo $message->subject . "\n";

// get content-type header
$type = $message->contentType;

If you have multiple headers with the same name i.e. the Received headers you might want it as array instead of a string, which is possible with the getHeader() method.

// get header as property - the result is always a string,
// with new lines between the single occurrences in the message
$received = $message->received;

// the same via getHeader() method
$received = $message->getHeader('received', 'string');

// better an array with a single entry for every occurrences
$received = $message->getHeader('received', 'array');
foreach ($received as $line) {
    // do stuff
}

// if you don't define a format you'll get the internal representation
// (string for single headers, array for multiple)
$received = $message->getHeader('received');
if (is_string($received)) {
    // only one received header found in message
}

The method getHeaders() returns all headers as array with the lower-cased name as key and the value as array for multiple headers or as string for single headers.

// dump all headers
foreach ($message->getHeaders() as $name => $value) {
    if (is_string($value)) {
        echo "$name: $value\n";
        continue;
    }
    foreach ($value as $entry) {
        echo "$name: $entry\n";
    }
}

If you don't have a multipart message fetching the content is easy done via getContent(). Unlike the headers the content is only fetched when needed (aka late-fetch).

// output message content for HTML
echo '
';
echo $message->getContent();
echo '
';

Checking for a multipart message is done with the method isMultipart(). If you have multipart message you can get an instance of Zend_Mail_Part with the method getPart(). Zend_Mail_Part is the base class of Zend_Mail_Message, so you have the same methods: getHeader(), getHeaders(), getContent(), getPart(), isMultipart and the properties for headers.

// get the first none multipart part
$part = $message;
while ($part->isMultipart()) {
    $part = $message->getPart(1);
}
echo 'Type of this part is ' . strtok($part->contentType, ';') . "\n";
echo "Content:\n";
echo $part->getContent();

Zend_Mail_Part also implements RecursiveIterator, which makes it easy to scan through all parts. And for easy output it also implements the magic method __toString(), which returns the content.

// output first text/plain part
$foundPart = null;
foreach (new RecursiveIteratorIterator($mail->getMessage(1)) as $part) {
    try {
        if (strtok($part->contentType, ';') == 'text/plain') {
            $foundPart = $part;
            break;
        }
    } catch (Zend_Mail_Exception $e) {
        // ignore
    }
}
if (!$foundPart) {
    echo 'no plain text part found';
} else {
    echo "plain text part: \n" . $foundPart;
}

Checking for flags

Maildir and IMAP support storing flags. The class Zend_Mail_Storage has constants for all known maildir and IMAP system flags, named Zend_Mail_Storage::FLAG_<flagname>. To check for flags Zend_Mail_Message has a method called hasFlag(). With getFlags() you'll get all set flags.

// find unread messages
echo "Unread mails:\n";
foreach ($mail as $message) {
    if ($message->hasFlag(Zend_Mail_Storage::FLAG_SEEN)) {
        continue;
    }
    // mark recent/new mails
    if ($message->hasFlag(Zend_Mail_Storage::FLAG_RECENT)) {
        echo '! ';
    } else {
        echo '  ';
    }
    echo $message->subject . "\n";
}


// check for known flags
$flags = $message->getFlags();
echo "Message is flagged as: ";
foreach ($flags as $flag) {
    switch ($flag) {
        case Zend_Mail_Storage::FLAG_ANSWERED:
            echo 'Answered ';
            break;
        case Zend_Mail_Storage::FLAG_FLAGGED:
            echo 'Flagged ';
            break;

        // ...
        // check for other flags
        // ...

        default:
            echo $flag . '(unknown flag) ';
    }
}

As IMAP allows user or client defined flags you could get flags, that don't have a constant in Zend_Mail_Storage. Instead they are returned as string and can be checked the same way with hasFlag().

// check message for client defined flags $IsSpam, $SpamTested
if (!$message->hasFlag('$SpamTested')) {
    echo 'message has not been tested for spam';
} else if ($message->hasFlag('$IsSpam')) {
    echo 'this message is spam';
} else {
    echo 'this message is ham';
}

Using folders

All storages, except Pop3, support folders, also called mailboxes. The interface implemented by all storages supporting folders is called Zend_Mail_Storage_Folder_Interface. Also all of these classes have an additional optional parameter called folder, which is the folder selected after login, in the constructor.

For the local storages you need to use separate classes called Zend_Mail_Storage_Folder_Mbox or Zend_Mail_Storage_Folder_Maildir. Both need one parameter called dirname with the name of the base dir. The format for maildir is as defined in maildir++ (with a dot as default delimiter), Mbox is a directory hierarchy with Mbox files. If you don't have a Mbox file called INBOX in your Mbox base dir you need to set an other folder in the constructor.

Zend_Mail_Storage_Imap already supports folders by default. Examples for opening these storages:

// mbox with folders
$mail = new Zend_Mail_Storage_Folder_Mbox(array('dirname' =>
                                                    '/home/test/mail/'));

// mbox with a default folder not called INBOX, also works
// with Zend_Mail_Storage_Folder_Maildir and Zend_Mail_Storage_Imap
$mail = new Zend_Mail_Storage_Folder_Mbox(array('dirname' =>
                                                    '/home/test/mail/',
                                                'folder'  =>
                                                    'Archive'));

// maildir with folders
$mail = new Zend_Mail_Storage_Folder_Maildir(array('dirname' =>
                                                       '/home/test/mail/'));

// maildir with colon as delimiter, as suggested in Maildir++
$mail = new Zend_Mail_Storage_Folder_Maildir(array('dirname' =>
                                                       '/home/test/mail/',
                                                   'delim'   => ':'));

// imap is the same with and without folders
$mail = new Zend_Mail_Storage_Imap(array('host'     => 'example.com',
                                         'user'     => 'test',
                                         'password' => 'test'));

With the method getFolders($root = null) you can get the folder hierarchy starting with the root folder or the given folder. It's returned as instance of Zend_Mail_Storage_Folder, which implements RecursiveIterator and all children are also instances of Zend_Mail_Storage_Folder. Each of these instances has a local and a global name returned by the methods getLocalName() and getGlobalName(). The global name is the absolute name from the root folder (including delimiters), the local name is the name in the parent folder.

Mail Folder Names
Global Name Local Name
/INBOX INBOX
/Archive/2005 2005
List.ZF.General General

If you use the iterator the key of the current element is the local name. The global name is also returned by the magic method __toString(). Some folders may not be selectable, which means they can't store messages and selecting them results in an error. This can be checked with the method isSelectable(). So it's very easy to output the whole tree in a view:

$folders = new RecursiveIteratorIterator($this->mail->getFolders(),
                                         RecursiveIteratorIterator::SELF_FIRST);
echo '';

The current selected folders is returned by the method getSelectedFolder(). Changing the folder is done with the method selectFolder(), which needs the global name as parameter. If you want to avoid to write delimiters you can also use the properties of a Zend_Mail_Storage_Folder instance:

// depending on your mail storage and its settings $rootFolder->Archive->2005
// is the same as:
//   /Archive/2005
//  Archive:2005
//  INBOX.Archive.2005
//  ...
$folder = $mail->getFolders()->Archive->2005;
echo 'Last folder was '
   . $mail->getSelectedFolder()
   . "new folder is $folder\n";
$mail->selectFolder($folder);

Advanced Use

Using NOOP

If you're using a remote storage and have some long tasks you might need to keep the connection alive via noop:

foreach ($mail as $message) {

    // do some calculations ...

    $mail->noop(); // keep alive

    // do something else ...

    $mail->noop(); // keep alive
}

Caching instances

Zend_Mail_Storage_Mbox, Zend_Mail_Storage_Folder_Mbox, Zend_Mail_Storage_Maildir and Zend_Mail_Storage_Folder_Maildir implement the magic methods __sleep() and __wakeup(), which means they are serializable. This avoids parsing the files or directory tree more than once. The disadvantage is that your Mbox or Maildir storage should not change. Some easy checks are done, like reparsing the current Mbox file if the modification time changes or reparsing the folder structure if a folder has vanished (which still results in an error, but you can search for an other folder afterwards). It's better if you have something like a signal file for changes and check it before using the cached instance.

// there's no specific cache handler/class used here,
// change the code to match your cache handler
$signal_file = '/home/test/.mail.last_change';
$mbox_basedir = '/home/test/mail/';
$cache_id = 'example mail cache ' . $mbox_basedir . $signal_file;

$cache = new Your_Cache_Class();
if (!$cache->isCached($cache_id) ||
    filemtime($signal_file) > $cache->getMTime($cache_id)) {
    $mail = new Zend_Mail_Storage_Folder_Pop3(array('dirname' =>
                                                        $mbox_basedir));
} else {
    $mail = $cache->get($cache_id);
}

// do stuff ...

$cache->set($cache_id, $mail);

Extending Protocol Classes

Remote storages use two classes: Zend_Mail_Storage_<Name> and Zend_Mail_Protocol_<Name>. The protocol class translates the protocol commands and responses from and to PHP, like methods for the commands or variables with different structures for data. The other/main class implements the common interface.

If you need additional protocol features you can extend the protocol class and use it in the constructor of the main class. As an example assume we need to knock different ports before we can connect to POP3.

class Example_Mail_Exception extends Zend_Mail_Exception
{
}

class Example_Mail_Protocol_Exception extends Zend_Mail_Protocol_Exception
{
}

class Example_Mail_Protocol_Pop3_Knock extends Zend_Mail_Protocol_Pop3
{
    private $host, $port;

    public function __construct($host, $port = null)
    {
        // no auto connect in this class
        $this->host = $host;
        $this->port = $port;
    }

    public function knock($port)
    {
        $sock = @fsockopen($this->host, $port);
        if ($sock) {
            fclose($sock);
        }
    }

    public function connect($host = null, $port = null, $ssl = false)
    {
        if ($host === null) {
            $host = $this->host;
        }
        if ($port === null) {
            $port = $this->port;
        }
        parent::connect($host, $port);
    }
}

class Example_Mail_Pop3_Knock extends Zend_Mail_Storage_Pop3
{
    public function __construct(array $params)
    {
        // ... check $params here! ...
        $protocol = new Example_Mail_Protocol_Pop3_Knock($params['host']);

        // do our "special" thing
        foreach ((array)$params['knock_ports'] as $port) {
            $protocol->knock($port);
        }

        // get to correct state
        $protocol->connect($params['host'], $params['port']);
        $protocol->login($params['user'], $params['password']);

        // initialize parent
        parent::__construct($protocol);
    }
}

$mail = new Example_Mail_Pop3_Knock(array('host'        => 'localhost',
                                          'user'        => 'test',
                                          'password'    => 'test',
                                          'knock_ports' =>
                                              array(1101, 1105, 1111)));

As you see we always assume we're connected, logged in and, if supported, a folder is selected in the constructor of the main class. Thus if you assign your own protocol class you always need to make sure that's done or the next method will fail if the server doesn't allow it in the current state.

Using Quota (since 1.5)

Zend_Mail_Storage_Writable_Maildir has support for Maildir++ quotas. It's disabled by default, but it's possible to use it manually, if the automatic checks are not desired (this means appendMessage(), removeMessage() and copyMessage() do no checks and do not add entry to the maildirsize file). If enabled an exception is thrown if you try to write to the maildir if it's already over quota.

There are three methods used for quotas: getQuota(), setQuota() and checkQuota():

$mail = new Zend_Mail_Storage_Writable_Maildir(array('dirname' =>
                                                   '/home/test/mail/'));
$mail->setQuota(true); // true to enable, false to disable
echo 'Quota check is now ', $mail->getQuota() ? 'enabled' : 'disabled', "\n";
// check quota can be used even if quota checks are disabled
echo 'You are ', $mail->checkQuota() ? 'over quota' : 'not over quota', "\n";

checkQuota() can also return a more detailed response:

$quota = $mail->checkQuota(true);
echo 'You are ', $quota['over_quota'] ? 'over quota' : 'not over quota', "\n";
echo 'You have ',
     $quota['count'],
     ' of ',
     $quota['quota']['count'],
     ' messages and use ';
echo $quota['size'], ' of ', $quota['quota']['size'], ' octets';

If you want to specify your own quota instead of using the one specified in the maildirsize file you can do with setQuota():

// message count and octet size supported, order does matter
$quota = $mail->setQuota(array('size' => 10000, 'count' => 100));

To add your own quota checks use single letters as key and they are preserved (but obviously not checked). It's also possible to extend Zend_Mail_Storage_Writable_Maildir to define your own quota only if the maildirsize file is missing (which can happen in Maildir++):

class Example_Mail_Storage_Maildir extends Zend_Mail_Storage_Writable_Maildir {
    // getQuota is called with $fromStorage = true by quota checks
    public function getQuota($fromStorage = false) {
        try {
            return parent::getQuota($fromStorage);
        } catch (Zend_Mail_Storage_Exception $e) {
            if (!$fromStorage) {
                // unknown error:
                throw $e;
            }
            // maildirsize file must be missing

            list($count, $size) = get_quota_from_somewhere_else();
            return array('count' => $count, 'size' => $size);
        }
    }
}
Previous Next
Introduction to Zend Framework
Overview
Installation
Zend_Acl
Introduction
Refining Access Controls
Advanced Usage
Zend_Amf
Introduction
Zend_Amf_Server
Zend_Auth
Introduction
Database Table Authentication
Digest Authentication
HTTP Authentication Adapter
LDAP Authentication
Open ID Authentication
Zend_Cache
Introduction
The theory of caching
Zend_Cache frontends
Zend_Cache backends
Zend_Captcha
Introduction
Captcha Operation
Captcha Adapters
Zend_Config
Introduction
Theory of Operation
Zend_Config_Ini
Zend_Config_Xml
Zend_Config_Writer
Zend_Config_Writer
Zend_Console_Getopt
Introduction to Getopt
Declaring Getopt Rules
Fetching Options and Arguments
Configuring Zend_Console_Getopt
Zend_Controller
Zend_Controller Quick Start
Zend_Controller Basics
The Front Controller
The Request Object
The Standard Router
The Dispatcher
Action Controllers
Action Helpers
The Response Object
Plugins
Using a Conventional Modular Directory Structure
MVC Exceptions
Migrating from Previous Versions
Zend_Currency
Introduction to Zend_Currency
How to work with currencies
Migrating from Previous Versions
Zend_Date
Introduction
Theory of Operation
Basic Methods
Zend_Date API Overview
Creation of dates
Constants for General Date Functions
Working examples
Zend_Db
Zend_Db_Adapter
Zend_Db_Statement
Zend_Db_Profiler
Zend_Db_Select
Zend_Db_Table
Zend_Db_Table_Row
Zend_Db_Table_Rowset
Zend_Db_Table Relationships
Zend_Debug
Dumping Variables
Zend_Dojo
Introduction
Zend_Dojo_Data: dojo.data Envelopes
Dojo View Helpers
Dojo Form Elements and Decorators
Zend_Dom
Introduction
Zend_Dom_Query
Zend_Exception
Using Exceptions
Zend_Feed
Introduction
Importing Feeds
Retrieving Feeds from Web Pages
Consuming an RSS Feed
Consuming an Atom Feed
Consuming a Single Atom Entry
Modifying Feed and Entry structures
Custom Feed and Entry Classes
Zend_File
Zend_File_Transfer
Validators for Zend_File_Transfer
Filters for Zend_File_Transfer
Migrating from previous versions
Zend_Filter
Introduction
Standard Filter Classes
Filter Chains
Writing Filters
Zend_Filter_Input
Zend_Filter_Inflector
Zend_Form
Zend_Form
Zend_Form Quick Start
Creating Form Elements Using Zend_Form_Element
Creating Forms Using Zend_Form
Creating Custom Form Markup Using Zend_Form_Decorator
Standard Form Elements Shipped With Zend Framework
Standard Form Decorators Shipped With Zend Framework
Internationalization of Zend_Form
Advanced Zend_Form Usage
Zend_Gdata
Introduction to Gdata
Authenticating with AuthSub
Using the Book Search Data API
Authenticating with ClientLogin
Using Google Calendar
Using Google Documents List Data API
Using Google Health
Using Google Spreadsheets
Using Google Apps Provisioning
Using Google Base
Using Picasa Web Albums
Using the YouTube Data API
Catching Gdata Exceptions
Zend_Http
Zend_Http_Client - Introduction
Zend_Http_Client - Advanced Usage
Zend_Http_Client - Connection Adapters
Zend_Http_Cookie and Zend_Http_CookieJar
Zend_Http_Response
Zend_InfoCard
Introduction
Zend_Json
Introduction
Basic Usage
JSON Objects
XML to JSON conversion
Zend_Json_Server - JSON-RPC server
Zend_Layout
Introduction
Zend_Layout Quick Start
Zend_Layout Configuration Options
Zend_Layout Advanced Usage
Zend_Ldap
Introduction
Zend_Loader
Loading Files and Classes Dynamically
Loading Plugins
Zend_Locale
Introduction
Using Zend_Locale
Normalization and Localization
Working with Dates and Times
Supported locales
Migrating from previous versions
Zend_Log
Overview
Writers
Formatters
Filters
Zend_Mail
Introduction
Sending via SMTP
Sending Multiple Mails per SMTP Connection
Using Different Transports
HTML E-Mail
Attachments
Adding Recipients
Controlling the MIME Boundary
Additional Headers
Character Sets
Encoding
SMTP Authentication
Securing SMTP Transport
Reading Mail Messages
Zend_Measure
Introduction
Creation of Measurements
Outputting measurements
Manipulating Measurements
Types of measurements
Zend_Memory
Overview
Memory Manager
Memory Objects
Zend_Mime
Zend_Mime
Zend_Mime_Message
Zend_Mime_Part
Zend_OpenId
Introduction
Zend_OpenId_Consumer Basics
Zend_OpenId_Provider
Zend_Paginator
Introduction
Usage
Configuration
Advanced usage
Zend_Pdf
Introduction.
Creating and loading PDF documents.
Save changes to the PDF document.
Document pages.
Drawing
Document Info and Metadata.
Zend_Pdf module usage example
Zend_ProgressBar
Zend_ProgressBar
Zend_Registry
Using the Registry
Zend_Rest
Introduction
Zend_Rest_Client
Zend_Rest_Server
Zend_Search_Lucene
Overview
Building Indexes
Searching an Index
Query Language
Query Construction API
Character Set
Extensibility
Interoperating with Java Lucene
Advanced
Best Practices
Zend_Server
Introduction
Zend_Server_Reflection
Zend_Service
Introduction
Zend_Service_Akismet
Zend_Service_Amazon
Zend_Service_Audioscrobbler
Zend_Service_Delicious
Zend_Service_Flickr
Zend_Service_Nirvanix
Zend_Service_ReCaptcha
Zend_Service_Simpy
Introduction
Zend_Service_StrikeIron
Zend_Service_StrikeIron: Bundled Services
Zend_Service_StrikeIron: Advanced Uses
Zend_Service_Technorati
Zend_Service_Twitter
Zend_Service_Yahoo
Zend_Session
Introduction
Basic Usage
Advanced Usage
Global Session Management
Zend_Session_SaveHandler_DbTable
Zend_Soap
Zend_Soap_Server
Zend_Soap_Client
WSDL Accessor
AutoDiscovery
Zend_Test
Introduction
Zend_Test_PHPUnit
Zend_Text
Zend_Text_Figlet
Zend_Text_Table
Zend_TimeSync
Introduction
Working with Zend_TimeSync
Zend_Translate
Introduction
Adapters for Zend_Translate
Using Translation Adapters
Migrating from previous versions
Zend_Uri
Zend_Uri
Zend_Validate
Introduction
Standard Validation Classes
Validator Chains
Writing Validators
Zend_Version
Reading the Zend Framework Version
Zend_View
Introduction
Controller Scripts
View Scripts
View Helpers
Zend_View_Abstract
Zend_Wildfire
Zend_Wildfire
Zend_XmlRpc
Introduction
Zend_XmlRpc_Client
Zend_XmlRpc_Server
Zend Framework Requirements
PHP Version
PHP Extensions
Zend Framework Components
Zend Framework Dependencies
Zend Framework Coding Standard for PHP
Overview
PHP File Formatting
Naming Conventions
Coding Style
Zend Framework Performance Guide
Introduction
Class Loading
Internationalization (i18n) and Localization (l10n)
View Rendering
Copyright Information