Previewable email templates
Installs:
337
Open Bugs:
5
Development Status:
Seeking co-maintainer(s)
Under active development
The Previewable Email Template (PET) module lets you create email templates, with token substitution, which can be previewed by the user before sending. The emails can be sent to one or many email addresses in a flexible way, and the recipients may or may not be Drupal account holders (users).
PET stores templates in a db table, not the variables table, so there is none of the memory usage which goes with the latter.
PET templates are in one place for easy management by site administrators. Emails can be sent one of three ways:
- interactively, from a link
- programmatically, in response to any situation
- via a Rules action (D7 only)
README for D7 version
Previewable Email Templates (PET)
=================================
The Previewable Email Template (PET) module lets users create email templates,
with token substitution, which can be previewed before sending. The emails can
be sent to one or many email addresses in a flexible way, and the recipients
may or may not be Drupal account holders (users).
Individual email sends can be customized per email send without affecting the
template, which makes one-off customization a breeze.
PET puts all your email templates in one place which makes for easy editing by
your users, who don't have to go into the bowels of Rules to edit an email.
Emails can also be sent programmatically by you the developer.
PET stores templates in a db table, not the variables table, so there is none
of the memory usage which goes with the latter.
PETs are based on the Entity API, which means export, import, clone, code-based
defaults, etc are supported.
PET supports the Rules module, so email actions can be triggered by any Rule.
PET supports the MimeMail module for HTML emails.
Required Modules
================
- Entity API
Optional Modules
================
- Rules
- MimeMail
Installation
============
* Copy the pet directory to the modules folder in your installation.
* Go to the Modules page (/admin/modules) and enable it.
Template Management
===================
Manage (import, add, edit, clone, delete, export) the templates for your
site from the Structure page (/admin/structure/pets). Users must have
"administer previewable email templates" permission for this.
* Title (required) - A descriptive title for the template. For reference by PET
administrators. Doesn't appear anywhere in the email itself.
* Name (required) - Machine name for the template. This is used if you refer to
your template from code.
* Subject (required) - The email subject. May contain tokens for substitution.
* Body (optional but obviously common) - The email body. Like Subject, may
contain tokens.
* From override (optional) - An alternative From address for emails originating
from this template. If not provided the site default is used.
* CC default (optional) - One or more emails to be cc'd on every email sent
using this template.
* BCC default (optional) - One or more emails to be blind cc'd on every email
sent using this template.
* Recipient callback (optional) - The name of a function which is called to
retrieve a list of email recipients, if the uid argument is 0 (not missing,
but the number 0) for an interactive send. This is a function that you
provide. If there is a nid argument, the node is loaded and passed to this
function.
Using PET Templates
===================
Once you've created a PET template, you can fire it a) interactively, b) via
code you write, or c) via Rules.
Interactive PETs
================
To send a PET interactively a user must have "use previewable email
templates" permission. The best way to get a feel for the UI when sending when
doing interactive sends is to create a template (/admin/structure/pets/add),
then click the link of the PET Label at (/admin/structure/pets). A form will
appear with the template data, and clicking the Preview button will show the
email as it will be sent, along with token substitutions if any and markup.
Clicking back allows edits to be made for this particular send, without
changing the stored template itself. When happy with the preview, click Send
email(s) to send the email.
You the developer can include a link with the path "/pet/MY_PET_NAME" anywhere
you like on your site to give your users interactive access to a template.
Interactive PETs With Substitutions
===================================
In this simple form of the path above, with no arguments provided, the user
will be required to enter one or more email addresses. User token substitutions
(if present in the template) will be made for every email that has a
corresponding user in the site. Global token substitutions will also be made.
You can provide a default user in the To field by including uid=[uid] in the
query, e.g.
/pet/MY_PET_NAME?uid=17
This will provide token substitution for user 17. Additional email recipients
can also be added to the form.
To invoke a PET for a custom list of users, specify "recipient_callback=true"
in the query, for example
/pet/MY_PET_NAME?recipient_callback=true
If the PET is set up to support user token substitution then for each email
with a corresponding drupal user the substitution will take place.
To invoke a PET with node substitution, add the node id to the arguments, e.g.
/pet/MY_PET_NAME?uid=17&nid=244
Token substitution will be done on both user 17 and node 244. Recipient
callback could be used as well, as in
/pet/MY_PET_NAME?recipient_callback=true&nid=244
For example, let's say you manage events in your site, and you wish to send an
email to all registrants reminding them of the event date. The event info is
stored in node 348 and you have a function called event_registrants($event)
which, given an event node returns an array of registrant emails. Finally, the
name of the PET template is "event_reminder". The following path would provide
an interactive way to do this send:
/pet/event_reminder?recipient_callback=true&nid=348
Firing PET Emails From Code
===========================
PET emails can also be sent from code anywhere in your site. You can do this in
response to whatever situation you have, and you have full control over the
output. The authors of this module fire PETs programmatically in response to
e-commerce purchases, class signups, event reminders, membership expirations, and
many other triggering events.
There are two functions available to programmers. See function pet_send_mail()
for sending emails to multiple recipients. See function pet_send_one_mail() for
sending email to a single recipient. These function headers contain further
documentation.
Additional tokens can be provided via hook_pet_substitutions_alter().
Triggering PET Emails From Rules
================================
If you have Rules enabled on your site (admin/config/workflow/rules) you will
see the Rules action "Send PET mail" provided by the PET module. In the action
you choose the PET template to fire, along with either a) a fixed set of email
address(es) or a recipient user provided by the Rules event. You may also
choose a node for token substitutions.
MimeMail Integration
====================
For those wanting to send HTML email, PET supports the MimeMail module. When
MimeMail is enabled, you will see additional options in the template edit form,
including a plain text email body, and a checkbox for sending plain text only.
If you leave the plain text body empty, MimeMail will perform its usual
conversion of markup to plain text using core's drupal_html_to_text(). If you
provide a plain text version of the email, it will be included in the multipart
mime email.
MimeMail also works for programmatic and Rules triggered sends.README for D6 version
The Previewable Email Template (PET) module lets you create email templates, with token substitution,
which can be previewed by the user before sending. The emails can be sent to one or many email addresses
in a flexible way, and the recipients may or may not be Drupal account holders (users).
PET stores templates in a db table, not the variables table, so there is none of the memory usage which
goes with the latter.
Required Modules
-------------------
- Token
Installation
------------
1) Copy the pet directory to the modules folder in your installation.
2) Enable the module using Administer -> Modules (/admin/build/modules)
Template Configuration
-------------
Configure (create, edit, delete) the templates for your site at Administer -> Site Building -> Previewable email templates (/admin/build/pets)
Name (required) - Machine name for the template. This is useful if you want to refer to your template from code.
Title (required) - A descriptive title for the template. Neither this nor Name appear anywhere in the email itself.
Subject (required) - The email subject. May contain tokens for value substitution (see below).
Body (optional but obviously common) - The email body. Like Subject, may contain tokens (see below).
From override (optional) - An alternative From address for emails originating from this template. If not provided
the site default is used.
CC default (optional) - One or more emails to be cc'd on every email sent using this template.
BCC default (optional) - One or more emails to be blind cc'd on every email sent using this template.
Recipient callback (optional) - The name of a function which is called to retrieve a list of email recipients, if
the uid argument is 0 (not missing, but the number 0). This is a function that you provide. If there
is a nid argument, the node is loaded and passed to this function.
Custom tokens (optional) - The standard 'node', 'user', and 'global' tokens are provided. Replacements are made for
'node' and 'user' if the nid and uid arguments, respectively, are positive integers. If you have custom token
handlers which expect an object of type 'node' or 'user', list them here.
Template Usage Via Links / UI
---------------
To invoke a PET, use the path /pet/[pet_name]. In this simple form, with no arguments provided, the user
will be required to enter one or more email addresses. User token substitutions will be made for every email
that has a corresponding user in the site. Global token substitutions will also be made.
You can provide a default user in the To field by including uid=[uid] in the query, e.g. /pet/[pet_name]?uid=17.
This will provide token substitution for user 17. Additional email recipients can be added.
To invoke a PET for a custom list of users, specify "recipient_callback=true" in the query, for example
/pet/[pet_name]?recipient_callback=true. If the PET is set up to support user token substitution then for each
email with a corresponding user the substitution will take place.
To invoke a PET with node substitution, add the node id to the arguments, e.g. /pet/[pet_name]?uid=17&nid=244.
Token substitution will be done on both user 17 and node 244. Recipient callback could be used as well, as in /pet/[pet_name]?recipient_callback=true&nid=244.
Template Usage From Code
---------------
pet_send_mail() sends email to multiple recipients. pet_send_one_mail() sends email to one recipient. See
these function headers for documentation.
CCK and Views Integration
-------
Supports the CCK field type "PET Reference", which is available when you enable the petreference module. This
field lets you stores templates specific to certain content with that content.
The petreference module also includes basic Views support, including a Views type PET, which can be used to
create Views of PETs, and support for displaying PET Reference fields in Node type Views.
Ubercart Integration
-------
PET offers a conditional action which lets you send PET-based emails instead of Ubercart action emails.
The Ubercart order tokens are available to your templates. Using PETs in this way can be useful if
a) you want a unified entry point to all your configurable email templates, or b) you send the PET email
outside the context of an Ubercart order as well as within one, and don't want to replicate your templates.
Preview
-------
When Preview is clicked, token substitution is made for the first recipient, and the email displayed. This
allows error checking. It also allows the template to be customized on a one-off basis for a send, without
altering the stored template.
To send the email(s) click Send email(s).
API
-------
pet_send_mail() can be called from code to generate email.
pet_insert() can be called from code to insert a template into the db (e.g. from an install function).Sponsor
This module is sponsored by the Human Capital Institute (http://www.hci.org).
Releases:
7.x-1.0-beta2
6.x-1.5
7.x-1.x-dev
6.x-1.x-dev
Release Dates:
11/29/2012
03/06/2012
12/20/2013
10/01/2013