Xataface Email Module

Synopsis

This module allows users to send batch emails to entire found sets of records. It supports mail-merge also so that fields from each record can be embedded into the email, customizing each email to its respective recipient.

Table of Contents

1. Requirements
2. License
3. Installation
4. Basic Usage
5. Templates
6. Using Mail-merge Fields
7. Opt-Out and Blacklists
8. Viewing the Email Log
9. Delegate Class Triggers
10. Relevant Permissions
11. Support

Requirements

1. Xataface 2.0 (or SVN development trunk rev 3121 or higher)
2. The CKeditor Module 0.3 or higher.
3. The AJAX Upload Module 0.1 or higher.

License

This module is distributed under the GNU Public License version 2

Installation

1. Install the CKeditor module (used for editing the body of email messages).
2. Install the AJAX Upload modules. (used for adding attachments to email messages).
3. Copying the Email directory into your application's (or xataface's) modules directory. I.e. the path should be modules/Email.
4. Adding the following line to the [_modules] section of your conf.ini file:

   modules_Email=modules/Email/Email.php

5. Any tables for which you want email to be enabled must implement the 'Person' ontology. To do this you just need to add the following section to the table's fields.ini file:

   [__implements__]
       Person=1

   You may also need to specify which field of the table stores the email address. You can do this by adding the email directive to the field definition for the email field in the fields.ini file:

   [email_address]
       email=1

6. If you want to allow attachments, create a directory to store the attachments, and make it writable by the web server. Then add the following section to your conf.ini file:

   [modules_Email]
           attachments=path/to/attachments
           attachments_url=url/to/attachments

At this point, you should see an email action added to your list view and to the details view of your application when browsing the table.

Basic Usage

Once the module has been installed, you can go to the list view for any table that implements the Person ontology and you should notice an email action appearing in the resultlist_actions group of actions (e.g. along side the export XML, CSV, etc.. actions). Clicking on this action will take you to a form to send an email to all of the users in the current found set.

If you want to send an email to every record in the table, then just click the email link when you haven't performed any filters or searches to your found set. If you just want to send an email to a subset of the table, then you can first perform a search on the table to narrow the results to those records that you want to send an email to, then click the email link.

If you only want to send an email to a single record you can click on the record to access it's details view, and click on the email link there.

The Email Form

After you click on the email link from either the details view or the list veiw, you'll see an email form as follows:

This form includes the following fields:

1. Template - Allows you to load a pre-written email template to start your email. See Templates for more on templates.
2. Subject - Text field to enter the subject of the email.
3. From - Text field to enter the from email address.
4. Cc - Text field to enter an optional email address to use as the bcc field for each email address. Beware that a copy of every email that is sent in this batch will be sent to this address so if you're sending to 100 records, than this Bcc address will receive 100 emails - one corresponding to each email that is sent.
5. Email Body - A CKeditor field used to edit the HTML contents of the email.
6. Ignore Blacklist

Attention

Before sending your message it is a good idea to review the Email addresses that it will be sent to. You can view the selected addresses by clicking the "Show Email Addresses" link.

Once you have filled in your message and you are ready to send it, just click the "Send" button.

This will take you to a progress page with a progress bar. It will show you the status of your job while it progresses.

Templates

Templates are useful for pre-designing emails that you may need to send periodically. You can enter the "email body", from, cc, and subject fields in a template, then load them at the time that you send the emails via the "template" field on the email form.

Creating A New Template

1. Click on "Control Panel" in the upper right (location may vary depending on your theme).
2. Click on "Manage Email" in the control panel.
3. Click on "Manage Email Templates"
4. Click "New Record" to add a new template. This will bring up the new record form for the templates table.

This form contains the following fields:

1. Table name - A select list to choose which table the template is intended to be used with.
2. Template name - A text field to enter a unique name by which the template can be referenced.
3. Email Subject - A text field to enter a default subject that can be used by emails that use this template.
4. Default From - A text field to enter the default from address for emails sent with this template.
5. Default cc - A text field to enter the default cc address for emails sent with this template.
6. Email Body - A WYSIWYG HTML editor field to enter the template content. This will be used as the default content for email messages sent with this template.
7. Template Instructions - Optional instructions for users who use this template. If you have designated particular fields to be used in this template or are performing some back-end triggers upon use of this template you may want to include that here for the benefit of users. When a user selects this template on the email form, these instructions will be displayed to the user just above the "email body" field.

Fill in the form and click "Save" when you are done.

Using Mailmerge Fields in Templates

It is sometimes desirable to customize emails with different information for each recipient. This can be achieved by embedding fields in your template that will be replaced by content from the recipients' table upon sending the mail. For example, you may want your email to begin with:

Dear {$firstname} {$lastname},

You can embed these types of fields into both templates and directly into emails using the "Insert Field" button.

In order to embed fields into a template, you must first specify which table the template will be used with using the "Table Name" pull-down list. The table that you select dictate which fields you will be able to add to the template.

On the template form you may notice a button on the toolbar to insert a field (hover over the button to see the tool-tip text).

After you have selected a table in the "Table Name" select list, click on this button to reveal a field browser for that table as follows:

Notice that when you click on a field in this browser, a macro is added to your email template at the last caret position. The macro will look something like:

{$fieldname}

These will be replaced with the content from the corresponding field at the time the email is sent. Each recipient will then see custom data that is specific to them.

Using Your Template

Now that you have created a template, you can use this every time you want to send an email of this type.

To test this out, go to a table that has email enabled and try to send a new email.

On the new email form, click on the "Template ID" field and select the template that you created.

Attention

If you do not see your template listed double check to make sure that your template was created for the same table as you are sending an email to this time.

After you have selected a template, you should see the "From", "CC", "Subject", and "Body" fields prepopulated with the contents you specified in your template. You can now make changes to the content as necessary before sending the email.

When you are satisfied with your message, you can click "Send".

Using Mail-merge Fields

Mail-merge is a feature that allows you to embed content from each individual record with email sent with the mailer module. E.g. If you want to personalize each message so that a message to Steve would say "Dear Steve" and a message to Michelle would say "Dear Michelle". To do this you would embed a macro field into your email body such as:

Dear {$firstname}

You can actually embed any field from the recipients table (i.e. the table from which the email found set is formed).

The usage for this feature on the mail form is identical to the usage on the template form see Using Mailmerge Fields in Templates for more information.

Opt-Out and Blacklists

Whenever you are sending bulk emails you should give your recipients the ability to opt out of your list. The email module supports this behavior by including a link at the foot of every email sent that says:

If you don't want to receive email updates from us, you can opt out of our mailing list by clicking here .

If the user clicks on this link, it will give them the option to add their name to the "Do Not Send" list so that they won't receive any further emails from you.

Once they click this, they receive a confirmation that they have opted out of the list:

Attention

It is important to keep the email_opt_out action accessible to the public so that users can opt out of your emails. This is the way it works by default but if you add rules in your beforeHandleRequest() method that redirect users, you may want to make sure that you leave requests for the email_opt_out action alone.

If the user changes their mind, they can opt back in by visiting the same URL at a later time.

By default all emails that you send will be checked against this "Do Not Send" list (or blacklist) to make sure that they haven't opted out. If they have opted out, the email will be skipped and it will be logged so that you are aware that the email was not sent.

Ignoring the Black List

The email form includes a checkbox labelled "Ignore Black List" that, when checked, will cause your email to disregard the blacklist rules and send the email even if the address is on the black list. It is not a good idea to abuse this ability. If people don't want to receive email from you, you had better respect their wishes. This override is there in case you absolutely need to force the email to get through despite the recipient's wishes.

Managing the Black List

You can view the black list at any time in the email management section of the control panel. There you can also add and remove addresses from the list manually.

Viewing the Email Log

The Email module logs all emails that are ever sent (unless you delete the log). You can view the email history in the "View History" section of the email management section of the Control Panel.

This section shows a list of all of the past email messages that were sent along with statistics to show how many messages where sent as part of the batch, how many succeeded, how many failed, and how many were cancelled due to the blacklist.

Clicking on a row will reveal more details about the mailout.

Each history details record also contains a log of each individual email that was sent.

This log can also be accessed immediately after sending an email by clicking on the "View Log Details" link at the foot of the progress screen.

Delegate Class Triggers

This module supports some callbacks in both the Application Delegate class and the table delegate class. See the documentation for those classes for more details.

1. ApplicationDelegate
2. TableDelegate

Configuration Directives

Every email that is sent has an opt-out message and link appended to the end of the email so that the recipient is able to opt out of your mailing list. You can override this default message to a custom message by either defining some directives in the conf.ini file or by implementing some delegate class methods.

To override the opt-out message in an HTML message you should define the opt_out_html directive in the modules_Email section of the conf.ini file.

To override the opt-out message in a Plain-text message, you should define the opt_out_text directive in the modules_Email section of the conf.ini file.

Both of these directives should contain a single variable $url which will be replaced by the link to opt out of the mailing list at run-time:

Example

[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"

Relevant Permissions

In order to access the email function a user needs to be granted the email permission on the table/record of the recipients table - and at the application level.

This permission covers most of the functions that need to be performed as part of the email module.

The "view schema" permission is required to allow the user to use the embed macro feature. It is a good idea to limit this feature to administrators that you trust as this provides detailed information about the fields that are contained in your database.

Support

See Also

http://xataface.com/forum