Process Incoming Email Messages using PHP Script to Receive and Get Read Email Inbox using POP3 and Parse Mail from the Mailbox - POP3 e-mail client package blog

By Manuel Lemos

manuellemos.net

<email contact>

Contents

* Introduction

* Starting a PHP script on message arrival

* Accessing received messages via POP3 or IMAP

* Parsing and processing received messages

* Immediate processing versus POP3 or IMAP access to messages


* Introduction

Some PHP applications need to handle incoming e-mail sent to a certain address and process the messages in a way that suits the application needs.

For instance, if you want to develop a simple CRM application (Customer Relationship Management), usually it needs to receive the messages sent by the customers to a given address and process them somehow.

A typical e-mail processing script stores the message details in a database, so the messages can be handled later by a customer support representative.

PHP can help in this situation by automatically receiving and performing the initial processing of the incoming messages.


* Starting a PHP script on message arrival

One way to process the incoming messages is to configure the local mail server to start a PHP script when a message arrives on a given mailbox.

To achieve this, you need to learn specific details of how to configure your mail server because each mail server works in a different way.

For instance, if you use qmail mail server, you need to setup a .qmail file associated to the e-mail address that you want to handle. The .qmail file must contain the command that will be executed to start the PHP script that will handle the incoming messages.

For instance, if PHP CLI (Command Line Interface) version path is /usr/bin/php , and the path of the PHP script that will process the messages is /home/crm/bin/request.php, the .qmail file must have this line:

/usr/bin/php /home/crm/bin/request.php

The incoming message data is passed to PHP via the standard input. Therefore, you can read the message as if it was a file with name php://stdin , for instance like this:

$message = file_get_contents('php://stdin');


* Accessing received messages via POP3 or IMAP

An alternative solution to process received e-mail messages using PHP is to associate the incoming addresses to mailboxes accessible using POP3 or IMAP client scripts.

In this case, the messages are received and stored by the mail server, so they can be processed later by applications.

PHP scripts can use existing POP3 or IMAP client classes or extensions to regularly poll the mail server and retrieve the messages to perform the necessary processing tasks.

To perform this periodic poll, you can use the PHP CLI version command to start a PHP script by adding a task to cron on Linux and other Unix like systems, or the task scheduler on Windows.

Depending on how important the incoming messages may be, you may adjust the frequency of execution of the mailbox polling script.

For instance, if PHP CLI version command path is /usr/bin/php , and the path of the script that will process the messages every 5 minutes is /home/crm/bin/request.php, you need to add a cron task by adding a line like this to the crontab:

5 * * * * /usr/bin/php /home/crm/bin/request.php

PHP has the IMAP extension that can access mailboxes either via POP3 or IMAP protocol. However, this extension is not always available in all PHP installations.

Alternatively, this POP3 class can be always used regardless if the IMAP extension available.

The POP3 class comes with a stream handler that allows you to retrieve files from a mailbox, as if the messages were real files. For instance, you can re retrieve the first message from the mailbox like this:

stream_wrapper_register('pop3', 'pop3_stream');

$message = file_get_contents( 'pop3://user:password@pop.mailserver.com/1' );

"user" is the user name of the mailbox account and "password" is the respective password. "pop.mailserver.com" is the mail server host address.

If you want to process the message and delete it later, which usually you have to do, you need to implement a little more complicated procedure demonstrated by the following code sample. This assures that the messages are listed, retrieved and deleted safely within the same POP3 connection:

/* Set connection options */
$pop3 = new pop3_class;
$pop3->hostname = "pop.mailserver.com";
$pop3->port = 110;
$user = "mailbox_account";
$password = "mailbox_password";
$apop = 0;

/* Connect to the server */
if(($error = $pop3->Open())=="")
{

/* Authenticate */
if(($error = $pop3->Login($user, $password, $apop))=="")
{

/* Setup a file name of a message to be retrieved
* on an already opened POP3 connection */
$pop3->GetConnectionName($connection_name);
$message=1;
$message_file='pop3://'. $connection_name. '/'. $message;

/* Do your message processing here */
$message = file_get_contents($message_file);

/* If all goes well, delete the processed message */
$pop3->DeleteMessage($message);
}

/* Close the connection before you exit */
$pop3->Close();
}


* Parsing and processing received messages

E-mail messages may have a complicated structure that it is not easy to parse. This is especially true when you need to extract complex details from the messages like encoded subjects or sender names and addresses, extracting attached files, handle messages with alternative text or HTML parts, embedded images or CSS, etc..

The best solution for handling the complexity of parsing e-mail problems is to use existing e-mail parsing components, like for instance the MIME parser class. It is ready to parse messages by passing it the message file names.

The MIME parser class comes with plenty of examples and documentation that you can read to easily learn how to use it to parse the messages that your application needs to handle.

phpclasses.org/mimeparser


* Immediate processing versus POP3 or IMAP access to messages

Before you decide which method is the best, you need to understand that each method has advantages and disadvantages. Let me give an overview of the most important details.

- Immediate processing of messages passed by the mail server

a) The messages are processed immediately as they are received by the mail server.

b) If your message processing script fails for some reason, you loose the messages. Therefore it is not recommended for applications on which the received messages are critical.

c) The mail processing script must run on the same machine as the mail server.

d) Setting up a mail processing script is a task that depends on the type of mail server.

- Processing messages polling a POP3 or IMAP server

a) The mail server must be polled regularly, so there may be delays in processing messages if the polling is not frequent enough.

b) If message processing takes too long, you need to be careful to not start processing one message before the previous message was processed. POP3 servers lock mailboxes while a connection to the server is not closed.

c) The mail processing script may poll a server that is running on a different machine.

d) Accessing messages in mailbox via POP3 or IMAP does not depend on the platform PHP is running on.


You may find more information on how to access and process messages dropped in POP3 mailboxes by looking at the example scripts and documentation available with the described classes.

If you have more questions feel free to post a comment to this article.