Mail queueing using PEAR Mail_Queue

Introduction

Most of us at some point have needed to add some form of mailing functionality to a website/application. However as the demand on the system has increased we've had to send more and more emails (billing runs, newsletters, etc) to the point where 1 page execution has been insufficient to send a few thousand emails.

Thankfully we have a simple solution provided by the PEAR libraries, Mail_Queue.

Installing PEAR Mail_Queue

You'll need to get hold of the PEAR Webservice library first (and the core PEAR libraries if you don't have that already). You can follow the installation instructions to get PEAR installed on your system at:

http://pear.php.net/manual/en/installation.php

The package we will be using can be located here:

http://pear.php.net/package/Mail_Queue/

For Ubuntu users you can install PEAR, DB (to handle database connections) and Mail_Queue like this

$ sudo apt-get install php-pear
$ sudo pear install -a DB
$ sudo pear install -a Mail_Queue

You may have to install some dependants of the Mail_Queue like Mail_mime (check the install message from Mail_Queue for these dependants). The -a flag should take care of them. If not then install them manually.

Setting up the Database

Mail_Queue uses a database tableto store queued emails so we'll need to create that first. The database design can be found here: http://pear.php.net/manual/en/package.mail.mail-queue.mail-queue.tutorial.php and looks like this.

CREATE TABLE mail_queue (
  id bigint(20) NOT NULL default '0',
  create_time datetime NOT NULL default '0000-00-00 00:00:00',
  time_to_send datetime NOT NULL default '0000-00-00 00:00:00',
  sent_time datetime default NULL,
  id_user bigint(20) NOT NULL default '0',
  ip varchar(20) NOT NULL default 'unknown',
  sender varchar(50) NOT NULL default '',
  recipient text NOT NULL,
  headers text NOT NULL,
  body longtext NOT NULL,
  try_sent tinyint(4) NOT NULL default '0',
  delete_after_send tinyint(1) NOT NULL default '1',
  PRIMARY KEY  (id),
  KEY id (id),
  KEY time_to_send (time_to_send),
  KEY id_user (id_user)
);

Coding the Queue System

require_once "Mail/Queue.php"; // Information required to connect to the database $db['type'] = 'db'; $db['dsn'] = 'mysql://username:password@host/database'; $db['mail_table'] = 'mail_queue'; // Options for configuring the Mail Queue $options['driver'] = 'smtp'; $options['host'] = 'smtp.your_mail_server.com'; $options['port'] = 25; $options['auth'] = false; // Authentication for your email account the email will be sent through $options['username'] = 'email_address'; $options['password'] = 'email_address_password'; // We use the $db and $options here to initialize a new Mail_Queue object $queue =& new Mail_Queue($db_options, $mail_options); $mime =& new Mail_mime(); $mime->setTXTBody("Insert your message here"); // Alternatively you can use the setHTMLBody instead if you want to send HTML based emails // See http://pear.php.net/package/Mail_Mime/docs/latest/Mail_Mime/Mail_mime.html#methodsetHTMLBody for more info // $mime->setHTMLBody($content); // You can add attachments by using the following function (can call multiple times) // See http://pear.php.net/package/Mail_Mime/docs/latest/Mail_Mime/Mail_mime.html#methodaddAttachment for more info //$mime->addAttachment($filename_with_path, $mime_type, $filename); $to = "test@test.com"; $from = "you@youremailaddress.com"; $hdrs = array( "To" => $to, "From" => $from, "Subject" => "Subject of the email", "Date" => date('r') ); // Turn this email into suitable MIME format $body = $mime->get(); // Generate suitable headers given the information provided $hdrs = $mime->headers($hdrs); // Put the message in the queue $mail_queue->put($from, $to, $hdrs, $body);

Coding the Cronjob

You'll now need a scheduled event to send your queued emails. We'll save this script as queue.php.

require_once "Mail/Queue.php"; // Information required to connect to the database $db['type'] = 'db'; $db['dsn'] = 'mysql://username:password@host/database'; $db['mail_table'] = 'mail_queue'; // Options for configuring the Mail Queue $options['driver'] = 'smtp'; $options['host'] = 'smtp.your_mail_server.com'; $options['port'] = 25; $options['auth'] = false; // Authentication for your email account the email will be sent through $options['username'] = 'email_address'; $options['password'] = 'email_address_password'; // We use the $db and $options here to initialize a new Mail_Queue object $queue =& new Mail_Queue($db_options, $mail_options); $max_amount = 50; $max_send_attempts = 10; // This will send a batch of emails from the queue // The explanation of this function and its parameters can be found here: // http://pear.php.net/package/Mail_Queue/docs/latest/Mail_Queue/Mail_Queue.html#methodsendMailsInQueue $queue->sendMailsInQueue($max_amount, MAILQUEUE_START, $max_send_attempts);

You'll then, if you're using Linux, have to add the script to your cronjob file. This is normally located at /etc/crontab.

You'll have to add a new entry that looks something like this:

*/5   *       *       *       *       user    /usr/bin/php -f /path/to/script/queue.php

What this basically means is that every 5 minutes our script will run and send 50 emails (10 attempts for each) from the top of the queue to their intended recipients.

Points of Interest

That's a basic mail queueing system done. There are various modifications you can make by using different features of the Mail_Queue library or you can hack the Mail_Queue library yourself to include other features (like mail priority, mail delaying, etc).

I personally use this library in a professional environment to mail thousands of invoices with PDF attachments every month without problems.

Points to note are:

• There's an option to delete mail after sending it.
• Successfully sent emails doesn't mean the message won't get bounced back or fail. It just means your SMTP server has accepted the email and passed it on successfully. Emails can still fail if the email address is invalid, expired or blocking your email address / spam block.

Conclusion

And that's it. A simple but highly useful library for handling your PHP application's emails.

License

This article, along with any associated source code and files, is licensed under The Common Public License Version 1.0 (CPL)

About the author