PHPackages                             craigh/imap-mail-manager - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. craigh/imap-mail-manager

ActiveLibrary

craigh/imap-mail-manager
========================

Wrapper for PHP imap

v1.0-beta(10y ago)5301MITPHP

Since Mar 20Pushed 10y ago1 watchersCompare

[ Source](https://github.com/craigh411/ImapMailManager)[ Packagist](https://packagist.org/packages/craigh/imap-mail-manager)[ RSS](/packages/craigh-imap-mail-manager/feed)WikiDiscussions master Synced 2mo ago

READMEChangelog (1)Dependencies (4)Versions (2)Used By (0)

ImapMailManager
===============

[](#imapmailmanager)

ImapMailManager provides convenient OOP classes for performing common tasks when for managing incoming email via imap in php.

**Note:** This package is now under a beta realease. A fully stable realease is expected in the coming weeks.

Features
--------

[](#features)

- Provides convenient methods for searching imap mailboxes
- Automatic detection, decoding and encoding of email messages and attachments.
- Encodes messages in UTF-8 for optimal display.
- Provides simple methods for downloading attachments and embedded images.
- Configurable via a config file, rather than having to hardcode username and password information.
- Converts php's native imap responses in to simple value objects for easy access.

Getting Started
---------------

[](#getting-started)

ImapMailManager provides two main service classes for performing tasks on the Mailbox (searching the mailbox for messages, folders etc) and on the Message itself (downloading attachments). Convenient factories have been provided to help with the creation of required objects.

### Config

[](#config)

The simplest way to connect to your mailbox is by providing the settings via a config file.

```
return [
    'server' => 'imap.example.com',
    'username' => 'USERNAME',
    'password' => 'PASSWORD',
    'port' => 993,
    'ssl' => true,
    'validate_cert' => true,
];

```

#### Aliases

[](#aliases)

Aliases provide a convenient way to reference mailbox folders, for example if you use different `config` files to connect to multiple mailboxes you can provide folder aliases in the config itself. This means you can avoid hardcoding folder names, and using if statements to detect which mailbox you are connected to to get the correct folder name. To create an alias, you simply need to add an `aliases` array to your `config` file, these aliases can then be passed to methods that request a folder name, e.g. `moveToFolder('spam')`:

```
return [
    'server' => 'imap.example.com',
    'username' => 'USERNAME',
    'password' => 'PASSWORD',
    'port' => 993,
    'ssl' => true,
    'validate_cert' => true,
    'aliases' => [
      'trash' => 'INBOX.Trash',
      'spam' => 'INBOX.Spam'
    ]
];

```

It's a good idea to add the `trash` alias, as this is the alias that is automatically used by the `moveToTrash()` and `emptyTrash()` methods. Otherwise you will need to pass the folder name in as a parameter: e.g. `moveToTrash('INBOX.Trash')`

### Generating the config file

[](#generating-the-config-file)

`ImapMailManager` provides a config generator called `createImapConfig.php` which can be run from composers `vendor/bin` folder, which will create 'imap\_config/config.php' in the folder the script is run from.

Alternatively, you can simply copy and paste the code from config.php to your own config file.

By default `ImapMailManager` looks for your config file in `imap_config/config.php`, you can change this by passing the config location directly in to the relevant class constructors or factory methods. (see docs)

### Listing Emails

[](#listing-emails)

This following example uses the provided factories to build a collection of messages from your inbox. See *Creating Imap using constructors and no config* below to see how you may use constructors to acheive the same results.

```
// Creates the relevant imap classes to be passed to a service
$imap = ImapFactory::create('INBOX');
// Create a new service
$mailboxService = new ImapMailboxService($imap);

// Get all messages in the folder (this returns an array of message numbers)
$all = $mailboxService->getAllMessages();

// Create a collection of Message objects
$messages = ImapMessagesCollectionFactory::create($all);
```

Now you can simply loop through the messages to display a list of message subjects:

```
if(count($messages)){
    foreach($messages as $message){
      echo $message->getSubject().'';
    }
}
```

### Displaying a message

[](#displaying-a-message)

```
$messageNum = $_REQUEST['messageNum'];

// Creates the relevant imap classes to be passed to a service
$imap = ImapFactory::create('INBOX');

// Get the current message
$message = ImapMessageFactory::create($messageNum, $imap);
// Create a new service
$messageService = new ImapMessageService($message, $imap);

echo $message->getSubject().'';
echo $message->getHtmlBody();
```

You should look at the docs for the `ImapMessage` class to see what methods are availble for retrieving message information. You can also look at `examples\showMessage.php` which provides a more complete example of displaying a message.

### Handling Attachments

[](#handling-attachments)

`ImapMailManager` takes all the pain out of downloading attachments by extracting the attachment information, decoding and saving the attachment to the relevant folder.

#### Downloading all attachments

[](#downloading-all-attachments)

To download all attachments for a message you simply need the following:

```
$messageNum = $_REQUEST['messageNum'];

// Creates the relevant imap classes to be passed to a service
$imap = ImapFactory::create('INBOX');

// Get the current message
$message = ImapMessageFactory::create($messageNum, $imap);
$message->downloadAttachments('path/to/download/to');
```

#### Downloading A Single Attachment

[](#downloading-a-single-attachment)

You will often want to download a single attachment, in order to do this `ImapMailManager` provides a few convenience methods: `downloadAttachmentByFilename()`, `downloadAttachmentByPart()` and `downloadAttachment()`. You can use the `getAttachments()` method on the returned message to retrieve a collection of `Attachment` objects which provide `getFilename()` and `getPart()` methods:

**Downloading attachment by filename**

```
// Filename passed from the previous page, this can be retrieved using the `getFilename()` method on the Attachment object.
$filename = $_REQUEST['filename'];
// The folder for the message, this can be retreived using `getFolder()` on the Mailbox object (see `examples\exmple.php`)
$folder = $_REQUEST['folder'];

// Creates the relevant imap classes to be passed to a service
$imap = ImapFactory::create($folder);

// Get the current message
$message = ImapMessageFactory::create($messageNum, $imap);
// Create a new service
$messageService = new ImapMessageService($message, $imap);

$messageService->downloadAttachmentByFilename($filename, 'attachment/download/path');
```

### Downloading Embedded images

[](#downloading-embedded-images)

Some E-mails have images directly embedded in them, by default `ImapMailManager` will not download these images, so they will not be displayed. If you want to download and display embedded images you simply need to call the `downloadEmbeddedImages()` method, when displaying the message:

```
$messageNum = $_REQUEST['messageNum'];
// The folder for the message, this can be retreived using `getFolder()` on the Mailbox object (see `examples\exmple.php`)
$folder = $_REQUEST['folder'];
// Creates the relevant imap classes to be passed to a service
$imap = ImapFactory::create(folder);

// Get the current message
$message = ImapMessageFactory::create($messageNum, $imap);
// Create a new service
$messageService = new ImapMessageService($message, $imap);
// Download any embedded images, without this embedded images will not display.
$messageService->downloadEmbeddedImages('path/to/download/to');

// Display Message with embedded images
$message->getHtmlBody()
```

In order to avoid overwriting images embedded images are saved to `your/path/folderName/messageNumber`.

**Note:** Embedded images are only downloaded if they do not exist in the download location, they will not be downloaded each time the message is opened.

### Creating Imap using constructors and no config

[](#creating-imap-using-constructors-and-no-config)

While the factory methods provide a convenient way to create an the Imap class that is passed in to a service or factory, it hides a lot of what is going on. In order to better understand how ImapMailManager works, the following shows how you would directly construct the `MailboxService` object:

```
// We don't have a config file, so lets create the mailbox directly
$mailbox = new Mailbox('imap.example.com', 'username', 'password', 'INBOX');
// Now lets connect to the mailbox
$imapConnection = new ImapConnection($mailbox);
// Now create an ImapHandler object, which is used to perform various tasks on the mailbox
$imap = new ImapHandler($imapConnection);
// Finally create the service
$mailboxService = new MailboxService($imap);
```

**Note:** Creating a Message object directly is quite involved, so the Factories should still be used to create Message objects and collections.

Running the Examples
--------------------

[](#running-the-examples)

The examples require you to provide your own config file in `examples/imap_config/config.php`, you can do this by using the generator found in `vendor\bin` or simply creating one manually, you can find the basic config file in `config.php` in the root of this project.

You then need to change the settings in your `config.php` file to match your email account and you should then be able to run the examples.

Documentation
-------------

[](#documentation)

There's a lot more that can be done with `ImapMailManager` than just these examples. You can find the full list of methods and descriptions in the `docs` folder, provided as HTML. I hope to have these online soon.

Notes
-----

[](#notes)

#### A Note About Collections

[](#a-note-about-collections)

`ImapMailMainager` returns collections as Collection objects. You can treat these exactly as you would a normal php array, so you can still use `count` and `foreach` on them as well as access them via their array index `MessageCollection[0]`

#### A Note on JSON Encoding

[](#a-note-on-json-encoding)

All value objects and collections are designed to be easily json encodable (and provide a `toJson()` method), however, you may find that some parts of an object are not included when json encoded, these are generally the raw responses from php's imap functions which could cause `json_encode()` to fail if they are not `UTF-8` encoded.

#### A Note on echoing

[](#a-note-on-echoing)

All value objects and collections have a `__toString()` method that will automatically display their json representations if echoed or printed to the screen, so you don't need to `var_dump()`. You should be aware that json is not the actual returned value when creating an object, but it's string represntation, so all methods can be used on the object as normal.

#### A Note About Cloning

[](#a-note-about-cloning)

Classes that contain properties that are objects are deep cloned, so those object properties are thmeselves clones.

###  Health Score

25

—

LowBetter than 37% of packages

Maintenance20

Infrequent updates — may be unmaintained

Popularity13

Limited adoption so far

Community8

Small or concentrated contributor base

Maturity49

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Unknown

Total

1

Last Release

3704d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/791b31f6b625d43874f70831846b002b7bb46dc911e38b02250e7aaab6596716?d=identicon)[craigh411](/maintainers/craigh411)

---

Top Contributors

[![craigh411](https://avatars.githubusercontent.com/u/13747552?v=4)](https://github.com/craigh411 "craigh411 (45 commits)")

###  Code Quality

TestsPHPUnit

### Embed Badge

![Health badge](/badges/craigh-imap-mail-manager/health.svg)

```
[![Health](https://phpackages.com/badges/craigh-imap-mail-manager/health.svg)](https://phpackages.com/packages/craigh-imap-mail-manager)
```

###  Alternatives

[tymon/jwt-auth

JSON Web Token Authentication for Laravel and Lumen

11.5k49.1M350](/packages/tymon-jwt-auth)[bagisto/bagisto

Bagisto Laravel E-Commerce

26.2k161.6k7](/packages/bagisto-bagisto)[spatie/laravel-sitemap

Create and generate sitemaps with ease

2.6k14.6M107](/packages/spatie-laravel-sitemap)[statamic/cms

The Statamic CMS Core Package

4.8k3.2M720](/packages/statamic-cms)[team-reflex/discord-php

An unofficial API to interact with the voice and text service Discord.

1.1k379.4k24](/packages/team-reflex-discord-php)[temporal/sdk

Temporal SDK

4002.2M18](/packages/temporal-sdk)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)