Download the PHP package bjc/roundcube-imap without Composer

roundcube-imap

A PHP IMAP library to read and process e-mails over IMAP protocol. It works independently of PHP IMAP extension and supports newer additions to the IMAP protocol like CONDSTORE and QRESYNC which is not supported by the standard PHP IMAP extension.

The code to communicate over the IMAP protocol was extracted from the roundcubemail project (https://roundcube.net/). The interface to access the classes/methods was inspired by ddeboer/imap, another object-oriented IMAP library.

Installation

The recommended way to install this package is through Composer. Please note that this package is only available in Composer 2. If you still run Composer 1 you will have to update to Composer 2.

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

Usage

Connect and Authenticate

Mailboxes

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

Or retrieve a specific mailbox:

Create a mailbox:

Rename a mailbox:

Clear a mailbox (remove all messages):

Delete a mailbox:

Status of a mailbox

To retrieve the status of a mailbox run:

Messages

For retrieving messages it is important to understand the concept of UIDs and uidvalidity. UID is a numeric unique identifier of a message WITHIN the mailbox (not to confuse with the message ID which is an alphanumeric identifier that identifies a message "world wide"). When a new message is being put into a mailbox, it will always get a higher UID than all the messages before. As a result, when your application knows which UID it fetched last, it can easily ask the IMAP server to just send the messages that were newly received. This concept works as long as the UIDs of messages don't change and new messages always get higher UIDs than existing ones. There are scenarios were this is not the case and this is the reason for uidvalidity. Uidvalidity is a parameter maintained by the IMAP server for each mailbox. As long as this parameter stays the same, the UIDs assigned to the existing mails did not change and new messages always received higher UIDs than the ones that existed.

Therefore your application has to store two parameters for each mailbox:

• uidvalidity
• last fetched uid

If you check the mailbox, check first whether uidvalidity changed compared to which uidvalidity you have stored in your application for the respective mailbox. If it changed, delete the stored email data in your application (for this mailbox) and fetch everything again as UIDs for messages could have changed. If uidvalidity stayed the same, then just fetch the new messages higher than your last fetched uid.

To get the current uidvalidity value run:

Get messages higher than a certain UID (normally the one you fetched at last)

If you plan to analyse the bodystructure of all e-mails you already can request the bodystructure to be fetched (and stored in the message object) for all messages in the set by setting the second variable of the function call to true:

Anyway the message object will take care of fetching the bodystructure later if needed but not yet stored in the message object.

Note that the above command will fetch a standard set of headers of the selected messages. You can add additional headers you would like to fetch by adding an array of strings as a third variable to the function call:

Get messages of a certain message set (e.g. if you want to fetch all messages again because uidvalidity changed)

If you plan to analyse the bodystructure of all e-mails you already can request the bodystructure to be fetched (and stored in the message object) for all messages in the set by setting the second variable of the function call to true:

Anyway the message object will take care of fetching the bodystructure later if needed but not yet stored in the message object.

Note that the above command will fetch a standard set of headers of the selected messages. You can add additional headers you would like to fetch by adding an array of strings as a third variable to the function call:

If you know the UID of the message you want to retrieve

If you plan to analyse the bodystructure of the e-mail you already can request the bodystructure to be fetched (and stored in the message object) by setting the second variable of the function call to true:

Anyway the message object will take care of fetching the bodystructure later if needed but not yet stored in the message object.

Note that the above command will fetch a standard set of headers of the selected message. You can add additional headers you would like to fetch by adding an array of strings as a third variable to the function call:

Checking whether your server is capable of synchronization (i.e. has CONDSTORE and QRESYNC extension implemented)

Synchronization will help you to keep your applications data up to date with what is going on on the IMAP server. First you have to check if your server supports it:

If your server supports CONDSTORE and QRESYNC extension then you can synchronize your data

'Synchronize' means you can get just the messages that changed, came in new or got deleted since your last fetch. For this you have to store another parameter (beside uidvalidity) for each mailbox in your persistence (e.g. your database): Highestmodsequence

Highestmodsequence is a numeric value that increases each time something changed in the mailbox. The IMAP server keeps track of which changes happened at which modsequence and therefore can tell which changes it needs to tell you when you ask for changes since a certain modsequence.

To get the current highestmodseq for a mailbox (in order to store it in your application until your next fetch) run:

To get the changes since last synchronization run:

If you plan to analyse the bodystructure of the e-mails you already can request the bodystructure to be fetched (and stored in the message object) by setting the third variable of the function call to true:

Anyway the message object will take care of fetching the bodystructure later if needed but not yet stored in the message object.

Note that the above command will fetch a standard set of headers of the selected message. You can add additional headers you would like to fetch by adding an array of strings as a fourth variable to the function call:

If your server does not support CONDSTORE and QRESYNC

If your server does not support CONDSTORE and QRESYNC then you have to fetch at least the flags and UIDs of all messages in the mailbox (from time to time or always) to keep track of flag changes and deleted messages. To keep traffic as low as possible you should run two queries, one for new messages where you fetch all the headers you need and one query where you will only ask for uid, message-id and flags of the old messages. Use your stored last fetched uid value to distinct between new and old messages (again as long as uidvalidity did not change).

Note that the $message object and it's child object $messageheaders will not have the standard set of headers. By default only $uid, $id and the flags will be available. If you need still more headers you can add them by giving a second argument to the function call:

After the update query, run the query for new messages:

Messageheaders

To retrieve headers from the message object, you have the following options:

Email address object

For the emailaddress object you can do the following:

Message Parts

Attachments and inline objects

Fetching (and storing) all attachments in your application no matter if you need them or not is costly. Therefore you might want to save the $filename and $mime_id in your application and only fetch the data from the IMAP server when the user requests the data of an attachment. You can fetch an attachment having the $mime_id (also called part number) from the message object later:

Inline images use the same class (\bjc\roundcubeimap\attachment) therefore it has the same available methods:

Retrieve full Mime message

Sometimes you need to get the full mime message to deal with it further.

Flag messages

You can set and clear message flags within the mailbox object or within the message object:

Copy, move (within account), delete messages

You can copy, move and delete messages within the mailbox object or within the message object:

Count messages

You can count all messages, recent messages or unseen messages in a mailbox object:

Append messages to mailbox

In case you have sent a message you maybe want to save the sent message to a folder. This package is only for managing IMAP mailboxes, not for communicating with an SMTP server to send messages.

So let's assume you have sent an email with another library, e.g. PHPMailer:

Move messages into other account

If you would like to move messages from one account to another, you can use the fetchMimemessage method to retrieve the message and appendMessage method together.

To Do:

• Create class \bjc\roundcubeimap\embeddedmessage to give a possibility to deal with embedded messages