- API documentation (updated nightly)
- IMP Source Code (Horde/Imap_Client was written for use with IMP, so the source code code provides a wealth of real-life usage examples)
Horde/Imap_Client does not
include() its own files, so
an autoloader must be registered that will load the Horde/Imap_Client
files from its PEAR directory.
package can be used to do this for you (or any other
Interaction with the mail server is handled through a
Horde_Imap_Client_Base object. The object class will be
one of the following:
The minimum necessary configuration needed for the Client constructor is
password. Although default
values can be used for the
secure options, it is generally a good idea to explicitly
set these values to aid in debugging connection issues.
Debug output of the server protocol communication can be obtained by
providing the 'debug' option. Acceptable values are any PHP supported
wrapper that can be opened via the
fopen() command. A plain
string is inerpreted as a filename, which is probably what most people
will want to use.
A sample constructor instantation (all further examples assume that this
command has been performed and a client object is present in the
The full list of options can be found in the API Documentation.
As noted in the constructor example, all errors encountered by the
library will cause exceptions of the
Horde_Imap_Client_Exception class (or a subclass of this
base class) to be thrown.
The exception message will contain a translated version of the
error message. If the "raw" English version of the message is needed -
i.e. for logging purposes - it can be found in the
Further server debug information might be found in the
Working with a Single Mailbox
The following examples assume that the user wants to work with the messages contained in their INBOX.
There is no need to provide commands to login and/or switch to a mailbox. These actions are handled on-demand by the library.
NOTE: All mailbox arguments to methods in Horde/Imap_Client take the UTF-8 version of the mailbox name. There is no need to worry about converting from/to the internal UTF7-IMAP charset used on IMAP servers.
Alternatively, you can use Horde_Imap_Client_Mailbox objects as the mailbox argument. This object can automatically convert the mailbox name if in UTF7-IMAP for you. Example:
search() command is used to list the messages in a mailbox. It only requires a mailbox name for basic
usage, and will return a list of unsorted UIDs in the mailbox.
To filter the list of messages returned by
Horde_Imap_Client_Search_Query object can be passed as the second parameter to
search(). If not present, all messages in the mailbox are returned.
The third argument to
search() allows additional search parameters to be specified, such as the prefered sort order.
In the examples above,
$uids is a
(all message ID lists are returned via this object in Horde/Imap_Client).
This object implements both the
Traversable classes, so it can be used directly in
foreach() commands. If a raw array
is needed, it can be obtained from the object via the