Email Campaign

The email campaign service is for inserting, updating and listing of campaign emails.

Email Campaign Data

This is a listing of all the data for an email campaign. When using one of the methods that returns email campaign 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.
campaign_id	int	Yes	Campaign the email is attached to.	See note in #insert when creating new email campaign
template_id	int	Yes	The email template used to create the email.	Can be used in #insert to create an email from a template.
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.
sample_size	int	Yes	When the email is based in a variable campaign the sample size is applied to the assigned lists.
scheduled_ts	datetime	Yes	The scheduled start time of the email	Only used when the status of the email is approved.
start_ts	datetime		The time the email started to send.
finish_ts	datetime		The time the email completed send.
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	See #unsubscribe_method
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

There are many status available - the 'Writeable' column shows the status that can be set through #insert or #update.

Value	Writeable	Description
draft	Yes	default Email can be edited
for_approval	Yes	Email is locked from editing, but can be set back to draft
approved	Yes	Set email to send at scheduled time
checking_credits		Part of the scheduling process
insufficient_credits		Error. Email must be set back to draft, for_approval or approved once more credits are assigned
scheduled		Email will send at the scheduled time. Email can be set back to draft, for_approval or approved.
generate_pending		Part of the scheduling process
generating		Part of the scheduling process
sending		Email is being sent. Possible to set to request_pause
request_pause	Yes	Request the email to be paused.
paused		Pause request has been actioned and email is not currently sending
continue_send	Yes	Continue the email send. Can only be set when status is paused
cancelled	Yes	Email send has been cancelled. Can only be set when status is paused
error		Email send has encountered an error. This is not recoverable and you must contact Support.
complete		Email send completed successfully

fetchAll

array email_campaign.fetchAll( int campaignId )

Returns a list of email campaigns under the specified campaign. If you are looking to retrieve a list of emails in a folder, see tree.fetchNode.

Parameters

campaignId

The campaign from which to select the emails.

Return Values

Returns an array of associative arrays. For the possible returned elements see #Email Campaign Data.

fetchByFilter

array email_campaign.fetchByFilter( array filter, int limit, int start, string sort, string dir )

Returns a list of email campaigns based on the filter options. Simliar to list.fetchRecipients

Parameters

filter

Associative array of filter options. Each filter criteria is optional. Results are returned that match all criteria defined.

Key	Type	Description
status	string/array	status of the email campaign, see #Email Campaign Data
update_ts	timestamp	yyyy-mm-dd hh:mm:ss
start_ts	timestamp/array	Single timestamp in format yyyy-mm-dd hh:mm:ss for lower limit, or indexed array of lower and upper limits

limit

The number of records to be returned. If greater than 5000, a value of 5000 will be used.

start

The starting record from which to retrieve limit rows.

sort

Field on which to sort the data.
eg. 'start_ts'

dir

The sort direction. Either 'ASC' or 'DESC'.

Return Values

Returns an array of associative arrays. For the possible returned elements see #Email Campaign Data

find

array email_campaign.find( int emailId )

Requests the email campaign details of the single email id requested.

Parameters

emailId

ID of the email campaign you're requesting.

Return Values

Returns an array of associative arrays. For the possible returned elements see #Email Campaign Data

findByIdArray

array email_campaign.findByIdArray( array data, array filter )

Requests a list of email campaigns belonging to the node IDs requested, filtered by date.

Parameters

data

An associative array of arrays. All keys are optional.

Key	Type	Values
folders	array	folder IDs
campaigns	array	campaign IDs
emails	array	email IDs

filter

An associative array of arrays. All keys are optional.

Key	Type	Values
startDate	timestamp	email start_ts greater than this datetime
endDate	timestamp	email start_ts less than this datetime

Return Values

Returns an array of associative arrays. For the possible returned elements see #Email Campaign Data

calculateListTotal

bool email_campaign.calculateListTotal( int emailId )

Calculates the total number of recipients the email campaign will be sent to based on the include, exclude and segmentation applied.

Parameters

emailId

The ID of the email.

Return Values

Returns a bool. True on success.

getListTotal

int email_campaign.getListTotal( int emailId )

Returns the total number of recipients the email campaign will be sent to based on the include, exclude and segmentation applied.

Parameters

emailId

The ID of the email.

Return Values

Returns a number of recipients being sent to. There are some special values for consideration:

Value	Description
-1	The list total is still being calculated
-2	The list total hasn't been calculated

insert

int email_campaign.insert( array data )

Inserts a new email campaign.

Parameters

data

See #Email Campaign Data for the values that can be written. Only the name and campaign_id OR folder_id are required (see note below). All other writeable elements are optional.

If you are not inserting the email campaign into an existing (non-standard) campaign, then you should set the folder_id rather than the campaign_id. In this case a standard campaign is created automatically.

Return Values

Returns an associative array:

Key	Type	Description
email_id	int	The ID of the newly created email
campaign_id	int	The ID of the campaign.

update

bool email_campaign.update( int emailId, array data )

Updates an existing email campaign using the data specified.

Parameters

emailId

The ID of the email campaign.

data

See #Email Campaign Data for the values that can be written. All elements are optional.

If you wish to move the email campaign to a new folder, set the folder_id element.
Please see the notes in #insert.

Return Values

Returns a bool. True on success.

delete

bool email_campaign.delete( int emailId )

Deletes the specified email campaign.

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 email campaign you want to delete.

Return Values

Returns a bool. True on success.

copy

array email_campaign.copy( int emailId, string name, string destinationType, int destinationId )

Copy an existing email campaign to a new folder/name. Please note the two parameters required to specify the destination as a campaign or folder. This works in a similar way as described in #insert.

Parameters

emailId

ID of the email campaign to be copied.

name

Name of the new email campaign.

destinationType

Type of destination.

Value	Description
campaign	email copied to an existing campaign
folder	email copied to an existing folder. A standard campaign will automatically be created

destinationId

ID of the folder or campaign where the new email campaign should be created.

Return Values

Returns an associative array. See #insert.

getSeedRecipients

array email_campaign.getSeedRecipients( int emailId )

Retrieves a list of recipients assigned to the email who are marked with a record type of both or seed. This depends on the lists assigned to the campaign.

Parameters

emailId

ID of the email campaign.

Return Values

Returns an indexed array of email addresses of recipients.

Deprecated

This method has been deprecated and will be removed in a future version. For an alternative, see email_campaign.storeContent()

setContent

boolean email_campaign.setContent( int emailId, string type, string source, array options )

Sets the content for the email campaign of type specified in the parameter.

Parameters

See #storeContent.

Return Values

Returns a boolean true.

storeContent

array email_campaign.storeContent( int emailId, string type, string source, array options )

Sets the content for the email campaign of type specified in the parameter.

Parameters

emailId

ID of the email campaign.

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.
host_images	Images with absolute URLs will be uploaded to the Image Library, and the HTML content altered to use the new URL (requires Image Library feature enabled)

text

Name	Description
lineending	Describes the type of lineendings used in the text content message.

source

The way in which the content should be set.

Value	Description
string	The content is specified as a parameter as part of the method call. See options below.
uri	The content is retrieved via a specified URI. Relative URLs are modified to absolute, based on the source URL.
fileupload	The content is retrieved via a previous file upload using the file upload service.
template	The content is copied from an email template.

options

Each source has specific options. These are outlined below.

string

Name	Required	Description
content	Required	The actual HTML message to loaded against the email specified email.
encoding	Optional	The character encoding used to save the message. Defaults to UTF-8.

uri

Name	Required	Description
uri	Required	The URI where the HTML or Text is located to retrieve the content from.
encoding	Optional	The character encoding used to save the message. Defaults to UTF-8.

fileupload

Name	Required	Description
key	Required	The key generated from the file upload service.
encoding	Optional	The character encoding used to save the message. Defaults to UTF-8.

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_campaign.getContent( int emailId, string type )

Retrieves the message from the email campaign of type specified in the parameter.

Parameters

emailId

ID of the email campaign.

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.

exportReport

array email_campaign.exportReport( int emailId, string type )

Generates a report on the email campaign, which can then be downloaded.

Parameters

emailId

ID of the email campaign.

type

The report type to be generated.

Value	Description
pdf	A multipage report in PDF format, containing items as seen in the email's 'Reporting' tab in the user interface

Return Values

Returns the file download key.

The report can then be downloaded by using the following URL:

https://<server>/download/file/key/<key>

Where:

Placeholder	Value
server	Hostname of your server
key	The file download key returned

Service

email_campaign