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, and they use largely the same content which can be pre-defined in Maxemail. If you are considering sending an email to a changing batch of recipients at periodic intervals, then please look at Recurring campaigns.
Each API call to trigger the email only needs the recipient email address, any associated profile data (such as name) and the ID for the email to trigger. The recipient will be added to your Customer Space if it doesn't already exist, the profile data set, and the email to them queued for send.
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.
Put the Triggered Email in a folder, named specifically 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'.
Dynamic content
You can store whole blocks of content in a profile field but this is not recommended. This is because the content will not be rendered and any links within these will not be tracked.
It is better to keep as much static content as possible in the email content, and merge dynamic parts with individual Profile Fields.
The API
Once the above is set up, and the email is approved, it is ready to be triggered. The simplest solution is to just use email_send.trigger with the Triggered Email's ID, the recipient's email address, and the profile data you wish to set for the email content.
However, to allow the marketer to create new revisions by adding new Triggered Emails, you would need to update the email_id in your app. So instead, 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 = '[email protected]';
$profileData = array(
'Recipient' => array(
'First Name' => 'Bob'
),
'Registration' => array(
'AuthCode' => 'abc123def456'
)
);
$result = $api->email_send->triggerFolder($folderId, $emailAddress, $profileData);