README

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

Installation

Make sure the PHP IMAP extension is installed. For instance on Ubuntu:

# apt-get install php7.0-imap

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

$ composer require sgoranov/imap-client

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

Usage

Connect and Authenticate

use sgoranov\ImapClient\Server;

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

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

Options

You can specify port, flags and parameters to the server:

$server = new Server(
    $hostname, // required
    $port,     // defaults to 993
    $flags,    // defaults to '/imap/ssl/validate-cert'
    $parameters
);

Mailboxes

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

$mailboxes = $connection->getMailboxes();

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

Or retrieve a specific mailbox:

$mailbox = $connection->getMailbox('INBOX');

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 \sgoranov\ImapClient\Message
}

Searching for Messages

use sgoranov\ImapClient\SearchExpression;
use sgoranov\ImapClient\Search\Email\To;
use sgoranov\ImapClient\Search\Text\Body;

$search = new SearchExpression();
$search->addCondition(new To('me@here.com'))
    ->addCondition(new Body('contents'))
;

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

Sorting Messages

Search and then sort the result:

use sgoranov\ImapClient\SearchExpression;
use sgoranov\ImapClient\Search\Email\To;
use sgoranov\ImapClient\Search\Text\Body;
use sgoranov\ImapClient\Sort\Size;

$search = new SearchExpression();
$search->addCondition(new To('me@here.com'))
    ->addCondition(new Body('contents'))
;

$messages = $mailbox->getMessages($search, new Size('DESC')); // sort by size

Sort all the messages in the mailbox:

use sgoranov\ImapClient\Sort\Date;

$messages = $mailbox->getMessages(null, new Date()); // sort by date ASC

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 \sgoranov\ImapClient\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 \sgoranov\ImapClient\Message\Attachment
}

Download a message attachment to a local file:

// getDecodedContent() decodes the attachment’s 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 IMAP (test) account, you can run the tests locally by providing your IMAP (e.g., Gmail) credentials:

$ composer install
$ export EMAIL_USERNAME="your_username" 
$ export EMAIL_PASSWORD="your_password" 
$ vendor/bin/phpunit

You can also set an EMAIL_SERVER variable, which defaults to imap.gmail.com:

$ export EMAIL_SERVER="imap.you.com"

sgoranov / imap-client

Maintainers

Details