Download the PHP package directorytree/imapengine without Composer

Working with IMAP doesn't need to be hard.

ImapEngine provides a simple API for managing mailboxes -- without the PHP extension.

Index

• Requirements
• Installation
• Usage
  • Connecting
  • Retrieving Folders
  • Retrieving Messages
  • Interacting With Messages
  • Creating Draft Messages
  • Real Time Monitoring

Requirements

PHP >= 8.1

Installation

Installation is done through composer:

Usage

ImapEngine provides a simple, fluent API for working with IMAP mailboxes, messages, and attachments.

Connecting

To connect to a mailbox, create a new Mailbox instance with the configuration options:

To connect using an OAuth token, pass the token as the password, and set the authentication method to oauth:

To connect using plain (without encryption) or starttls, set the encryption option to starttls:

There are also many other configuration options available you may find useful:

Debugging

The debug configuration option controls logging behavior for the mailbox.

It accepts the following values:

Boolean:

• false – (Default) Disables debugging output
• true – Enables debugging using an EchoLogger, which outputs debug messages to the console

String: When set to a file path (e.g., '/path/to/log/file.log'), a FileLogger is instantiated to write debug messages to the specified file.

Class Name: If provided with a fully-qualified class name (and the class exists), an instance of that logger will be created and used.

The class must implement DirectoryTree\ImapEngine\Connection\Loggers\LoggerInterface.

Or, if you use Spatie Ray, you may use the built in RayLogger:

Retrieving Folders

Retrieving Messages

ImapEngine provides a fluent, chainable API for building advanced message search queries.

This allows you to combine various search criteria and options to retrieve exactly the messages you need:

[!important] It's paramount to understand that, without any query criteria specified, the get() method fetches all messages in the folder by default, and will be slow for large mailboxes. When working with large mailboxes, consider using since($date), and other criteria filters to limit the number of messages your IMAP server returns, along with pagination or chunking to avoid possible memory issues.

You may also consider restricting the parts of the message you fetch by omitting the use of withHeaders(), withFlags(), and withBody(). This will reduce the amount of data fetched from the server, and speed up your queries.

A typical approach when dealing with large mailboxes is to store all messages (either in a cache or DB) once, and then only fetch new messages since the last time the mailbox was checked.

Filtering By Criteria

The query builder supports many common IMAP search criteria. You may chain methods such as:

• all()
• new()
• old()
• seen()
• recent()
• unseen()
• deleted()
• on($date)
• uid($uid)
• answered()
• cc($value)
• to($value)
• bcc($value)
• undeleted()
• unflagged()
• body($value)
• from($email)
• since($date)
• text($value)
• unanswered()
• before($date)
• flagged($value)
• keyword($value)
• subject($value)
• header($header, $value)

For example, to retrieve messages from the last 7 days with a specific subject:

If a method doesn't exist for a specific search criteria, you may use the where() method to add custom criteria:

Fetching Additional Message Data

By default, ImapEngine search queries only fetches UIDs.

To fetch additional message data, you have to enable it explicitly.

Message Flags:

Use withFlags() to retrieve flags, or withoutFlags() to omit them.

Message Body:

Use withBody() to fetch the full body content, or withoutBody() to skip it.

[!important] The withBody() method fetches the full body content of the message, including attachments. Keep this in mind when fetching messages, as it can be slow for large messages.

For example, to fetch messages with both their bodies, headers, and flags:

Message Headers:

Use withHeaders() to include headers in the result, or withoutHeaders() to exclude them.

Message Pagination

You may paginate messages using the paginate() method. This method accepts the number of messages to display per page:

[!important] IMAP does not support native pagination, as you would typically expect, like a SQL database. Instead, ImapEngine retrieves all UID's from the selected folder, takes the slice of the UID's that corresponds to the current page, and fetches the requested email message parts specifically for those UID's.

Message Chunking

If you need to process a large number of messages without loading them all at once, you may use the chunk() method:

You may also use the each() method to iterate over messages in every chunk:

Finding a Specific Message

You may retrieve a single message by its unique identifier using the find() method.

The method accepts an ID and an ImapFetchIdentifier (an enum) that specifies whether the ID is a UID or a message sequence number.

For example, to find a message by UID:

Or by message sequence number:

You may also use the findOrFail() method to throw an exception if the message is not found:

Interacting With Messages

Once you retrieve messages from a folder using methods like $inbox->messages()->get(), you'll receive instances of the DirectoryTree\ImapEngine\Message class.

This class offers a rich set of helper methods for interacting with individual emails, making it easy to inspect, modify, and manipulate messages.

Retrieving Message Information

The Message class provides several methods to access basic properties:

UID and Flags

• $message->uid(): Returns the unique identifier (UID) of the message.
• $message->flags(): Returns an array of flags currently set on the message.

Headers and Contents

• $message->head(): Returns the raw message header.
• $message->body(): Returns the raw message body.
• $message->header($name): Returns a specific header.
• $message->headers(): Returns an array of all headers.
• $message->hasHead() / hasBody(): Determine whether the message has headers or body.

Metadata

• $message->subject(): Returns the subject of the message.
• $message->date(): Returns the message’s date as a Carbon instance (if available).
• $message->messageId(): Retrieves the Message-ID header (globally unique identifier for the message).

Additional Message Details

In addition to the methods shown above, the Message class provides several additional helpers:

Flag Checking

Quickly check whether a message has a specific flag:

• $message->isSeen(): Determine if the message marked as \Seen
• $message->isDraft(): Determine if the message marked as \Draft
• $message->isRecent(): Determine if the message marked as \Recent
• $message->isFlagged(): Determine if the message marked as \Flagged
• $message->isDeleted(): Determine if the message marked as \Deleted
• $message->isAnswered(): Determine if the message marked as \Answered

Address Handling

To conveniently work with email addresses, the Message class includes methods that return addresses as instances of the DirectoryTree\ImapEngine\Address class:

• from(): The sender’s address.
• sender(): The actual sender (if different from "from").
• replyTo(): The reply-to address.
• inReplyTo(): The In-Reply-To address.
• to(): An array of recipient addresses.
• cc(): An array of CC addresses.
• bcc(): An array of BCC addresses.

Content Retrieval

For accessing the message content in different formats:

• html(): Returns the HTML version of the message (if available).
• text(): Returns the plain text version of the message (if available).

Attachment Handling

Messages that include attachments can be inspected with:

• attachments(): Returns an array of Attachment objects.
• hasAttachments(): Checks if the message contains any attachments.
• attachmentCount(): Returns the number of attachments in the message.

Flag Operations

The class also provides methods to modify message flags, which help you manage the state of a message:

Marking as Seen/Unseen

• markSeen(): Marks the message as read.
• unmarkSeen(): Marks the message as unread.
• Aliases: markRead() and markUnread().

Other Flags

• markDraft() / unmarkDraft()
• markRecent() / unmarkRecent()
• markFlagged() / unmarkFlagged()
• markDeleted() / unmarkDeleted()
• markAnswered() / unmarkAnswered()

All these methods work by invoking the underlying IMAP STORE command (with the appropriate flag and operation).

Message Manipulation

Beyond just flagging, you may move or copy messages between folders, as well as delete them:

• restore(): Restores the message from the trash.
• copy(string $folder): Copies the message to the specified folder.
• move(string $folder, bool $expunge = false): Moves the message to the specified folder.
• delete(bool $expunge = false): Marks the message as deleted and, if desired, expunges it from the folder.

Example: Interacting with a Retrieved Message

Creating Draft Messages

ImapEngine allows you to create draft messages and save them to the server for later editing or sending.

To create a new draft message, you may use the append() method on a folder instance:

Draft messages also accept attachments:

`

Idling on Folders (Real Time Monitoring)

ImapEngine supports real-time monitoring of folders via the IMAP IDLE command.

This lets you listen for new messages as they arrive without polling repeatedly.

[!important] The idle() method is fully blocking (as in, it enters an infinite loop), so consider running it in a background process or a worker when used in a web application.

By default, messages received in idle will not be fetched with all of their content (flags, headers, and body with attachments).

If you need to fetch the message content, you may set the query to fetch the desired content using the second argument of the idle() method:

If your IMAP server requires a specific timeout, you may specify one in the third parameter (or using the parameter name):