Exploring the PHP IMAP Library, Part 1

    Rakhitha Nimesh

    Some web applications might require features of an email client to be made available the users. In these situations, we can either write our own or customize opensource clients like SquirrelMail or Roundcube. Regardless of what you choose, knowledge of working with the PHP IMAP mail extension will be helpful.

    In this two-part series I’ll explain how to work with the IMAP extension. This is the first part which discusses the necessary functions for connecting to mail servers and reading messages. The second part will talk about actions for working with email, like deleting messages, downloading attachments, etc.

    To demonstrate functionality, I’ll use code samples that can be used to start scripting your own mail client. I’ll assume a single web script which uses these URL parameters to call the necessary functions:

    • func – the type of functionality required (ex: read email, view inbox, delete message)
    • folder – the name of the mailbox folder to connect to (ex: inbox, sent, spam)
    • uid – the unique ID of the email targeted

    The parameters can be retrieved using $_GET and a switch statement can be used to invoke the appropriate actions.

    $func = (!empty($_GET["func"])) ? $_GET["func"] : "view";
    $folder = (!empty($_GET["folder"])) ? $_GET["folder"] : "INBOX";
    $uid = (!empty($_GET["uid"])) ? $_GET["uid"] : 0;
    // connect to IMAP
    // ...
    switch ($func) {
        case "delete":
            deleteMail($imap, $folder, $uid);
        case "read":
            deleteMail($imap, $folder, $uid);
        case "view":
            viewMail($imap, $folder);

    Connecting to IMAP

    To establish a connection to the IMAP server, we use the imap_connect() function as shown here:

    $imap = imap_open($mailboxPath, $username, $password);

    The mailbox path, username, and password strings are required parameters to connect to the server. You can learn about the optional parameters in the manual.

    The mailbox path is a string that identifies server and port information in braces followed by the name of the desired mail folder. Here are a few strings for the inbox folder for popular mail providers:

    • Gmail {imap.gmail.com:993/imap/ssl}INBOX
    • Yahoo {imap.mail.yahoo.com:993/imap/ssl}INBOX
    • AOL {imap.aol.com:993/imap/ssl}INBOX

    Some servers do not have SSL enabled, in which case you would omit “SSL” from the string. Other servers might use self-signed certificates, in which you would include “novalidate-cert”.

    $imap = imap_open("{localhost:993/imap/ssl/novalidate-cert}", "username", "password");

    With an open connection to the mail server, now we can look at the functions used for the following activities:

    • Displaying the list of mailbox folders in your email account
    • Displaying the list of email messages in the folder
    • Viewing the email’s content

    Listing the Folders

    Inbox, sent, trash, and spam folders are seen in pretty much every email account, and users can often create custom folders as well. In order to view messages in these folders, we need to change our connection string. For example, I used “INBOX” in the path string earlier. If I wanted to connect to the spam folder, I might want to use something like “Spam” instead. But even though it might be listed as Spam in your email account when viewed through a mail client, the real folder name might be different behind the scenes. We can list all of the available folders in an account using imap_list().

    $folders = imap_list($imap, "{imap.gmail.com:993/imap/ssl}", "*");
    echo "<ul>";
    foreach ($folders as $folder) {
        $folder = str_replace("{imap.gmail.com:993/imap/ssl}", "", imap_utf7_decode($folder));
        echo '<li><a href="mail.php?folder=' . $folder . '&func=view">' . $folder . '</a></li>';
    echo "</ul>";

    We have to pass the connection handle obtained with imap_open() as the initial parameter to imap_list(). We also need to pass a bare path sting (without the folder, e.g. “INBOX”). The star as the third parameter requests all of the available folders.

    Listing Email Messages

    Each folder has a list of available email messages, so let’s see how we can generate a listing of the messages in our inbox.

    We need to first get the number of messages available using imap_num_msg(). Then we can use the imap_header() function to get the header information for each message.

    Let’s say if we wanted to the last 20 emails:

    $numMessages = imap_num_msg($imap);
    for ($i = $numMessages; $i > ($numMessages - 20); $i--) {
        $header = imap_header($imap, $i);
        $fromInfo = $header->from[0];
        $replyInfo = $header->reply_to[0];
        $details = array(
            "fromAddr" => (isset($fromInfo->mailbox) && isset($fromInfo->host))
                ? $fromInfo->mailbox . "@" . $fromInfo->host : "",
            "fromName" => (isset($fromInfo->personal))
                ? $fromInfo->personal : "",
            "replyAddr" => (isset($replyInfo->mailbox) && isset($replyInfo->host))
                ? $replyInfo->mailbox . "@" . $replyInfo->host : "",
            "replyName" => (isset($replyTo->personal))
                ? $replyto->personal : "",
            "subject" => (isset($header->subject))
                ? $header->subject : "",
            "udate" => (isset($header->udate))
                ? $header->udate : ""
        $uid = imap_uid($imap, $i);
        echo "<ul>";
        echo "<li><strong>From:</strong>" . $details["fromName"];
        echo " " . $details["fromAddr"] . "</li>";
        echo "<li><strong>Subject:</strong> " . $details["subject"] . "</li>";
        echo '<li><a href="mail.php?folder=' . $folder . '&uid=' . $uid . '&func=read">Read</a>';
        echo " | ";
        echo '<a href="mail.php?folder=' . $folder . '&uid=' . $uid . '&func=delete">Delete</a></li>';
        echo "</ul>";

    The $imap connection should be open to the desired folder. We can then traverse through the last 20 emails using the number of messages received by imap_num_msg(). The connection and email number are given to imap_header() to retrieve the header information, which can then be parsed for the interesting details like the sender’s email address and name, subject, etc.

    Note that the email number we get from using the total message count is not a unique ID for the message. If you have 100 emails in your inbox, then the last number will be 100, the previous will be 99, and so on. But its not unique. If you delete message number 100 and then receive a new message, it’s number will also will be 100.

    We have to get the unique ID for an email in order to proceed with other actions. Each email does have an unique ID, called UID, which we can get by providing the email number to the imap_uid() function. The UID is unique and will not change over time.

    Viewing Message Contents

    Reading email is not really as simple as the previous tasks, so I’m going to use the Receive Mail class developed by Mitul Koradia as a starting point to help make things easier. From the class I’ve extracted and adapted the following three functions for our example here:

    function getBody($uid, $imap) {
        $body = get_part($imap, $uid, "TEXT/HTML");
        // if HTML body is empty, try getting text body
        if ($body == "") {
            $body = get_part($imap, $uid, "TEXT/PLAIN");
        return $body;
    function get_part($imap, $uid, $mimetype, $structure = false, $partNumber = false) {
        if (!$structure) {
               $structure = imap_fetchstructure($imap, $uid, FT_UID);
        if ($structure) {
            if ($mimetype == get_mime_type($structure)) {
                if (!$partNumber) {
                    $partNumber = 1;
                $text = imap_fetchbody($imap, $uid, $partNumber, FT_UID);
                switch ($structure->encoding) {
                    case 3: return imap_base64($text);
                    case 4: return imap_qprint($text);
                    default: return $text;
            // multipart 
            if ($structure->type == 1) {
                foreach ($structure->parts as $index => $subStruct) {
                    $prefix = "";
                    if ($partNumber) {
                        $prefix = $partNumber . ".";
                    $data = get_part($imap, $uid, $mimetype, $subStruct, $prefix . ($index + 1));
                    if ($data) {
                        return $data;
        return false;
    function get_mime_type($structure) {
        $primaryMimetype = array("TEXT", "MULTIPART", "MESSAGE", "APPLICATION", "AUDIO", "IMAGE", "VIDEO", "OTHER");
        if ($structure->subtype) {
           return $primaryMimetype[(int)$structure->type] . "/" . $structure->subtype;
        return "TEXT/PLAIN";

    The getBody() function gets the email’s content by passing its UID and the IMAP connection. Inside the function, we call the get_part() function with the content type as TEXT/HTML. Plain text emails are much easier to read. So we first try to find the HTML content inside the email.

    Then we read the structure of the email using imap_fetchstructure() function. This function would have taken the email number by default, but we changed the library function to use the UID instead by passing the FT_UID constant.

    Then we get the mime type of the email message using the get_mime_type() function. There are eight mime types returned by this function as integers:

    • 0 – TEXT
    • 1 – MULTIPART
    • 2 – MESSAGE
    • 4 – AUDIO
    • 5 – IMAGE
    • 6 – VIDEO
    • 7 – OTHER

    We convert the returned integer into actual mime type string using the mime types array.

    Multipart messages can have a large number of subtypes, so we traverse recursively through all of the subtypes using the part numbers and retrieve the email content using imap_fetchBody() when the correct part is found using the mime type.

    Then, we use an appropriate decode function according to the encoding type of the message and return the content. A complete list of available encoding types is shown here:

    • 0 – 7BIT
    • 1 – 8BIT
    • 2 – BINARY
    • 3 – BASE64
    • 5 – OTHER


    We started this series by reviewing the basics of connecting to IMAP servers, then moved on to listing message inside available folders, and finished with reading an email message’s content. In the next part I’ll discuss the functions which can be used to implement additional functionality expected from an email client, like deleting messages and handling attachments.

    Image via Fotolia