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.
- HTML Email
- 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).
- Create a modules directory inside your application's directory, if it doesn't exist already:
$ cd /path/to/my/app
$ mkdir modules
- 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
- 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
- Activate both the ckeditor and Email modules in the conf.ini file by adding the following to the [_modules] section:
- 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:
- 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:
If you don't do this, Xataface will have to try and guess which field to use - and it may be wrong!
If you want to be able to send attachments with your email messages, you will need to follow these additional installation steps:
- 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
- Enable the ajax_upload module in your conf.ini file by adding the following to the [_modules] section:
- Specify the location of the directory to store the uploaded files, by adding the following to your conf.ini file:
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:
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"