Email Triggered
The email triggered service is for inserting, updating and listing of triggered emails. To send a triggered email, see email_send.
Triggered Email Data
This is a listing of all the data for a trigger email. When using one of the methods that returns triggered email data, you will receive the majority of these. The ones marked 'Yes' in the 'Writeable' columns are values that can be written through the #insert or #update methods.
Name | Type | Writeable | Description | Note |
|---|---|---|---|---|
email_id | int | Email Campaign Id. | ||
folder_id | int | Yes | Folder in which the email is contained. | |
branding_id | int | Yes | The branding template to use when display public pages associated with the email. | |
name | string | Yes | The name of the email | |
message_type | string | Yes | The setting for the content types to use. | See #message_type |
subject_line | string | Yes | The subject line of the email | |
from_address | string | Yes | The from address used when sending the email. | |
from_address_alias | string | Yes | An alias to the from address to display a recognisable name. | |
reply_to | string | Yes | The reply to address used when the recipient replies to the email. | |
reply_to_alias | string | Yes | An alias to the reply address to display a recognisable name. | |
status | string | Yes | The status of the email. | The email progresses through several states before being sent. See #status |
encoding | string | Yes | The encoding to be applied to the email when sent. | |
source_url | string | The last url used to populate the HTML content. | ||
text_source_url | string | The last url used to populate the text content. | ||
use_opens | boolean | Yes | Whether to track opens in the email. | |
use_click_thrus | boolean | Yes | Whether to track click thrus in the email. | |
use_roi | boolean | Yes | Whether to track the recipient from the email across a web site. | Requires ROI to be enabled. |
unsubscribe_method | string | Yes | The unsubscribe method to be used | |
analytics_code | string | Yes | The analytics query string to be appended to click-throughs | |
spam_score | float | The last calculated spam score for the email. | This is null when created and requires a request to generate. | |
list_total | int | The list total for the email. | This is calculated on request and is based on lists assigned and segmentation applied. | |
total_sent | int | The total emails sent. | When the email is sending this statistic changes as emails are sent. | |
total_opens | int | The total number of opens. | Only displayed when the email is in progress or complete. | |
total_unique_opens | int | The total number of unique opens. | Only displayed when the email is in progress or complete. | |
total_clickthrus | int | The total number of click thrus. | Only displayed when the email is in progress or complete. | |
total_unique_clickthrus | int | The total number of unique click thrus. | Only displayed when the email is in progress or complete. | |
total_responses | int | The total number of responses. | Only displayed when the email is in progress or complete. | |
total_bounces_soft | int | The total number of soft bounces. | Only displayed when the email is in progress or complete. | |
total_bounces_hard | int | The total number of hard bounces. | Only displayed when the email is in progress or complete. | |
total_tracking_hits | int | The total number of web site pages hits (ROI). | Only displayed when the email is in progress or complete. | |
total_roi_conversions | int | The total number of recipients hitting the coversion page (ROI). | Only displayed when the email is in progress or complete. | |
total_roi_revenue | float | The total revenue generated (ROI). | Only displayed when the email is in progress or complete. | |
total_unsubscribes_local | int | The total number of local unsubscribes. | Only displayed when the email is in progress or complete. | |
total_unsubscribes_global | int | The total number of global unsubscribes. | Only displayed when the email is in progress or complete. | |
total_unsubscribes_feedback | int | The total number of feedback unsubscribes. | Only displayed when the email is in progress or complete. | |
update_ts | datetime | Date and time the list was last updated. |
message_type
This controls the content types that will be used for the email send.
Value | Description |
|---|---|
both | default Both HTML and text content |
html | |
text |
unsubscribe_method
Value | Description |
|---|---|
link | default Single-click |
form | Confirmation request |
status
Unlike Email_Campaign the status are limited, as once set to 'approved' the email is finalised and cannot be set back to 'draft'.
Value | Description |
|---|---|
draft | default Email can be edited |
for_approval | Email is locked from editing, but can be set back to draft |
approved | Email can be triggered for live sends and is now locked |
fetchAll
array email_triggered.fetchAll( int folderId )Returns a list of triggered emails under the specified folder. It is usually better to use the tree structure, see tree.fetchNode.
Parameters
folderId
The folder from which to select the emails.
Return Values
Returns an array of associative arrays. For the possible returned elements see #Triggered Email Data.
find
array email_triggered.find( int emailId )Requests the triggered email details of the single email id requested.
Parameters
emailId
ID of the triggered email you're requesting.
Return Values
Returns an array of associative arrays. For the possible returned elements see #Triggered Email Data
insert
int email_triggered.insert( array data )Inserts a new triggered email.
Parameters
data
See #Triggered Email Data for the values that can be written. Only the name and folder_id are required. All other writeable elements are optional.
Return Values
Returns an associative array:
Key | Type | Description |
|---|---|---|
email_id | int | The ID of the newly created email |
folder_id | int | The ID of the folder. |
update
bool email_triggered.update( int emailId, array data )Updates an existing triggered email using the data specified.
Parameters
emailId
The ID of the triggered email.
data
See #Triggered Email Data for the values that can be written. All elements are optional.
If you wish to move the triggered email to a new folder, set the folder_id element.
Return Values
Returns a bool. True on success.
delete
bool email_triggered.delete( int emailId )Deletes the specified triggered email.
This will delete anything associated with the email.
If the email is complete it will also delete all associated statistics.
Any feedback from recipients will also be lost.
Parameters
emailId
ID of the triggered email you want to delete.
Return Values
Returns a bool. True on success.
copy
array email_triggered.copy( int emailId, string name, int folderId )Copy an existing triggered email to a new folder/name.
Parameters
emailId
ID of the triggered email to be copied.
name
Name of the new triggered email.
folderId
ID of the folder where the new triggered email should be created.
Return Values
Returns an associative array. See #insert.
storeContent
array email_triggered.storeContent( int emailId, string type, string source, array options )Sets the message for the triggered email of type specified in the parameter.
Parameters
emailId
ID of the triggered email.
type
The specific message content you want to set. This can either be 'html' or 'text'.
Depending on the type specified further options can be added to the options parameter specified below.
html
Name | Description |
|---|---|
modify_headers | Describes whether the header tags within the HTML should be altered to fit other options specified. |
htmltidy | This allows you to specify a range of options to the HTML Tidy utility. |
text
Name | Description |
|---|---|
lineendings | Describes the type of lineendings used in the text content message. |
source
The way in which the message content should be set. This can be string, uri, fileupload or generated.
Name | Description |
|---|---|
string | The message is specified as a parameter as part of the method call. See options below. |
uri | The message is retrieved via a specified URI. |
fileupload | The message is retrieved via a previous file upload using the file upload service. |
generated | The text content of the message is generated from HTML content already existing on the email campaign. |
options
Each source has specific options. These are outlined below.
string
Name | Description |
|---|---|
content | The actual HTML message to loaded against the email specified email. |
encoding | The character encoding used to save the message. |
uri
Name | Description |
|---|---|
uri | The URI where the HTML or Text is located to retrieve the content from. |
encoding | The character encoding used to save the message. |
fileupload
Name | Description |
|---|---|
key | The key generated from the file upload service. |
encoding | The character encoding used to save the message. |
generated
There are no options available for the 'generated' source. This assumes a HTML message exists on the email campaign and uses that to generate the source of the Text content.
Return Values
Returns an array of validation warning messages.
Any errors would be handled as exceptions in the usual way for the API.
getContent
array email_triggered.getContent( int emailId, string type )Retrieves the message from the triggered email of type specified in the parameter.
Parameters
emailId
ID of the triggered email.
type
The specific message content you want returned. This can either be 'html' or 'text'.
Return Values
Returns a string of the message content requested.
Service
email_triggered
Methods