Create Your Own Maillist Manager using the Xataface Email Module

Suppose you have a "contacts" table in your database that contains contact information of all of your customers or users.  It is probable that you intend to contact these by email - e.g. for a mailing list.  The Xataface Email module makes it a simple matter to use this table as a mailing list.

What it Does

The Email module adds a "Send Email" action to all designated tables that allows you to send email to all records in the current found set.

Features

• HTML Email
• Attachments
• Email templates
• Compatible with all existing found sets.  (E.g. you can perform a search for any subset of rows, and the module will send to the found set).

Prerequisites

• Xataface 2.0 or higher
• The ckeditor Module needs to be installed  (for HTML email)

Installation

1. Create a modules directory inside your application's directory, if it doesn't exist already:
   
   $ cd /path/to/my/app
   $ mkdir modules
2. Check out the latest SVN trunk of the ckeditor module into the modules directory:
   
   $ cd modules
   $ svn co http://weblite.ca/svn/dataface/modules/ckeditor/trunk ckeditor
3. Check out the latest SVN trunk of the Email module into the modules directory
   
   $ svn co http://weblite.ca/svn/dataface/modules/Email/trunk Email
4. Activate both the ckeditor and Email modules in the conf.ini file by adding the following to the [_modules] section:
   
   modules_ckeditor=modules/ckeditor/ckeditor.php
   modules_Email=modules/Email/Email.php
5. Designate the tables on which you want the "Send Email" action to be available by marking them as implementing the Person ontology.  You do this by adding the following to the beginning of the fields.ini file of each table that should be designated:
   
   [__implements__]
       Person=1
6. In addition, you may need to specify which field of the table contains the email address.  You do this by adding the email=1 directive to the field's definition in the fields.ini file.  E.g:
   
   [my_email_field]
       email=1
   
   If you don't do this, Xataface will have to try and guess which field to use - and it may be wrong!

Enabling Attachments

If you want to be able to send attachments with your email messages,  you will need to follow these additional installation steps:

1. Install the ajax_upload module.  You can do this by navigating to the modules directory, and checking out the latest from SVN:
   
   $ cd modules
   $ svn co http://weblite.ca/svn/dataface/modules/ajax_upload/trunk ajax_upload
2. Enable the ajax_upload module in your conf.ini file by adding the following to the [_modules] section:
   
   modules_ajax_upload=modules/ajax_upload/ajax_upload.php
3. Specify the location of the directory to store the uploaded files, by adding the following to your conf.ini file:
   
   [modules_Email]
       attachments=path/to/attachments
       attachments_url=url/to/attachments

Sending Email

Now that we have the module installed, let's try to send some email.  In our example application, I have a "contacts" table with all of my contacts.

The "List" view for the contacts table.  Notice the "Send Email" button, which is present because the Email module is installed and the contacts table is designated as a "Person" entity.

You can see from the result descriptor in the upper right that the current found set has 1155 records.  If you want to send an email to all 1155 contacts, just click the "Send Email" button at the top.  This will open the email form:

The email form.  The Message body uses CKeditor to allow you to craft an HTML email in WYSIWYG fashion.

Before proceeding with sending the email, you should double check that you are sending to the found set that you intend.  Look at the description at the top of the form that says "Please complete the form below to send email to the 1155 email addresses...", and ensure that the number looks right.  You should also click the "Show Email Addresses" link to reveal a list of the email addresses that will be mailed.  The worst thing you can do is accidentally send an email to thousands of people.

If you accidentally click "Send", you can still cancel or pause the email queue at any time - so there are some fail safes in place.

So let's send a simple email to all of our found set:

A simple email by filling in the subject, from, and message body fields.  Notice that the "From" field should include the email address in the standard email notation: Name <address>.

Now that we're ready, click the "Send Now" button:

This will show an email progress form to allow you to track the progress of the mailout:

You can cancel/pause the mailout at any time by clicking the "Cancel" button.  Clicking this button will take you to a "Job Paused" screen:

You can resume the job by clicking "Resume Job", and you can also view the mail log to see a detailed log of all of the email that has already been sent (by clicking "View Mail Log"):

The email history log shows every email that has been sent, along with status information about the Email.

In my example email here, it sent out 96 emails successfully before I paused it.  Logging into my email program, I can view the email:

The resulting email as opened in my Email reader

Opting Out of the Mail List

Notice that the mailer automatically added a line at the bottom of the email to give the recipient the option to "Opt out" of the mailing list.  This "opt-out" feature is built into the Email module and is handled automatically for you.  The module keeps a "black list" of email addresses that should not receive email.  When a batch email is created, it automatically skips any recipient addresses on this black list (unless you explicitly tell the Email module to ignore the black list on the email form).

Just to see what happens, I'm going to click on the link to opt out:

Form to opt out of receiving email notifications

This form gives the user an opportunity to reconsider opting out.  If they are sure that they don't want to receive email from this list, they can click the button on this form.  

They can opt back in at any time by clicking the same link that is in the email.

Customizing the Opt-Out Instructions

In some cases you might not want the user to see this opt-out message, or you may want to customize it to fit your purposes.  This can be done using either a conf.ini  file directive or a delegate class method.  For this example, let's just use the conf.ini file directives.  You can simply add the following section, and sub-directives to your conf.ini file:

[modules_Email]

opt_out_html = "<hr/><p>Click <a href='$url'>here</a> to opt out of our list.</p>"

opt_out_text = "\r\n\r\n----------------------\r\n To opt out, go to $url \r\n"

You can specify any text you want here.  Just embed the $url variable in the content where you want the link to the opt-out page to appear.