IMAP Library for Laravel – Fetch email using laravel

Description

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

If you want to use this library outside of Laravel, please head over to webklex/php-imap

Table of Contents

• Installation
• Configuration
• Usage
  • Basic usage example
  • Facade
  • Folder / Mailbox
  • Search
  • Counting messages
  • Result limiting
  • Pagination
  • View examples
  • Fetch a specific message
  • Message flags
  • Attachments
  • Advanced fetching
  • Masking
  • Specials
• Support
• Documentation
  • Client::class
  • Message::class
  • Folder::class
  • Query::class
  • Attachment::class
  • Mask::class
    • MessageMask::class
    • AttachmentMask::class
  • MessageCollection::class
  • AttachmentCollection::class
  • FolderCollection::class
  • FlagCollection::class
• Known issues
• Milestones & upcoming features
• Security
• Credits
• Supporters
• License

Installation

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

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

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

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

composer require webklex/laravel-imap

1. 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,
2. Run the command below to publish the package config file config/imap.php:

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

Configuration

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
IMAP_PROTOCOL=imap

Supported protocols:

• imap — Use IMAP [default]
• pop3 — Use POP3
• nntp — Use NNTP

The following encryption methods are supported:

• false — Disable encryption
• ssl — Use SSL
• tls — Use TLS
• starttls — Use STARTTLS (alias TLS)
• notls — Use NoTLS

Detailed config/imap.php configuration:

• default — used default account. It will be used as default for any missing account parameters. If however the default account is missing a parameter the package default will be used. Set to false to disable this functionality.
• accounts — all available accounts
  • default — The account identifier (in this case default but could also be fooBar etc).
    • 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
• date_format — The default date format is used to convert any given Carbon::class object into a valid date string. (d-M-Y, d-M-y, d M y)
• options — additional fetch options
  • delimiter — you can use any supported char such as “.”, “/”, etc
  • fetch — IMAP::FT_UID (message marked as read by fetching the message) or IMAP::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
  • fetch_flags — If set to false all messages will be fetched without any flags
  • message_key — Message key identifier option
  • fetch_order — Message fetch order
  • open — special configuration for imap_open()
    • DISABLE_AUTHENTICATOR — Disable authentication properties.
  • decoder — Currently only the message subject and attachment name decoder can be set
  • masks — Default masking config
    • message — Default message mask
    • attachment — Default attachment mask

Usage

Basic usage example

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',
    'protocol'      => 'imap'
]);
/* Alternative by using the Facade
$oClient = Webklex\IMAP\Facades\Client::account('default');
*/

//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->messages()->all()->get();
    
    /** @var \Webklex\IMAP\Message $oMessage */
    foreach($aMessage as $oMessage){
        echo $oMessage->getSubject().'<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';
        }
    }
}

Facade

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();

Folder / Mailbox

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');

List all available folders:

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

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

Search for messages

Search for specific emails:

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

//Get all messages
/** @var \Webklex\IMAP\Support\MessageCollection $aMessage */
$aMessage = $oFolder->query()->all()->get();

//Get all messages from [email protected]
/** @var \Webklex\IMAP\Support\MessageCollection $aMessage */
$aMessage = $oFolder->query()->from('[email protected]')->get();

//Get all messages since march 15 2018
/** @var \Webklex\IMAP\Support\MessageCollection $aMessage */
$aMessage = $oFolder->query()->since('15.03.2018')->get();

//Get all messages within the last 5 days
/** @var \Webklex\IMAP\Support\MessageCollection $aMessage */
$aMessage = $oFolder->query()->since(now()->subDays(5))->get();
//Or for older laravel versions..
$aMessage = $oFolder->query()->since(\Carbon::now()->subDays(5))->get();

//Get all messages containing "hello world"
/** @var \Webklex\IMAP\Support\MessageCollection $aMessage */
$aMessage = $oFolder->query()->text('hello world')->get();

//Get all unseen messages containing "hello world"
/** @var \Webklex\IMAP\Support\MessageCollection $aMessage */
$aMessage = $oFolder->query()->unseen()->text('hello world')->get();

//Extended custom search query for all messages containing "hello world" 
//and have been received since march 15 2018
/** @var \Webklex\IMAP\Support\MessageCollection $aMessage */
$aMessage = $oFolder->query()->text('hello world')->since('15.03.2018')->get();
$aMessage = $oFolder->query()->Text('hello world')->Since('15.03.2018')->get();
$aMessage = $oFolder->query()->whereText('hello world')->whereSince('15.03.2018')->get();

// Build a custom search query
/** @var \Webklex\IMAP\Support\MessageCollection $aMessage */
$aMessage = $oFolder->query()
->where([['TEXT', 'Hello world'], ['SINCE', \Carbon::parse('15.03.2018')]])
->get();

//!EXPERIMENTAL!
//Get all messages NOT containing "hello world"
/** @var \Webklex\IMAP\Support\MessageCollection $aMessage */
$aMessage = $oFolder->query()->notText('hello world')->get();
$aMessage = $oFolder->query()->not_text('hello world')->get();
$aMessage = $oFolder->query()->not()->text('hello world')->get();

Available search aliases for a better code reading:

// Folder::search() is just an alias for Folder::query()
/** @var \Webklex\IMAP\Support\MessageCollection $aMessage */
$aMessage = $oFolder->search()->text('hello world')->since('15.03.2018')->get();

// Folder::messages() is just an alias for Folder::query()
/** @var \Webklex\IMAP\Support\MessageCollection $aMessage */
$aMessage = $oFolder->messages()->text('hello world')->since('15.03.2018')->get();

All available query / search methods can be found here: Query::class

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
• NOT — not matching
• 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
• https://gist.github.com/martinrusev/6121028

Result limiting

Limiting the request emails:

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

//Get all messages for page 2 since march 15 2018 where each apge contains 10 messages
/** @var \Webklex\IMAP\Support\MessageCollection $aMessage */
$aMessage = $oFolder->query()->since('15.03.2018')->limit(10, 2)->get();

Counting messages

Count all available messages matching the current search criteria:

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

//Count all messages
/** @var \Webklex\IMAP\Support\MessageCollection $aMessage */
$count = $oFolder->query()->all()->count();

//Count all messages since march 15 2018
$count = $oFolder->query()->since('15.03.2018')->count();

Pagination

Paginate a query:

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

/** @var \Illuminate\Pagination\LengthAwarePaginator $paginator */
$paginator = $oFolder->query()->since('15.03.2018')->paginate();

Paginate a message collection:

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

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

Blade example for a paginated list:

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

/** @var \Illuminate\Pagination\LengthAwarePaginator $paginator */
$paginator = $oFolder->search()
->since(\Carbon::now()->subDays(14))->get()
->paginate($perPage = 5, $page = null, $pageName = 'imap_blade_example');

<table>
    <thead>
        <tr>
            <th>UID</th>
            <th>Subject</th>
            <th>From</th>
            <th>Attachments</th>
        </tr>
    </thead>
    <tbody>
        @if($paginator->count() > 0)
            @foreach($paginator as $oMessage)
                <tr>
                    <td>{{$oMessage->getUid()}}</td>
                    <td>{{$oMessage->getSubject()}}</td>
                    <td>{{$oMessage->getFrom()[0]->mail}}</td>
                    <td>{{$oMessage->getAttachments()->count() > 0 ? 'yes' : 'no'}}</td>
                </tr>
            @endforeach
        @else
            <tr>
                <td colspan="4">No messages found</td>
            </tr>
        @endif
    </tbody>
</table>

{{$paginator->links()}}

You can also paginate a Folder-, Attachment- or FlagCollection instance.

View examples

You can find a few blade examples under /examples.

Fetch a specific message

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);

Message flags

Flag or “unflag” a message:

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

Mark all messages as “read” while fetching:

/** @var \Webklex\IMAP\Folder $oFolder */
/** @var \Webklex\IMAP\Support\MessageCollection $aMessage */
$aMessage = $oFolder->query()->text('Hello world')->markAsRead()->get();

Don’t mark all messages as “read” while fetching:

/** @var \Webklex\IMAP\Folder $oFolder */
/** @var \Webklex\IMAP\Support\MessageCollection $aMessage */
$aMessage = $oFolder->query()->text('Hello world')->leaveUnread()->get();

Attachments

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();
});

Advanced fetching

Fetch messages without body fetching (decrease load):

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

/** @var \Webklex\IMAP\Support\MessageCollection $aMessage */
$aMessage = $oFolder->query()->whereText('Hello world')->setFetchBody(false)->get();

/** @var \Webklex\IMAP\Support\MessageCollection $aMessage */
$aMessage = $oFolder->query()->whereAll()->setFetchBody(false)->setFetchAttachment();

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

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

/** @var \Webklex\IMAP\Support\MessageCollection $aMessage */
$aMessage = $oFolder->query()->whereText('Hello world')
->setFetchFlags(false)
->setFetchBody(false)
->setFetchAttachment(false)
->get();

/** @var \Webklex\IMAP\Support\MessageCollection $aMessage */
$aMessage = $oFolder->query()->whereAll()
->setFetchFlags(false)
->setFetchBody(false)
->setFetchAttachment(false)
->get();

Masking

Laravel-IMAP already comes with two default masks MessageMask::class and AttachmentMask::class.

The masked instance has to be called manually and is designed to add custom functionality.

You can call the default mask by calling the mask method without any arguments.

/** @var \Webklex\IMAP\Message $oMessage */
$mask = $oMessage->mask();

There are several methods available to set the default mask:

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

$message_mask = \Webklex\IMAP\Support\Masks\MessageMask::class;

$oClient->setDefaultMessageMask($message_mask);
$oMessage->setMask($message_mask);
$mask = $oMessage->mask($message_mask);

The last one wont set the mask but generate a masked instance using the provided mask.

You could also set the default masks inside your config/imap.php file under masks.

You can also apply a mask on attachments:

/** @var \Webklex\IMAP\Client $oClient */
/** @var \Webklex\IMAP\Attachment $oAttachment */
$attachment_mask = \Webklex\IMAP\Support\Masks\AttachmentMask::class;

$oClient->setDefaultAttachmentMask($attachment_mask);
$oAttachment->setMask($attachment_mask);
$mask = $oAttachment->mask($attachment_mask);

If you want to implement your own mask just extend MessageMask::class, AttachmentMask::class or Mask::class and implement your desired logic:

/** @var \Webklex\IMAP\Message $oMessage */
class CustomMessageMask extends \Webklex\IMAP\Support\Masks\MessageMask {

    /**
     * New custom method which can be called through a mask
     * @return string
     */
    public function token(){
        return implode('-', [$this->message_id, $this->uid, $this->message_no]);
    }
}

$mask = $oMessage->mask(CustomMessageMask::class);

echo $mask->token().'@'.$mask->uid;

Additional examples can be found here:

• Custom message mask
• Custom attachment mask

Specials

Find the folder containing a message:

$oFolder = $aMessage->getContainingFolder();

Support

If you encounter any problems or if you find a bug, please don’t hesitate to create a new issue. However please be aware that it might take some time to get an answer.

If you need immediate or commercial support, feel free to send me a mail at [email protected].

A little notice

If you write source code in your issue, please consider to format it correctly. This makes it so much nicer to read and people are more likely to comment and help 🙂

“` php

echo ‘your php code…’;

“`

will turn into:

echo 'your php code...';

Features & pull requests

Everyone can contribute to this project. Every pull request will be considered but it can also happen to be declined. To prevent unnecessary work, please consider to create a feature issue first, if you’re planning to do bigger changes. Of course you can also create a new feature issue if you’re just wishing a feature 😉

Off topic, rude or abusive issues will be deleted without any notice.

Documentation

Client::class

Message::class

Folder::class

Query::class

Attachment::class

Mask::class

MessageMask::class

AttachmentMask::class

MessageCollection::class

Extends Illuminate\Support\Collection::class

FlagCollection::class

Extends Illuminate\Support\Collection::class

AttachmentCollection::class

Extends Illuminate\Support\Collection::class

FolderCollection::class

Extends Illuminate\Support\Collection::class

Known issues

Milestones & upcoming features

• Wiki!!

Change log

Please see CHANGELOG for more information what has changed recently.

Security

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

Credits

• Webklex
• All Contributors

Supporters

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

License

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