Emailer

Bonfire uses CodeIgniter’s email library and provides a GUI to setup all relevant information regarding your outgoing server.

The Emailer settings can be found under Settings / Email in the Bonfire admin area.  From here, you can set all all of the settings that tell CodeIgniter how to send your email.  These settings only relate to the outgoing server itself.

Available Settings

All settings are stored in application/config/email.php and should be accessed automatically whenever you load the Emailer library.  In some server setups, I have run into issues where the settings were not automatically applied.  To combat this, the settings file is loaded and passed to the Email library’s initialize() method.

Bonfire tries to take the pain out of making sure your email settings are correct.  While this process does not guarantee positive results, it does help in debugging when you run into issues.

In the settings page still, you can specify an email address to send a test email to.  This will send a simple email, wrapped in the current email template, and report whether CodeIgniter thinks the process was successful or not.  It will also return the output of the Email class’ debugger so that you can see all of the information that was sent.

This test email is not queued.  It is sent immediately so that you are not forced to setup a CRON job for the email to work.

NOTE: The test uses the last-saved settings.  If you make changes to your server, you must save those changes before testing.

You can view all of the emails waiting in your queue by visiting Statistics / Emailer in the Bonfire Admin area.  This will list all emails that have not been marked as successfully sent.

The best thing to do when building your site is to use the Emailer library in place of CodeIgniter’s Email class.  You still have access to all of the same features, but can easily start queuing emails if the need arises.

NOTE: Before the queue will work, a CRON job must be setup.  More details on this to come as the CRON solution is developed for Bonfire.

The Emailer class is loaded like any other module’s library

$this->load->library('emailer/emailer');

Once loaded, the library is accessible through $this->emailer.

Sending Emails

To send an email from your module’s controller is a two-step process.  The first step is to prepare an array of data to be passed to the send() method.

$data = array(
  'to'            => '',      // either string or array
  'subject'       => '',      // string
  'message'       => '',      // string
  'alt_message'   => ''       // optional (text alt to html email)
);

The from address is specified in the config/email.php file, and can be set through at Settings / Emailer.

Next, you call the send() method, passing the data array to the method.

$this->emailer->send($data);

By default, the email will not be queued.  You can tell Emailer to queue the email (or not) on a case by case basis by passing true/false as an optional second parameter.  If TRUE is passed, the email will be queued.  If FALSE is passed, the email will be sent immediately.

$this->emailer->send($data, true);

You can change the default action so that all emails are queued by default by calling the queue emails() method somewhere earlier in your code.

$this->emailer->queue_emails(true);

Once emails have been queued, they need to be sent somehow.  This does not work automatically out of the box, as a CRON job must be setup to run.

Whatever solution you employ, you must create the code to run a single command from the Emailer library.

$this->emailer->process_queue();

This method will run through the unsent emails in the queue and send out a small portion of them.  It is designed to be run every 5 minutes, and defaults to sending batches of 33 emails.  This equates to 400 emails per hour.

You can override the number of emails sent per batch by passing the number of emails to send in as the second parameter.

$this->emailer->process_queue(50);