IMAP library

A PHP 5.3+ library to read and process e-mails over IMAP.

Installation

The recommended way to install the IMAP library is through Composer:

$ composer require ddeboer/imap

This command requires you to have Composer installed globally, as explained in the installation chapter of the Composer documentation.

Requirements

PHP IMAP extension installed

Usage

Connect and authenticate

use Ddeboer\Imap\Server;

$server = new Server('imap.gmail.com');

// $connection is instance of \Ddeboer\Imap\Connection
$connection = $server->authenticate('my_username', 'my_password');

Mailboxes

Retrieve mailboxes (also known as mail folders) from mailserver and iterate over them:

$mailboxes = $connection->getMailboxes();

foreach ($mailboxes as $mailbox) {
    // $mailbox is instance of \Ddeboer\Imap\Mailbox
    printf('Mailbox %s has %s messages', $mailbox->getName(), $mailbox->count());
}

Delete a mailbox:

$mailbox->delete();

Messages

Retrieve messages (e-mails) from a mailbox and iterate over them:

$messages = $mailbox->getMessages();

foreach ($messages as $message) {
    // $message is instance of \Ddeboer\Imap\Message
}

Searching for Messages

use Ddeboer\Imap\SearchExpression;
use Ddeboer\Imap\Search\Email\To;
use Ddeboer\Imap\Search\Text\Body;

$search = new SearchExpression();
$search->addCondition(new To('[email protected]'))
    ->addCondition(new Body('contents'))
;

$messages = $mailbox->getMessages($search);

Message Properties and Operations

Get message number and unique message id in the form <...>:

$message->getNumber();
$message->getId();

Get other message properties:

$message->getSubject();
$message->getFrom();
$message->getTo();
$message->getDate();
$message->isAnswered();
$message->isDeleted();
$message->isDraft();
$message->isSeen();

Get message headers as a \Ddeboer\Imap\Message\Headers object:

$message->getHeaders();

Get message body as HTML or plain text:

$message->getBodyHtml();
$message->getBodyText();

Reading the message body marks the message as seen. If you want to keep the message unseen:

$message->keepUnseen()->getBodyHtml();

Move a message to another mailbox:

$mailbox = $connection->getMailbox('another-mailbox');
$message->move($mailbox);

Deleting messages:

$mailbox->getMessage(1)->delete();
$mailbox->getMessage(2)->delete();
$mailbox->expunge();

Message attachments

Get message attachments (both inline and attached) and iterate over them:

$attachments = $message->getAttachments();

foreach ($attachments as $attachment) {
    // $attachment is instance of \Ddeboer\Imap\Message\Attachment
}

Download a message attachment to a local file:

// getDecodedContent() decodes the attachments contents automatically:
\file_put_contents(
    '/my/local/dir/' . $attachment->getFilename(),
    $attachment->getDecodedContent()
);

Running the tests

This library is functionally tested on Travis CI against the Gmail IMAP server.

If you have your own Gmail (test) account, you can run the tests locally:

$ composer install --dev
$ export EMAIL_USERNAME="your_gmail_username"
$ export EMAIL_PASSWORD="your_gmail_password"
$ vendor/bin/phpunit