MySource Matrix Developer

Content Tools

Main Content

A Quick Guide to the Bulkmail Package

Introduction

The purpose of the Bulkmail Package is to allow MySource Matrix content to be sent to users via email, either once off or on a scheduled basis. Examples of usage for this package include weekly newsletters, promotional mailouts, subsciber emails etc. This article shows you how to quickly setup a bulkmailer in your system.

Written by Rayn Ong on 06 Jun 2006

Requirement

Before you start, make sure that you have the required PEAR packages installed by running "pear list" command.

  • Mail (at least 1.1.4)
  • Mail_Mime
  • Mail_Queue
If you are using Mail 1.1.3, you will get an error like the following when you preview a Bulkmail Job because header key comparison was case-sensitive."Post Office Server Details Error: Unable to send preview mail, No from address given. [BML0002]".

The Bulkmailer also uses PHP process control support, so you have to compile the CGI or CLI version of PHP with --enable-pcntl configuration option.

If you are using an Oracle DB, the latest PHP oci8 extension is also required. You can refer to the PHP manual for more information.

Component of the Bulkmail Package

The Bulkmail Package consists of four major components - Bulkmail Manager, Bulkmail Post Offices, Bulkmail Jobs and the Bulkmailer. The Bulkmail Manager will be created as a system asset when you install the bulkmail package in your system. To quickly get your bulkmail system running, you should create a Bulkmail Post Office, a Bulkmail Job and the crontab for the Bulkmailer at a minimum.

Bulkmail Post Office

The post offices provide the ability to create default options for the jobs beneath it. If all your jobs have the same recipients or the same headers, then you would set those in the post office and the jobs beneath it would inherit the values. You can override the post office values on a job-by-job basis.

Please note that if you do not specify a post office, the default system post office will be used (located in System Management -> Bulkmail Manager -> Default Bulkmail Post Office).

Server Details

The basic purpose of these assets is to define the settings of the email server you will be sending all the emails through. This can be an SMTP server on the local/remote machine, or alternatively you can just use sendmail on the local machine. If you have a number mail servers you use for different purposes, you would have a post office defined for each.

Header Details

The Header Details Section allows you to specify the header values of the mailout. You may use the standard asset keywords as header values. Please visit the documentation page for a complete list of available keywords. The 'From' and 'Subject' field must be filled in order for the mailout to work.

It is important to note that if the mailout is going to be a HTML based email, you will need to add a Content-Type header with value text/html; charset="iso-8859-1"
Threshold Settings

Additional rules may be defined for all Bulkmail Jobs beneath this Post Office. For example, the Excluded Time rule is where you define a "black out" period so that no jobs will be processed, it is particularly useful to ensure that the mailouts do not get sent during peak hours.

Bulkmail Job

The Bulkmail Job defines which content is being sent, as well as the recipients, headers, and content generation type. The job can also inherit the values of the post office it is linked under (note that jobs can only be linked under ONE post office). The process for setting up a job is as follows:

  1. Create the job under a post office.
  2. Configure the recipents.
  3. Select the content that you want to send and the content generation type.
  4. Configure the header details or choose to inherit from the Post Office.
  5. Start the job by setting the status to Live
If the Cron Manager has been enabled on your system, you may use the future status options to set the Bulkmail Job to Live on a certain date in the future.
Recipients

You may use the multiple asset finder to select users or user groups you wish to send the email to. Problematic users that are not Live or without an email address will not receive the mailouts.

Content and Content Generation

You may select the asset to send as the bulkmail content in Asset to Send, this can be a Page asset or any asset of its decendent types.

The bulkmail system provides user keyword replacements which means your content page can contain any of the keywords available in the recipient asset. To use these keywords, they are prefixed with "recipient_". For example, %asset_name% would become %recipient_asset_name%.

The Generate As option allows you to specify a user to be used to generate content for all recipients based on his read/write/admin access, if the Generation Method option is set to "Generate as set user". If the Generation Method option is set to "Generate as recipient", the bulkmailer will generate content for each recipient. The user specified above will be used if the bulkmailer failed to generate content for a specific user.

Finally, you may use the asset finder to select the Design and the Layout to be applied to the content. One other thing to make sure of is that your Designs and Layouts are Live and have public read permissions turned on, and the same with any images that will appear in the content. One of the major problems with sending out HTML emails with image content is that when 100,000 people receive the email they will open it and your server will be brought to its' knees. One way to prevent this from happening is by using a separate server to serve your files (configure the SQ_CONF_STATIC_ROOT_URL option). For further details on how this is done, please contact Squiz support.

Header Details

You may inherit the settings in the Post Office by selecting Use Post Office Header Details option or you may choose to overwrite the Post Office header detail settings by defining your own.

Bulkmailer

The bulkmailer is setup to run via CRON every x minutes. When the bulkmailer detects a job that needs to be run, it will get all the information it needs, generates the content, and sends all the emails. To set up the bulkmailer to run every 15 minutes, you will need to create a cron entry (running as www-data or apache) as follows:

*/15    *    *    *    *    php /path_to_matrix/packages/bulkmail/run.php

Run "man 5 crontab" for more information on scheduling using cron.

Bulkmail Manager

The Bulkmail Manager provides an interface to view all queued/running jobs in the system. Jobs can be paused, resumed or cancelled from this interface. The interface is available in post offices (you can view all jobs which are being sent through a particular post office), and in the job asset too. Progress of all jobs in the system can be monitored via the Bulkmail Manager as well.

If you resume a paused job, it will not be processed until the next run of the bulkmailer.