Triggered Emails

Introduction

Triggered Emails are designed for use in what might be considered 'transactional' situations. This might be something like: a registration confirmation (the scenario we'll discuss below); an order confirmation; or even an incomplete basket reminder, which is sent a set amount of time after the recipient's last page view.

All the above situations have one key factor in common: they are sent immediately, or with a defined delay, to a single recipient. If you are considering sending an email to a changing batch of recipients at periodic intervals, then please look at Recurring campaigns.

Scenario

The example we're going to look at is a fairly basic start to triggered emails - the registration confirmation. The specification requires that the email is delivered immediately following the recipient entering their details on your site, with a unique link to confirm their email address to you, and that the email have a personalised salutation.

The more complex example of an order confirmation would be based from this, but probably use Dynamic Content to include a variable number of basket items within the email. An incomplete basket notification would be similar, but make use of a trigger delay, so the email is sent after a given number of seconds from you making the API request.

Initial Setup

The first steps will use the interface - it would likely be a waste of your time to program these steps through the API, when you can just click the required buttons instead! We're not going to cover how to navigate around the interface here, please see the Maxemail User Guide.

Email

Create the Triggered Email, set all the properties and content.

We'd probably recommend putting this in a folder, named appropriately for this campaign. To be able to instruct a Triggered Email to send, it needs to have been parsed and generated by the system. This requires the email to be set to 'Approved' status (once you've done all the usual testing of course!) but it then cannot be put back to 'Draft', so any further changes will require a new version of the Triggered Email. This is the reason for the folder, to contain these related Triggered Emails, which may all have logged opens and clicks that your marketers will want to refer back to in future.

For the registration email, our content might look something like this:

<p>Hi [recipient:Personal.Firstname;new user]!<br />
<br />
Thanks for registering your details on <a href="http://www.example.com/" target="_blank">MySite</a>!<br />
<br />
To confirm your email address, please click on this link:<br />
<a href="http://www.example.com/register/auth/[recipient:Registration.AuthCode]/" target="_blank">Confirm my email address</a></p>

Profile Fields

You'll notice the use of a couple of Content Tokens to bring data from the recipient's profile fields. These need to be set up in advance, so if they don't already exist, you need to create a profile called 'Personal' and a text field within it called 'Firstname', and a profile 'Registration' with another text field called 'AuthCode'.

The API

Once the above is set up, and the email is approved, it is ready to be triggered. Triggered Emails are very simple in that they just require the use of email_send.trigger, which requires the Triggered Email's ID, the recipient's email address, and the profile data you wish to set for the email content.

However as mentioned before, once a Triggered Email has been marked as Approved, any new revision will require a new Triggered Email to be created, which would require you to update the email_id in your app. For this reason, we recommend using the email_send.triggerFolder method. This takes the ID of the folder containing the Triggered Emails for this campaign. Once called, it takes a single approved Triggered Email from the folder and sends it to the given recipient with the given profile data. Older revisions of Triggered Emails for this campaign can be safely put in an archive sub-folder, as this method only considers immediate children when picking the email to send, rather than all descendants.

$folderId = 123;
$emailAddress = 'bob@example.com';
$profileData = array(
    'Recipient' => array(
        'First Name' => 'Bob'
    ),
    'Registration' => array(
        'AuthCode' => 'abc123def456'
    )
);
$result = $api->email_send->triggerFolder($folderId, $emailAddress, $profileData);