eiseMail library

It consists of two major classes:

eiseSMTP - the class that sends mail using sockets and supports TLS and other required security features. Developed especially to make batch send much easier.
eiseIMAP - the class that reads mail with IMAP. It’s not just a wrapper to native PHP IMAP, it is aimed to obtain message attachments in simpliest possible way.

Both classes are based on eiseMail_base class that contains some handful utilities.

In case of exception, class methods are throwing eiseMailException object with mail message queue in its actual state so you can trace what messages were sent and what were not.
PHP version: >5.1

License: GNU Public License http://opensource.org/licenses/gpl-license.php
Uses: : OpenSSL, IMAP
Version: : 1.0
Author: : Ilya Eliseev ie@e-ise.com, contributors: Dmitry Zakharov, Igor Zhuravlev

Sponsors: Yusen Logistics Rus LLC, Russia

class eiseSMTP

Class for mail sending and communications via SMTP. In difference with other mail utilities in PHP, it is aimed for batch mailing to various recipients with a little adaptation of mail message to each recipient. Message body, header, footer, subject can be set on main configuration options and then implemented in each mail in batch.

It can be used in the following way:

Create object with connection settings to the SMTP server
Add messages to send queue using addMessage() method (attachments can be added to messages as associative array members, class will handle them in proper way)
Send queue using send() method, it returns message array with timestamps when messages were actually sent.

send() method uses sockets to connect to SMTP server. It supports host authentication and TLS channel encryption. It pushes the message queue to the server right after connection is established, channel encrypted and authentication succeeded.

Being executed with ['flagAddToSentItems'] = true send() method will make an attempt to save message in sender’s “Sent Items” folder.

Class has been tested for proper communication with the following SMTP servers:

Postfix/Sendmail
Microsoft Exchange
Google mail
Microsoft Office365
Yandex mail

Actual example can be found in eiseMail_demo.php script attached to this package.

public function __construct($arrConfig)

Constructor just initializes the object and covers password for possible verbose mode.

Parameters:

$arrConfig (array) - configuration options array:
- Content-Type (string) - message body content type, default “text/plain”
- charset (string) - message body charset, default “utf-8”
- host (string) - SMTP server host name / IP address, default “localhost”
- port (string) - SMTP server port, default “25”
- tls (boolean) - flag use TLS channel encryption, default false
- login (string) - SMTP server login, default “”
- password (string) - SMTP server password, default “”
- localhost (string) - defines how to introduce yourself to SMTP server with HELO/EHLO SMTP command, default “localhost”
- Subject (string) - default subject for message queue, default ‘’
- Head (string) - default message body head, default ‘’
- Bottom (string) - default message bottom , default ‘’
- flagAddToSentItems (boolean) - set to true if you need a copy of message to be saved in user Sent Items, default false
- imap_host (string) - IMAP host address, default ‘’
- imap_login (string) - (optional) IMAP login. By default it is set by ‘login’ field. Specify only if it differs from it. Default ‘’
- imap_password (string) - (optional) IMAP password, default ‘’
- verbose (boolean) - when set to TRUE class methods are sending actual conversation data to standard output, default false
- debug (boolean) - when set to TRUE mail is actually sent to ‘rcpt_to_debug’ address + verbose, default false
Default mail message fields can be set here also:
- Content-type (default is ‘text/plain’)
- charset (default is ‘utf8’)
- From
- To
- Reply-To
- Subject (string)
- flagEscapeSubject
- Head
- Bottom
See more at eiseSMTP::addMessage() description.

public function addMessage ($msg)

This method adds message to message queue. Also it prepares all mandatory SMTP headers like mail from: and rcpt to: basing on From, To, Cc and Bcc fields.

Category: Mail send

Parameters:

$msg (array) - Associative array with message data. See description below:
- From (string) - content of ‘From’ field, can be set by default with object configuration options, see eiseSMTP::__construct(), default $this->conf['From']. If not set, it will be taken from login field.
- Content_Type (string) - MIME-type, default is $this->conf[‘Content-Type’]
- charset (string) - charset, default $this->conf[‘charset’]
- To (string) - “To” header contents, default $this->conf[‘To’]
- Reply-To (string) - “Reply-To” header contents, default’ => $this->conf[‘Reply-To’]
- Cc (string) - “Cc” addresses list, default null
- Bcc (string) - “Bcc” address list, default null
- Subject (string) - Message subject, default $this->conf[‘Subject’]
- flagEscapeSubject (booelan) - flag that tells whether to escape subject or not, default can be set by $this->conf[‘flagEscapeSubject’]
- Head (string) - Message header, default is $this->conf[‘Head’]. Contents of this field will be combined with Text and Bottom members of this array. Before send all necessary replacements will be done with eiseMail_base::doReplacements().
- Text (string) - Message body, default ‘’
- Bottom (string) - Message footer, default $this->conf[‘Bottom’]
- Attachments (array) - enumerable array of attachments. Each attachment have the following structure:
  - filename (string) - file name as it will saved with the message
  - content (binary) - attachment contents
  - Content-Type (string) - attachment MIME-type
Example:
```
  $sender->addMessage(array('From'=> '"John Doe" <john.doe@acme.com>'
          , 'To' => '"Bar, Foo" <foo.bar@sukaba.com>'
          , 'Subject' => 'Message with 2 kinds of attachments'
          , 'Text' => 'Hello there'
          , 'Attachments' => array(
             array ('filename'=>'file1.txt'
                 , 'content'=>"Hello\r\nfrom the text file"
                 , 'Content-Type'=>'text/plain')
             , array ('filename'=>'file2.txt'
                 , 'content'=>"Hello\r\nfrom the text file again"
                 , 'Content-Type'=>'text/plain')
             , array ('filename'=>'welcome_to_the_internet.jpg'
                 , 'content'=>file_get_contents('welcome_to_the_internet.jpg')
                 , 'Content-Type'=>'image/jpeg')
	
             )
          );
```

public function send($arrMsg=null)

This method performs connection to SMTP server and sends all message queue. Then it converts each message from $arrMessages to string, performs base64-encoding, chunk-splitting of the attachemtns and send each message to anyone in To, Cc and Bcc messages.
In case of failure it throws eiseMailException object with message queue. If you need to analyze what message were sent or not, you can walk through eiseMailException $arrMessages array. Each member of this array will be updated with the following members:

send_time (int) - UNIX timestamp when message was sent, in case of success
error (string) - Error message, in case of failure

Category: Mail send

Parameters:

$arrMsg (array) - single message, see …

public function getMessageSource($ixToGet = null)

This function returns source of a partiqular message in queue, its number (index) is specified by $ixToGet parameter. If this parameter is omitted, first message source is returned. This method uses msg2String private method.

Parameters:

$ixToGet (integer) - Message number (index) in queue.

Returns: string Message source.

private function msg2String($msg)

This function prepares message for sending: it converts it to string with headers and message parts

Parameters:

$msg (array) - message array

Returns: string Ready-to-send message data after SMTP DATA command.

private function say($words, $arrExpectedReplyCode=array())

This function transmits data to SMTP server

Parameters:

$words (string) - data to transmit
$arrExpectedReplyCode (array) - array of expected reply codes from the server.

Returns: void

private function listen($arrExpectedReplyCode=array())

This function listens for reply from SMTP server

Parameters:

$arrExpectedReplyCode (array) - array of expected reply codes from the server.

Returns: string $data - string with SMTP reply to last transmission

private function isItOk($rcv, $arrExpectedReplyCode)

This function analyze reply from SMTP server and, in case of unexpected reply, it throws the exception

Parameters:

$rcv (string) - server reply
$arrExpectedReplyCode (array) - array of expected reply codes from the server.

Returns: void

public variable $arrMessages

Mail message queue to send.

class eiseIMAP

Class to handle messages from IMAP/POP3 server

Uses PHP IMAP extension function

Link: http://php.net/manual/en/ref.imap.php

public function __construct($arrConfig)

Object constructor. Receives configuration array as parameter and merges it with the default one.

Parameters:

$arrConfig (array) - see eiseImap::$arrDefaultConfig

public function connect()

This method establishes connection with IMAP server.

Category: Mail receive

public function receive()

This method retrieves messages from the remote server as an associative array.

Category: Mail receive

Returns: Message array in the same manner as source for eiseSMTP function.

From (string) - sender, encoded to UTF-8
To (string) - addressee, encoded to UTF-8
CC (string) - CC field, encoded to UTF-8
Subject (string) - Subject field, encoded to UTF-8
overview (object) - first object from return value of imap_fetch_overview() function
source (string) - message source
Attachments (array) - array of attachments, in the same manner as for eiseSMTP function:
- filename (string) - filename, encoded to UTF-8
- content (binary) - binary content of the attached file
- Content-Type (string) - content MIME type

public function mailOverviewUTF8($overview)

This function converts mail headers to unicode and updates $overview object that returned by imap_fetch_overview() PHP function and updates the object with corresponding fields with _utf8 suffix: $overview->to_uft8 $overview->from_uft8 $overview->subject_utf8

Category: Message processing

Parameters:

$overview (object) - a single overview message object taken from the array returned by imap_fetch_overview() PHP function

Returns: $overview object

public function checkMailOverview($overview)

Function that allows to filter mail by its overview. If function returns true, mail attachments will be dowloaded also. This is interface function, to be overridden in extending class. By default it returns true, i.e. all messages will be returned with attachments.

Parameters:

$overview (object) - a single overview message object taken from the array returned by imap_fetch_overview() PHP function

Returns: variant - When it returns false if message will be skipped. If any other value - message will be completely fetched from the server

public function handleMessage()

Callback function to handle current messages stored in $this->msg object

Returns: boolean - If it returns true, receive() method sets flags for it specified in $conf[‘set_flags_on_handle’]

public function save($strMessage)

This function saves message in specified IMAP mailbox. It was used in this library to save sent mail to “Sent Items” in function eiseSMTP::send().

Parameters:

$strMessage (sttring) - the message, ready-to-send via SMTP

private function fetch_file($part, $partID)

Function recursively walks through all $part object and picks up any attachment.

This object is returned by imap_fetchstructure() PHP IMAP function.

There can be 3 cases:

Message is the file: it has only one part that contains attached file
Multipart message: when message contains few parts: some for texts, some for attachments
Alternative messages: when message consists of few parts: each one can have few subparts with attachments/texts etc.
This function just walks through all these parts recursively.

Category: Mail receive

Parameters:

$part (object) - the object that represents message structure element
$partID - id for part to be analyzed for attachments. ‘0’ represents root $part of message, ‘1’, ‘2’, etc - subparts of root part ‘2.1’, ‘2.2’, etc - subparts of sub-root part, and so on.

static variable $arrDefaultConfig

Default configuration associative array:

host (string) - IMAP server host name / IP address, default “localhost”
port (string) - IMAP server port , default “993”
flags (string) - flags according to imap_open() PHP function , default ‘/imap/ssl’
mailbox_name (string) - flags according to imap_open() PHP function, default ‘INBOX’
login (string) - SMTP server login , default “”
password (string) - SMPT server password , default “”
imap_open_options (int) - options for imap_open(), default 0
imap_open_n_retries (int) - attempt number for imap_open(), default 1
imap_open_params (string) - parameters array for imap_open(), default array()
search_criteria (string) - search criteria for imap_search() function, default ‘NEW’
max_messages (string) - maximum messages, default 10
set_flags_on_scan (string) - flags to set on message when it’s been scanned by script, default ‘\Seen’
set_flags_on_handle (string) - flags to set on message when it’s been handled by script, default ‘\Answered’
flagGetMessageSource (string) - when TRUE it will obtain all message source on reception, default false
verbose (string) - when set to TRUE class methods are sending actual flow data to standard output, default true

class eiseMailException

This extension of Exception class should allow us to pass back messages array in its actual state

public function __construct($usrMsg, $arrMessages=array())

Receives user message and $messages array

Parameters:

$usrMsg {string} text user message
$arrMessages {array} array of messages that can be set as an attemp to save unsent / unhandled messages in case of exception.

public function getMessages()

Receives user message and $messages array

Parameters:

$usrMsg {string} text user message
$arrMessages {array} array of messages that can be set as an attemp to save unsent / unhandled messages in case of exception.

function __construct($usrMsg, $arrMessages=array()){ parent::__construct($usrMsg); $this->arrMessages = $arrMessages; }

/* This function should be used in ‘catch’ block after eiseMail::send() activation to obtain eiseMail::arrMessages array in its actual state

class eiseMail_base

This class contains basic functions to handle mails/addresses/flow etc

public function coverPassword()

In order to prevent uncovered password display in verbose mode, this function offers partial password coverage. Number of symbols to show is set by eiseMail_base::passSymbolsToShow. Default value is 3. Password will be shown with first eiseMail_base::passSymbolsToShow, all the rest will be replaced with asterisks. Example: echo eiseMail::coverPassword('qwerty'); // will print 'qwe***'

Category: Utilities

static function explodeAddresses($addrList, $defaultDomain = ‘‘)

Explodes address list according to RFC2822: "Name Surname" <mailbox@host.domain>, "Surname, Name" <mailbox1@host.domain> etc to array. Ordinary explode() will not work, because comma (“,”) can be a part of personal information. E.g. "John Smith, Mr" <john.smith@domain.com>

Category: Message processing

Parameters:

$addrList (string) - Address list

Returns: array of strings with addresses

static function getAddresses($addrList, $defaultDomain = ‘‘)

Retrieves exact unique addresses from list matching according to RFC2822: “Name Surname” mailbox@host.domain, “Surname, Name” mailbox1@host.domain etc

Category: Message processing

Parameters:

$addrList (string) - Address list

Returns: array of strings with addresses w/o personal info

static function prepareAddressRFC( $addr, $defaultDomain=’‘)

Gets RFC-compliant mail address to be used with ‘MAIL FROM:’ and ‘RCPT TO:’ SMPT commands

Category: Message processing

Parameters:

$addr (string) - mail address list

Returns: false if $addr contains something wrong. Otherwise removes personal information from the address and returns address like ‘mailbox@domain.com’

static function doReplacements($text, $arrReplacements)

It replaces escaped statements (e.g. ##Sender## or ##orderHref##) in $text with values from $arrReplacements array (e.g ‘Sender’ => ‘John Doe’, ‘orderHref’ => ‘http://mysite.com/orders/12345’)

Category: Message processing

Parameters:

$text (string) - original text
$arrReplacements (array) - is an associative array of keys and replacements. Each occurence of ##$key## will be replaced with corresponding value.

Returns: string corrected text

static function getSubject($rfc822)

This function retrieves raw message subject from text representation of mail message.

Category: Message processing

Parameters:

$rfc822 (string) - Mail message in rfc822 format

Returns: string with subject

protected function v($string)

This function echoes if ‘verbose’ configuration flag is on.

Category: Utilities

Parameters:

$string (string) - string to echo.

Returns: void