Smiling Souls

Steeped in the delicious tea like leaves of anthroposophy for the evolving soul.

Mail_IMAP - A Webmail API for PHP

Donate: If you have found Mail_IMAP to be helpful in your project please express your appreciation by donating to my efforts through my Amazon wishlist.

Mail_IMAP provides a flexible API for connecting to and retrieving mail from mailboxes using the IMAP, POP3 or NNTP mail protocols. Connection to a mailbox is acheived through the c-client extension to PHP. Meaning installation of the c-client extension is required to use Mail_IMAP.

Mail_IMAP can be used to retrieve the contents of a mailbox, whereas it may serve as the backend for a webmail application or mailing list manager, or whatever you can imagine that requires connectivity to a mailbox.

Since Mail_IMAP is an abstracted object, it allows for complete customization of the UI for any application.

By default Mail_IMAP parses and retrieves information about multipart messages in a threaded fashion similar to MS Outlook, e.g. only top level attachments are retrieved initially, then when message part id and message id are passed to Mail_IMAP, it retrieves attachments and information relevant to that message part. Mail_IMAP::getParts() can be supplied an argument to turn off threading, whereas all parts are retrieved at once.

Mail_IMAP also, by default retrieves the alternative message parts of multipart messages. This is most useful for debugging applications that send out multipart mailers where both a text/html and alterntaive text/plain part are included. This can also be turned off by supplying an additional argument to Mail_IMAP::getParts().

Mail_IMAP always searches for a text/html part to display as the primary part. This can be reversed so that it always looks for a text/plain part initially by supplying the necessary arguments to Mail_IMAP::getParts(), and Mail_IMAP::getBody().

The Return of Mail_IMAP as hMailIMAP

Rebuilt for PHP5

03/16/2013 - After an extremely long hiatus and some encouragement from Mail_IMAP users, I have resumed development of Mail_IMAP! I am currently preparing a brand new version with a revised API built for PHP5, and make to take advantage of what PHP5 has to offer. I will try to come up with a workable solution that keeps as much backward compatibility as possible, but I make no promises there.

The new project will be called hMailIMAP. It is built into my PHP framework Hot Toddy. Eventhough it will be built into Hot Toddy, I will release a stand-alone package, which will not require Hot Toddy.

The new package will NOT be posted to PEAR. It will also have no depenencies on PEAR packages. More news to come on that.

The Existing Mail_IMAPv2 Script

I have also posted some small revisions and bug fixes to the old Mail_IMAPv2, these revisions are NOT in the downloadable tgz package on PEAR and will NOT be posted to PEAR in the future. You can, however, download the new zip archive containing the revised Mail_IMAPv2 source code

Among the improvments: fixed decoding of message headers, including support for UTF-8. Added PHP5 support. Removed dependency on Net_URL and PEAR error stack.

Improvements to the old Mail_IMAPv2 script will terminate when hMailIMAP is completed and ready to go.

Contact Me with Bugs, Problem Email Messages

You are welcomed to contact me with bug reports (please be as detailed as possible). Please DO NOT contact me with support or how-to requests, I will not answer them, and do not have time to answer them. I have an extremely busy schedule, which is why I have been unable to develop Mail_IMAP for some eight years or so. You are also welcomed to email messages that Mail_IMAP is unable to parse the structure of, or properly decode to: Please include [Mail_IMAP] in the subject line.

Revised Licensing

This is changing, I'll post more about it when I have a product.


  • February 12, 2009 Eric Dorsey says:

    I am working with your Mail_IMAP and Mail_IMAPv2 PEAR modules and I cannot get them to work. I noticed the documentation is extremely old and I cannot for the life of me understand what the problem is. I have used all of your examples with both versions (IMAP.php and IMAPv2.php). When I use the 'IMAP.connection_wizard_example.php' with 'IMAP.php' it returns 'A suitable URI could not be detected.' when I use the same file with 'IMAPv2.php' it returns nothing. When I try the 'IMAP.index.php' with IMAP.php is returns 'Unable to build a connection.' and when I try it with IMAPv2.php it still fails and throws an Error having to with 'PEAR_Error'. I am running on an Ubuntu8.10 Server with apache2, php5 and pear1.1.1. It is a brand new install. Thanks for any information you can provide, Eric Dorsey
  • March 19, 2009 spaze says:

    So I use it like this (extra PEAR packages required, check the comments), the code is pretty self-explanatory, but in short, it displays total count of messages on IMAP server, reads the first, displays some headers and body and then deletes the message. $mbox = new Mail_IMAPv2(); $uri = 'imap://'; // Net_URL package is required when using connect() method $mbox->connect($uri); echo $mbox->messageCount(); $params['include_bodies'] = TRUE; $params['decode_bodies'] = TRUE; $number = 1; // message number one $raw_message = $mbox->getRawHeaders($number).$mbox->getRawMessage($number); $params['input'] = $raw_message; // Mail_mimeDecode package required for parsing messages $structure = Mail_mimeDecode::decode($params); echo $structure->headers['message-id']; echo $structure->headers['date']; echo $structure->body; $mbox->delete($number); // Only marks for deletion $mbox->expunge(); // actual deletion $mbox->close();
  • October 8, 2010 cambridge says:

    Hi Richard, tried to download the Mail_IMAPv2-0.2.0.tgz package. Get some error in downloading, and as I saved it lateron can't open the package. Karl
  • November 22, 2010 hm2k says:

    Would I be right in saying that this is just a wrapper class for php's imap_* functions?
  • May 3, 2012 Devendra Buddhikot says:

    I tried all sorts of combination but $msg->connect(); returns nothing, no error. If I remove URL.php then it does not connect that is sure means following code works if($msg->connect($con,$get_info=true)){ echo "Connected"; }else{ echo "Connection Unsuccessful"; } But my own code works well on basis of pure php_imap, in my code still there are bugs while seperating msg body parts, so I was trying IMAPv2. Can you give some more idea? I use Red Hat,Cpanel on shared server thanks
  • March 18, 2013 Richard York says:

    @hm2k - No. It would not be accurate to say that. If it were merely a wrapper for imap_* functions, you could just use those functions without this class and easily read mail on a mail server. Some methods provided are little more than wrappers, others provide significant functionality to help with reading messages and attachments. If c-client were easy to use, this project probably wouldn't exist. With regards to connecting to a sever, please read the documentation here at and the documentation for imap_connect at This object supports pretty much all that imap_open supports. Example URI connecting to gmail: imaps:// The current version requires the port to be specified, a newer version I'm working on determines default ports automatically based on the protocol. Regarding the .tgz package not opening, download the new zip archive I just posted instead:

There are no comments posted at this time.

Leave a Comment

Simple HTML is allowed: <code>, <b>, <i>, <u>, <var>, <strong>, <em>, <blockquote>, <ul>, <ol>, <li>, <p> (no attributes). All spacing and line breaks in your comment will be preserved.

* All comments are moderated and are subject to approval.
Your comment will appear once it has been approved.
Posting multiple times will not expedite the approval process.

Comments are closed at this time.

© Copyright 2015 Hot Toddy, All Rights Reserved.