Laravel IMAP is an easy way to integrate the native php imap library into your Laravel app.

• Installation
• Configuration
• Usage
• Documentation
  • Client::class
  • Message::class
  • Folder::class
  • Attachment::class
  • MessageCollection::class
  • AttachmentCollection::class
  • FolderCollection::class
• Known issues
• Milestones & upcoming features
• Security
• Credits
• Supporters
• License

1. Install the php-imap library if it isn't already installed:

sudo apt-get install php*-imap && sudo apache2ctl graceful

You might also want to check phpinfo() if the extension is enabled.

2. Now install the Laravel IMAP package by running the following command:

composer require webklex/laravel-imap

3. If you're running Laravel >= 5.5, package discovery will configure the service provider and Client alias out of the box.

   Otherwise, for Laravel <= 5.4, edit your config/app.php file and:

   • add the following to the providers array:

     Webklex\IMAP\Providers\LaravelServiceProvider::class,

   • add the following to the aliases array:

     'Client' => Webklex\IMAP\Facades\Client::class,

4. Run the command below to publish the package config file config/imap.php:

php artisan vendor:publish --provider="Webklex\IMAP\Providers\LaravelServiceProvider"

If you are planning to use a single account, you might want to add the following to your .env file.

IMAP_HOST=somehost.com
IMAP_PORT=993
IMAP_ENCRYPTION=ssl
IMAP_VALIDATE_CERT=true
[email protected]
IMAP_PASSWORD=secret
IMAP_DEFAULT_ACCOUNT=default

The following encryption methods are supported:

• false — Disable encryption
• ssl — Use SSL
• tls — Use TLS

Detailed config/imap.php configuration:

• default — used default account
• accounts — all available accounts
  • default — default account identifier
    • host — imap host
    • port — imap port
    • encryption — desired encryption method
    • validate_cert — decide weather you want to verify the certificate or not
    • username — imap account username
    • password — imap account password
• options — additional fetch options
  • delimiter — you can use any supported char such as ".", "/", etc
  • fetch — FT_UID (message marked as read by fetching the message) or FT_PEEK (fetch the message without setting the "read" flag)
  • fetch_body — If set to false all messages will be fetched without the body and any potential attachments
  • fetch_attachment — If set to false all messages will be fetched without any attachments
  • open — special configuration for imap_open()
    • DISABLE_AUTHENTICATOR — Disable authentication properties.

This is a basic example, which will echo out all Mails within all imap folders and will move every message into INBOX.read. Please be aware that this should not ben tested in real live but it gives an impression on how things work.

use Webklex\IMAP\Client;

$oClient = new Client([
    'host'          => 'somehost.com',
    'port'          => 993,
    'encryption'    => 'ssl',
    'validate_cert' => true,
    'username'      => 'username',
    'password'      => 'password',
]);

//Connect to the IMAP Server
$oClient->connect();

//Get all Mailboxes
/** @var \Webklex\IMAP\Support\FolderCollection $aFolder */
$aFolder = $oClient->getFolders();

//Loop through every Mailbox
/** @var \Webklex\IMAP\Folder $oFolder */
foreach($aFolder as $oFolder){

    //Get all Messages of the current Mailbox $oFolder
    /** @var \Webklex\IMAP\Support\MessageCollection $aMessage */
    $aMessage = $oFolder->getMessages();
    
    /** @var \Webklex\IMAP\Message $oMessage */
    foreach($aMessage as $oMessage){
        echo $oMessage->subject.'<br />';
        echo 'Attachments: '.$oMessage->getAttachments()->count().'<br />';
        echo $oMessage->getHTMLBody(true);
        
        //Move the current Message to 'INBOX.read'
        if($oMessage->moveToFolder('INBOX.read') == true){
            echo 'Message has ben moved';
        }else{
            echo 'Message could not be moved';
        }
    }
}

If you use the Facade \Webklex\IMAP\Facades\Client::class please select an account first:

use Webklex\IMAP\Facades\Client;

$oClient = Client::account('default');
$oClient->connect();

There is an experimental function available to get a Folder instance by name. For an easier access please take a look at the new config option imap.options.delimiter however the getFolder method takes three options: the required (string) $folder_name and two optional variables. An integer $attributes which seems to be sometimes 32 or 64 (I honestly have no clue what this number does, so feel free to enlighten me and anyone else) and a delimiter which if it isn't set will use the default option configured inside the config/imap.php file.

/** @var \Webklex\IMAP\Client $oClient */

/** @var \Webklex\IMAP\Folder $oFolder */
$oFolder = $oClient->getFolder('INBOX.name');

Search for specific emails:

/** @var \Webklex\IMAP\Folder $oFolder */

//Get all messages since march 15 2018
/** @var \Webklex\IMAP\Support\MessageCollection $aMessage */
$aMessage = $oFolder->searchMessages([['SINCE', Carbon::parse('15.03.2018')]]);

//Get all messages containing "hello world"
/** @var \Webklex\IMAP\Support\MessageCollection $aMessage */
$aMessage = $oFolder->searchMessages([['TEXT', 'hello world']]);

//Get all unseen messages containing "hello world"
/** @var \Webklex\IMAP\Support\MessageCollection $aMessage */
$aMessage = $oFolder->searchMessages([['UNSEEN'], ['TEXT', 'hello world']]);

Available search criteria:

• ALL — return all messages matching the rest of the criteria
• ANSWERED — match messages with the \ANSWERED flag set
• BCC "string" — match messages with "string" in the Bcc: field
• BEFORE "date" — match messages with Date: before "date"
• BODY "string" — match messages with "string" in the body of the message
• CC "string" — match messages with "string" in the Cc: field
• DELETED — match deleted messages
• FLAGGED — match messages with the \FLAGGED (sometimes referred to as Important or Urgent) flag set
• FROM "string" — match messages with "string" in the From: field
• KEYWORD "string" — match messages with "string" as a keyword
• NEW — match new messages
• OLD — match old messages
• ON "date" — match messages with Date: matching "date"
• RECENT — match messages with the \RECENT flag set
• SEEN — match messages that have been read (the \SEEN flag is set)
• SINCE "date" — match messages with Date: after "date"
• SUBJECT "string" — match messages with "string" in the Subject:
• TEXT "string" — match messages with text "string"
• TO "string" — match messages with "string" in the To:
• UNANSWERED — match messages that have not been answered
• UNDELETED — match messages that are not deleted
• UNFLAGGED — match messages that are not flagged
• UNKEYWORD "string" — match messages that do not have the keyword "string"
• UNSEEN — match messages which have not been read yet

Further information:

• http://php.net/manual/en/function.imap-search.php
• https://tools.ietf.org/html/rfc1176
• https://tools.ietf.org/html/rfc1064
• https://tools.ietf.org/html/rfc822

Paginate a message collection:

/** @var \Webklex\IMAP\Support\MessageCollection $aMessage */

/** @var \Illuminate\Pagination\LengthAwarePaginator $paginator */
$paginator = $aMessage->paginate();

Get a specific message by uid (Please note that the uid is not unique and can change):

/** @var \Webklex\IMAP\Folder $oFolder */

/** @var \Webklex\IMAP\Message $oMessage */
$oMessage = $oFolder->getMessage($uid = 1);

Flag or "unflag" a message:

/** @var \Webklex\IMAP\Message $oMessage */
$oMessage->setFlag(['Seen', 'Spam']);
$oMessage->unsetFlag('Spam');

Save message attachments:

/** @var \Webklex\IMAP\Message $oMessage */

/** @var \Webklex\IMAP\Support\AttachmentCollection $aAttachment */
$aAttachment = $oMessage->getAttachments();

$aAttachment->each(function ($oAttachment) {
    /** @var \Webklex\IMAP\Attachment $oAttachment */
    $oAttachment->save();
});

Fetch messages without body fetching (decrease load):

/** @var \Webklex\IMAP\Folder $oFolder */

/** @var \Webklex\IMAP\Support\MessageCollection $aMessage */
$aMessage = $oFolder->searchMessages([['TEXT', 'Hello world']], null, false);

/** @var \Webklex\IMAP\Support\MessageCollection $aMessage */
$aMessage = $oFolder->getMessages('ALL', null, false);

Fetch messages without body and attachment fetching (decrease load):

/** @var \Webklex\IMAP\Folder $oFolder */

/** @var \Webklex\IMAP\Support\MessageCollection $aMessage */
$aMessage = $oFolder->searchMessages([['TEXT', 'Hello world']], null, false, 'UTF-8', false);

/** @var \Webklex\IMAP\Support\MessageCollection $aMessage */
$aMessage = $oFolder->getMessages('ALL', null, false, false);

Find the folder containing a message:

$oFolder = $aMessage->getContainingFolder();

Extends Illuminate\Support\Collection::class

Extends Illuminate\Support\Collection::class

Extends Illuminate\Support\Collection::class

• Wiki!!

Please see CHANGELOG for more information what has changed recently.

If you discover any security related issues, please email [email protected] instead of using the issue tracker.

• Webklex
• All Contributors

A special thanks to Jetbrains for supporting this project through their open source license program.

The MIT License (MIT). Please see License File for more information.