SmartFocus Cloud Service APIs

(1)

Service

Campaign management for managing email campaigns

Protocol

REST over HTTP

Version

11.8

(2)

Introduction

About This Document

This document is a reference document for using SmartFocus APIs. It does not explain the purpose or functions of SmartFocus features. For information on these features, please consult theSmartFocus Online Helpor theSmartFocus User Guide. This document is intended for developers and project managers.

About SmartFocus APIs

An Application Programming Interface (API) is a source code interface that a computer system or program library provides in order to support requests for services made from another computer program.

The goal of SmartFocus APIs is to offer customers the ability to pilot a complete campaign from their own system.

Feedback

The Campaign Management REST API Guide is constantly being enhanced to provide you with more and more information on using SmartFocus API methods.

If you can't find the information you need or want to provide feedback, simply drop us a line at [email protected].

We look forward to hearing from you!

Support Options

SmartFocus provides you with a dedicated Account Manager to accompany you throughout the execution of your projects in SmartFocus. Your Account Manager is the gateway to support, training, and professional services. Working with your Account Manager, you can rely on SmartFocus’s deliverability and technical support teams for complex troubleshooting and

optimization.

Training Options

SmartFocus provides fully comprehensive training ranging from basic product training through to advanced modules and both strategic and tactical marketing courses. The training courses are designed to help you increase productivity, develop new methods, and share best practices to optimize your email, mobile, and social marketing campaigns.

To get more information on training, please contact your Account Manager.

SmartFocus's Products and Services

For more information on SmartFocus's products and services, please seewww.smartfocus.com

Disclaimer

While the information contained in this publication is believed to be true and accurate, SmartFocus cannot accept any legal responsibility for any errors or omissions contained herein. All information is subject to change without notice.

(8)

Overview of the Campaign Management API

The Campaign Management API allows you to:

l Create, edit, and delete email and SMS Messages l Create, edit, and delete Dynamic Content Blocks

l Add, edit, track, and untrack Message and Dynamic Content Block links l Create, edit, and delete Segments

l Retrieve lists of Messages, Dynamic Content Blocks, and Campaigns

For further information on how to create, edit, and manage campaigns, please consult theSmartFocus User Guideor SmartFocus Online Help.

The following methods are available: l Connection

Method Description

Open Connection This method provides a session token when given valid credentials. Close Connection This method terminates the session token.

l Message

Create Email Message This method creates an email. Create SMS Message This method creates an SMS message. Create Message (POST) This method creates an email. Delete Message This method deletes a message. Update Message This method updates a message field.

Update Message (POST) This method updates an email or SMS message. Clone Message This method clones a message.

Get Message This method retrieves a message by its ID.

Get Last Email Messages This method retrieves the list of the last emails created. Get Last SMS Messages This method retrieves the last SMS messages created.

Get Email Messages by Field This method retrieves a list of emails that contain the given value in the specified field.

Get SMS Messages by Field This method retrieves a list of SMS messages that contain the given value in the specified field.

Get Messages by Period This method retrieves a list of messages from a given period. Get Email Message Preview This method provides a preview of an email.

Get SMS Message Preview This method provides a preview of an SMS message. Track All Links This method activates tracking for all links in an email. Untrack All Links This method deactivates link tracking for all links in an email. Track Link by Position This method tracks a link based on its position in an email. Untrack Link by Order This method untracks a link based on its order number. Get All Tracked Links This method retrieves a list of all the tracked links in an email.

(9)

Test Email Message on a

Group This method sends a test email campaign to a group of recipients. Test Email Message on a

Member This method sends a test email campaign to a member. Test SMS Message This method sends a test SMS message to a member.

Get Default Sender This method retrieves the email address of the default sender for the SmartFocus account.

Get Validated Alternate Senders

This method retrieves the list of validated alternate senders for the SmartFocus account.

Get Unvalidated Senders This method retrieves the list of the unvalidated alternate senders for the SmartFocus account.

URL

Note:To create or add links in REST, you must use the HTTP GET Query String (QS) format: l HTTP GET QS (Query String):

o The query string is composed of a series of field-value pairs. o The field-value pairs are each separated by an equals sign (=). o The series of pairs is separated by the ampersand (&).

o Below is an Internet browser URL location bar showing a URL where the Query String is: title=Main_page&action=raw

o API call summary: HTTP GET (Query String) Submission & sample URL call:

http://{server}/apiccmd/services/rest/campaign/get?token={token}&id={email}

l Segment

Create Segment

This method creates a segment.

Note:It is imperative that your segment contains members and that all necessary criteria is defined. If a segment without criteria is used in a campaign, all members in the database will be selected.

Delete Segment This method deletes a segment. Update Segment This method updates a segment. Add String Demographic

Criteria to a Segment This method add alphanumeric demographic criteria to a segment. Add Numeric Demographic

(10)

Add Trigger Campaign

Action Criteria to a Segment This method adds Trigger Campaign action criteria to a segment. Add Trigger Campaign

Trackable Link Criteria to a Segment

This method adds Trigger Campaign tracked link criteria to a segment. Add Social Criteria to a

Segment This method adds social criteria to a segment. Add Recency Criteria to a

Segment This method adds quick segment criteria to segment. Add DataMart Criteria to a

Segment This method adds DataMart criteria to a segment. Include or Exclude a

Segment from Another Segment

This method includes or excludes an existing segment in the criteria of a new segment. Get Segment by ID This method retrieves a segment by its ID.

Get Segment List This method retrieves a list of segments.

Get Segment Criteria This method retrieves the criteria used in a segment. Get DataMart Segment List This method retrieves a list of DataMart segments. Delete Segment Criteria This method deletes a criteria cell from a segment. Update the String

Demographic Criteria of a Segment

This method updates alphanumeric demographic criteria. Update the Numeric

This method updates numeric demographic criteria. Update the Date

This method updates date demographic criteria. Update the Campaign Action

Criteria of a Segment This method updates campaign action criteria. Update the Campaign

Trackable Link Criteria of a Segment

This method updates campaign tracked link criteria. Update the Trigger

Campaign Action Criteria of a Segment

This method updates Trigger Campaign action criteria. Update the Trigger

Campaign Trackable Link Criteria of a Segment

This method updates Trigger Campaign tracked link criteria. Update the Social Criteria of

a Segment This method updates social criteria. Update the Recency Criteria

of a Segment This method updates quick segment criteria. Update the DataMart

(11)

Count Segment This method counts the total number of members in a segment (including duplicated members).

Count Distinct Segment Members

This method counts the total number of distinct members in a segment (i.e. duplicate members are removed).

l Campaign

Create Campaign This method creates a campaign. Create Campaign with

Analytics

This method creates a campaign with analytics activated. It uses the analytics settings set up for the account.

Create Campaign (POST) This method creates a campaign by object. Delete Campaign This method deletes a campaign.

Update Campaign This method updates a campaign. Update Campaign (POST) This method updates a campaign. Post Campaign This method posts a campaign.

Unpost Campaign This method unposts a posted campaign. Get Campaign This method retrieves a campaign.

Get Campaigns by Field This method retrieves all campaigns that match a given value in a specified field. Get Campaigns By Status This method retrieves a list of campaigns having a specified status.

Get Campaigns By Period This method retrieves a list of campaigns from a specified period. Get Campaign Status This method retrieves a campaign's status.

Get Last Campaigns This method retrieves the most recent campaigns.

Test Campaign on a Group This method sends a test campaign to a group of members. Test Campaign on a

Member This method sends a test campaign to a member. Pause Campaign This method pauses a running campaign.

Unpause Campaign This method unpauses a paused campaign. Get Campaign Report This method retrieves a campaign's report. Get Campaign Snapshot

Report This method retrieves a snapshot report for a campaign. l Dynamic Content

Create Dynamic Content Block This method creates a Dynamic Content Block. Create Dynamic Content Block

(POST) This method creates a Dynamic Content Block by object. Delete Dynamic Content Block This method deletes a Dynamic Content Block.

Update Dynamic Content Block This method updates a Dynamic Content Block by field and value. Update Dynamic Content Block

(12)

Get Dynamic Content Blocks by Field This method retrieves a list of Dynamic Content Blocks that contain the same given value in a specific field.

Get Dynamic Content Blocks by

Period This method retrieves a list of Dynamic Content Blocks from a given period. Get Last Dynamic Content Blocks This method retrieves the list of the last Dynamic Content Blocks created. Track All Dynamic Content Block

Links

This method activates tracking for all untracked Dynamic Content Block links and saves the Dynamic Content Block.

Untrack All Dynamic Content Block

Links This method untracks all the Dynamic Content Block links.

Track Link by Position This method tracks the Dynamic Content Block link through its position in the Dynamic Content Block.

Untrack Dynamic Content Block Link

by Order This method untracks a link in the Dynamic Content Block by its order. Get All Dynamic Content Block

Tracked Links This method retrieves a list of all the tracked links in a Dynamic Content Block. Get All Unused Dynamic Content

Block Tracked Links

This method retrieves a list of all the unused tracked links of the Dynamic Content Block.

Get All Dynamic Content Block

Trackable Links This method retrieves a list of all the trackable links in a Dynamic Content Block. l Dynamic Content Link

Note:To create or add links in REST, you must use the HTTP GET Query String (QS) format: l HTTP GET QS (Query String):

o Below is an Internet browser URL location bar showing a URL where the Query String is: title=Main_page&action=raw

l Webforms

Create a Webform This method creates a new Webform. Update a Webform This method updates a Webform.

Copy a Webform This method makes a copy of an existing Webform. Update a Webform's Status This method updates a Webform's status.

(13)

Create a Test Member This method creates a test member using an email address.

Create an SMS Test Member This method creates a test member using their email address and mobile telephone number.

Delete a Test Member This method deletes a test member.

Get a Test Member This method retrieves a test member's details. Get Test Members This method retrieves the test members. Create a Test Group This method creates a test group of members. Create a Test Group (POST) This method creates a test group.

Delete a Test Group This method deletes a test group. Add Test Member to a Test

Group This method adds a member to a test group. Remove Test Member This method removes a member from a test group. Update a Test Group (POST) This method updates a test group.

Get Test Group This method retrieves the list of members in a test group. Get All Test Groups This method retrieves the list of test groups for your account.

Campaign Management API Use Cases

Message Use Cases

Create an Email, Ad d an Un s u b s crib e Lin k, an d Track All Lin ks

To create an email, add an unsubscribe link, and track all the email links, you would use the following methods in the following sequence:

1. Use the Open Connection method to open the connection.

2. Use the Create Message (POST) method to create your email. Make sure that your email content contains three ampersands (&&&) for the unsubscribe link.

3. Use the Create and Add Unsubscribe Link method to create and add an unsubscribe link. 4. Use the Track All Links method to track all the links in your email.

5. Use the Test HTML Validity method to check whether the HTML in your email is valid. 6. Use the Close Connection method to close the connection.

Clo n e an Email an d Ed it th e Co p ied Email To clone an email in order to create a new email:

2. Use the Get Messages by Period method to retrieve the list of Messages from which to choose the Message to clone. 3. Use the Clone Message method to copy the Message.

4. Use the Update Message (POST) method to edit the Message.

(14)

2. Use the Get Messages by Period method to retrieve the list of Messages from which to choose the Message for the campaign.

3. Use the Get Segment List method to retrieve the list of Segments from which to choose the Segment for the campaign.

4. Use the Create Campaign (POST) method to create the campaign. 5. Use the Post Campaign method to post the campaign.

6. Use the Close Connection method to close the connection.

Test Group Use Cases

Create a Tes t Gro u p To create a test group:

2. Use the Create a Test Group (POST) method to create the test group with the members. 3. If you want to add additional members, use the Add Test Members to Test Group method. 4. Use the Close Connection method to close the connection.

(15)

Getting Started with Integration

Prerequisites

To access SmartFocus’s APIs and take full advantage of this software’s ease of integration with other systems, you will need the following:

l An Internet connection

l A recent browser and operating system

l An active SmartFocus account with the API feature enabled

Quick Start

The process for interfacing your website, CRM, or any other internal system with the APIs is quite straightforward. Step 1: Get your API key in SmartFocus

Note:You must have a dedicated API login. This login will NOT have access to SmartFocus. Contact your Account Manager to have a dedicated API login.

To connect through the API, the user must first obtain a manager key using the CCMD Web Application.

Calling the connect method (with the login, password, manager key) will provide a token, to be used in all subsequent calls. This token will expire in the following cases:

l When a close connection call is made.

l When the maximum number of calls per session, defined by the manager in SmartFocus, is reached. l When the session times out.

Step 2: Build your application

Integration Using APIs

The first step in getting started with web services is to configure the range of remote servers that will access this module. Webmasters and developers should be able to interface with this new API with any programming language that uses standard HTTP calls.

List of APIs that are available: l RESTful API

l SOAP API (see theCampaign Management SOAP API Guide)

RESTful API

Description:RESTful API is the most standard way to remotely call a Web Service. REST requests are always sent over the HTTP protocol and can vary in format and methods of submission.

This API method is available in two formats: HTTP GET Query String (QS) and HTTP GET Path Info (PI). l HTTP GET QS (Query String):

(16)

l HTTP GET PI (Path Info):

The result is identical to the Query String method. It differs in the way parameters are organized in the URL. In the PI method, parameters are organized like a path.

The order of all parameters is very important. o The path is composed of a series of values.

o The values are each separated by a forward slash sign (/).

o Below is an Internet browser URL location bar showing a URL with the Path Info:

o API call summary: HTTP GET (Path Info)

Submission URL

http://{server}/apiccmd/services/rest/campaign/get/{token}/{ID}

Parameters & associated values

l All parameter names are case-sensitive.

l When specific values are expected, it should be assumed that parameter values are case sensitive. l The order of parameters must be strictly followed.

Example call

https://{server}/apiccmd/services/rest/campaign/get/{token}/1443

Rules

For a given Object (Message, Campaign, etc.), all create, get, update, delete methods will have the same structure: l Get Object will take the ID of the object as input and return the full object description.

l Create Object will take the full object as input and return the ID of the newly created object ( or error if creation failed).

l Update Object will take the full object as input and returntrueif the update was successful. l Delete Object will take the ID of the object as input and returntrueif the delete was successful.

URL Encoding Considerations (for HTTP GET methods only)

(17)

l Letters (A-Z and a-z) and numbers (0-9) are not encoded.

l The period (.), comma (,) , tilde (~), and underscore (_) characters are not encoded. l A space is encoded as%20.

l The forward slash (/) is encoded as%2F.

l All other characters are encoded as%FFhex representation with any non-ASCII characters first encoded as UTF-8 (or other specified encoding).

l To encode as RFC 1738, use the+sign to replace spaces.

Security

As web services are accessible over the Internet and can be interfaced with any system, there is a risk of fraudulent access and usage of the system. To tighten security, SmartFocus APIs can be accessed using the HTTPS protocol. To use HTTPS, just replaceHTTPwithHTTPSin all the submission URLs.

(18)

Connection

Prerequisite:To use SmartFocus APIs, you need to have the API manager login provided by SmartFocus and the associated password.

To connect through the API, you must first retrieve the manager key from SmartFocus. 1. Go toAccount Administrationand selectLogins.

2. Click theEditicon next to your API manager.

3. In theAPIsection of the popup window, copy the API key (also known as the manager key) and use it to open a connection to retrieve the token that will be used in your calls.

Calling the connect method (with the login, password, manager key) will provide a token, to be used in all subsequent calls. This token will expire in the following cases:

l When a close connection call is made.

l When the maximum number of calls per session, defined by the manager in SmartFocus, is reached. l When the session times out.

Recommended Token Usage

An open connection call generates a token that should be used until it expires. Once the token expires, an API call will generate a session exception. At this point, you should open a new connection to continue your API calls.

Example:An example workflow:

1. Open the connection to generate the token.

2. Use API method calls as needed. If a call fails due to a problem with the session: a. Send another open connection call to renew the token.

b. Resend the call that failed due to the session issue.

3. Send a close connection call once all API method calls for the session have been sent successfully.

Note:For time consuming calls (e.g., uploading a large file), you may need to use an open connection call to ensure that the token will remain valid for the duration of the call.

(19)

Open Connection

This method provides a session token when given valid credentials. Note:The token is valid for 60 minutes.

This is a GET method. REST WADL

https://{server}/apiccmd/services/rest?_wadl&_type=xml

REST URL

https://{server}/apiccmd/services/rest/connect/open/{login}/{pwd}/{key}

Note:Ask your Account Manager for your server name.

Input parameters Required parameters Description Output parameters Description

login The login provided for API access return The token to use in all other API calls

pwd

The password

Note: API passwords expire after 365 days. key The manager key copied from SmartFocus (see

Connectionon page 18)

Error messages

You must fill in the apiName parameter to check rights of client on this API. You must fill in the login parameter to authentifiate on this API.

You must fill in the password parameter to authentifiate on this API. You must fill in the managerKey parameter to authentifiate on this API. Error while decoding managerKey.

Your login is not valid !! Your password is not valid !!

No manager retrieved for those login, password. No available connection for manager {0}.

(20)

REST Example

In p u t http://{server}/apiccmd/services/rest/connect/open/br_test/aptrokez/CdX7CrlE_26blFNJOsgf-dawh6LJ3y6pwg5PEOvA Ou tp u t <response responseStatus="success"> <result xsi:type="xs:string"> {token} </result> </response>

(21)

Close Connection

This method terminates the session token. This is a GET method. REST WADL https://{server}/apiccmd/services/rest?_wadl&_type=xml REST URL https://{server}/apiccmd/services/rest/connect/close/{token} Input parameter Required parameters Description Output parameter Description

token The connection

token return

The connection is closed if the operation was successful, otherwise an error code appears.

Error messages

You must fill in the token parameter

No available connection for the specified token. An error occured on the server

REST Example

In p u t

https://{server}/apiccmd/services/rest/connect/close/{token}

Ou tp u t

<result xsi:type="xs:string">connection closed</result> </response>

(22)

Message

The Messages feature is the cornerstone of your campaign. It allows you to create the emails and SMS messages that you will associate to your classic and reflex campaigns, split runs, and RSS feeds. This essential and powerful feature is the medium for creating attractive emails that engage your readers and track their behavior within and outside of the email.

A message may contain links you would like to track or specific links like online preview, unsubscribe, etc. These links are part of the message and managed in the same object.

How to Use Tracked URLs in the Message Body

To use tracked URLs in the message body, you must change every reference to a tracked URL in the HTML code to comply with Ccmd syntax.

Thehrefvalue in the HTML code must be set to[EMV LINK]1[EMV /LINK]where the corresponding tracked URL order number would be 1. The tracked URL order numbers should start at 1 and be continuous (i.e. 1, 2, 3, 4... and not 1, 3, 5).

Then create a tracked URL (i.e. standard URL, update URL, etc.) using the appropriate method and set the order number for each tracked URL.

How to Automatically Track All Links

Another method of tracking links consists in loading the HTML body as it is, without any tracked URL definition, and use the

trackAllLinksmethod. If you use this method, all links will be considered asstandard links. You may therefore consider managing links individually if you want to handle specific link types.

The Message Object

Input

parameters Description

body The body of the message (HTML must be between the tags<![CDATA[and]]>) createDate The creation date of the message

description The description of the message encoding The encoding used (e.g. UTF-8)

from The From name. For SMS messages, the From name cannot exceed 11 characters. fromEmail The From email address

hotmailUnsubFlg Set totrueto use the unsubscribe feature of Windows Live Mail (this improves deliverability). The default value isfalse.

hotmailUnsubUrl The Windows Live Mail unsubscribe URL id The ID of the message

isBounceback Set totrueif you want to use this message as a bounce back message (update, unsubscribe). name The name of the message.

Note:The name cannot exceed 50 characters. replyTo The Reply To name

(23)

Input

parameters Description

to The To name

type The type (email or SMS). The default is SMS.

Note:The parameters making up the object do not always need to be present for methods using the object. For example, when you create a new banner, campaign, or message, you do not need to provide theidparameter even though this is present in the object. Each method's section lists the parameters that must or can be included for the method. On the other hand, these parameters are all present when the object appears in a method's output.

(24)

Create Email Message

This method creates an email. This is a GET method.

REST WADL https://{server}/apiccmd/services/rest?_wadl&_type=xml REST URL https://{server}/apiccmd/services/rest/message/createEmailMessage/{token}/{name}/ {description}/{subject}/{from}/{fromEmail}/{to}/{body}/{encoding}/{replyTo}/{replyToEmail}/ {isBounceback}/{hotmailUnsubFlg}/{hotmailUnsubUrl}

Input parameters Required parameters

Description Output_parameters Description

token The connection token return The message

ID name The name of the message.

Note:The name cannot exceed 50 characters. description The description of the message

subject

The subject of the message.

Note: The subject cannot exceed 2000 characters. from The From name

fromEmail The From email address

to The To name

body The body of the message (HTML must be between the tags<![CDATA[and ]]>)

encoding The encoding used (e.g. UTF-8) replyTo The Reply To name

replyToEmail The Reply To email address

isBounceback Set totrueif you want to use this message as a bounce back message (update, unsubscribe).

hotmailUnsubFlg Set totrueto use the unsubscribe feature of Windows Live Mail (this improves deliverability). The default value isfalse.

(25)

You must fill in the token parameter You must fill in the name parameter. You must fill in the body parameter.

The content must begin with [EMV TEXTPART] OR [EMV HTMLPART]. This sender is not configured for your account.

You must fill in the replyToEmail parameter. An error occured on the server

Note:Whenever you do not use all required and optional input parameters for a given method, you must use the HTTP GET QS (Query String) format.

l HTTP GET QS (Query String):

o The query string is composed of a series of field-value pairs. o _{The field-value pairs are each separated by an equals sign (=).} o The series of pairs is separated by the ampersand (&).

o _{Below is an Internet browser URL location bar showing a URL where the Query String is:} _{title=Main_} page&action=raw

o API call summary: HTTP GET (Query String)

Submission & sample URL call

REST Example

In p u t https://{server}/apiccmd/services/rest/message/createEmailMessage/{token}/TestEmail/ This%20is%20a%20test%20message/Welcome%20to%20SmartFocus%20test%20session/SmartFocus/ [email protected]/myclient/%5BEMV%20HTMLPART%5Dhi%20there/UTF-8/ Documentation/[email protected]/0/1/www.smarfocus.com Ou tp u t <response responseStatus="success"> <result xsi:type="xs:long">11490</result> </response>

(26)

Create SMS Message

This method creates an SMS message. This is a GET method. REST WADL https://{server}/apiccmd/services/rest?_wadl&_type=xml REST URL https://{server}/apiccmd/services/rest/message/createSmsMessage/{token}/{name}/{description}/ {from}/{body}

token The connection token return The SMS

message ID name The name of the message.

This parameter is required for Path Info, but optional for Query String.

from

The From name. The name cannot exceed 11 characters.

This parameter is required for Path Info, but optional for Query String. Note:

If you have subscribed to the branded SMS sender option, depending on the region that you are in, the From name can be a fixed or customizable value.

l Fixed branded sender: You must provide thefromparameter containing the branded sender configured for your account.

l Customizable branded sender: You must provide thefromparameter containing the sender value that you want to use for the SMS

campaign using this SMS message.

If you have not subscribed to the branded SMS sender option or if you are in a region where the branded SMS sender option is not permitted, thefrom parameter should not be included.

(27)

Body must contain [EMV SMSPART]. Body must contain less than 500 characters. This sender is not configured for your account.

You must include the Value parameter to update the From field.

You must include the from parameter with your authorised SMS sender, which is: {1}. The From parameter must contain the authorised SMS sender for your account, which is: {1}.

You cannot configure the From parameter because you have not subscribed to the personalised SMS sender option. To activate it, please contact SmartFocus Support.

The value for the From parameter cannot contain more than 11 characters. An error occured on the server

o Below is an Internet browser URL location bar showing a URL where the Query String is: _{title=Main_} page&action=raw

REST Example

In p u t https://{server}/apiccmd/services/rest/message/createSmsMessage/{token}/NewSMSName/ SMSdescription/[email protected]/%5BEMV%20SMSPART%5DHello Ou tp u t <response responseStatus="success"> <result xsi:type="xs:long">11830</result> </response>

(28)

Create Message (POST)

This method creates an email or SMS message. This is a POST method.

REST WADL

REST URL

https://{server}/apiccmd/services/rest/message/create/{token}

ID Message Parameters

message The message envelope parameter. name The name of the message.

subject The subject of the message.The subject cannot exceed 2000 characters. (email parameter)

from

The From name. For SMS messages, the From name cannot exceed 11 characters.

Note:

For SMS messages:

l Fixed branded sender: You must provide thefromparameter containing the branded sender configured for your account. l Customizable branded sender: You must provide thefrom

parameter containing the sender value that you want to use for the SMS campaign using this SMS message.

(29)

to The To name (email parameter)

body The body of the message (HTML must be between the tags<![CDATA[and]] >)

encoding The encoding used (e.g. UTF-8) (email parameter) replyTo The Reply To name (email parameter)

replyToEmail The Reply To email address (email parameter)

isBounceback Set totrueif you want to use this message as a bounce back message (update, unsubscribe). (email parameter)

hotmailUnsubFlg Set totrueto use the unsubscribe feature of Windows Live Mail (this improves deliverability). The default value isfalse. (email parameter) hotmailUnsubUrlThe Windows Live Mail unsubscribe URL (email parameter)

Error messages

The content must begin with [EMV TEXTPART] OR [EMV HTMLPART]. Body must contain less than 500 characters.

This sender is not configured for your account.

REST Example

In p u t

(30)

<message> <type>email</type> <body>[EMV HTMLPART]test</body> <isBounceback>false</isBounceback> <description>desc test</description> <encoding>UTF8</encoding> <from>[email protected]</from> <name>test name</name> <replyTo>[email protected]</replyTo> <replyToEmail>[email protected]</replyToEmail> <subject>test subject</subject> <to>[email protected]</to> <hotmailUnsubFlg>true</hotmailUnsubFlg> <hotmailUnsubUrl>http://www.smartfocus.com</hotmailUnsubUrl> </message> SMS Input Example URL https://{server}/apiccmd/services/rest/message/create/{token} Content-type text/xml; charset=UTF-8 Body <message> <type>sms</type> <name>test name</name> <description>desc test</description>

<body>[EMV SMSPART] SMS creation test by API</body> <from>SmartFocus</from>

</message>

Ou tp u t

<?xml version="1.0" encoding="utf-8" standalone="yes"?> <response responseStatus="success">

(31)

Delete Message

This method deletes a message. This is a GET method.

REST WADL

REST URL

https://{server}/apiccmd/services/rest/message/deleteMessage/{token}/{id}

Input parameter Required

parameters

Description Output

parameter Description

token The connection token return trueif it was successful,falseif it was not successful

id The ID of the message to delete

Error messages

You must fill in the token parameter This message doesn't exist.

This message is already used. Please select another one. An error occured on the server

REST Example

In p u t https://{server}/apiccmd/services/rest/message/deleteMessage/{token}/11830 Ou tp u t <response responseStatus="success"> <result xsi:type="xs:boolean">true</result> </response>

(32)

Update Message

This method updates a message field. This is a GET method.

REST WADL

REST URL

https://{server}/apiccmd/services/rest/message/updateMessage/{token}/{id}/{field}/{value}

Input parameter Required parameters Description Output parameter Description

token The connection token return

trueif it was successful,falseif it was not successful id The ID of the message to update

(33)

Input parameter Required parameters Description Output parameter Description field

The field of the Message object to update: l email fields: l name l description l subject l encoding l from l to l replyto l replytoemail l isbounceback l hotmailunsubflg l hotmailunsuburl l SMS fields: l name l description l from Note: For SMS messages:

l Fixed branded sender: You must provide the fromfield containing the branded sender configured for your account.

l Customizable branded sender: You must provide thefromfield containing the sender value that you want to use for the SMS campaign using this SMS message.

If you have not subscribed to the branded SMS sender option, thefromfield should not be included.

value The value to set for the field

Error messages

(34)

The Value parameter must contain the authorised SMS sender for your account, which is: {1}. You must include the Value parameter with your authorised SMS sender, which is: {1}. An error occured on the server

REST Example

In p u t https://{server}/apiccmd/services/rest/message/updateMessage/{token}/11499/subject/hello Ou tp u t <response responseStatus="success"> <result xsi:type="xs:boolean">true</result> </response>

(35)

Update Message (POST)

This method updates an email or SMS message. This is a POST method.

REST WADL

REST URL

https://{server}/apiccmd/services/rest/message/update/{token}

ID Message Parameters

message The message envelope parameter. id The ID of the message

name The name of the message.The name cannot exceed 50 characters. description The description of the message

subject The subject of the message.The subject cannot exceed 2000 characters. (email parameter)

from The From name. For SMS messages, the From name cannot exceed 11 characters.

fromEmail The From email address (email parameter) to The To name (email parameter)

body The body of the message (HTML must be between the tags<![CDATA[and]] >)

encoding The encoding used (e.g. UTF-8) (email parameter) replyTo The Reply To name (email parameter)

(36)

Error messages

The content must begin with [EMV TEXTPART] OR [EMV HTMLPART]. Body must contain less than 500 characters.

This sender is not configured for your account.

o _{The query string is composed of a series of field-value pairs.} o The field-value pairs are each separated by an equals sign (=). o _{The series of pairs is separated by the ampersand (&).}

o Below is an Internet browser URL location bar showing a URL where the Query String is: _{title=Main_} page&action=raw

REST Example

In p u t URL https://{server}/apiccmd/services/rest/message/update/{token} Content-type

(37)

<body>[EMV SMSPART]Hello</body> <description>desc test</description> <encoding>UTF8</encoding> <from>John Smith</from> <fromEmail>[email protected]</fromEmail> <name>Test</name> <replyTo>John Smith</replyTo> <replyToEmail>[email protected]</replyToEmail> <subject>test subject</subject> <to>[email protected]</to> <hotmailUnsubFlg>true</hotmailUnsubFlg> <hotmailUnsubUrl>http://www.smartfocus.com</hotmailUnsubUrl> </message> Ou tp u t

<?xml version="1.0" encoding="utf-8" standalone="yes"?> <response responseStatus="success">

(38)

Clone Message

This method clones a message. This is a GET method.

REST WADL

REST URL

https://{server}/apiccmd/services/rest/message/cloneMessage/{token}/{id}/{newName}

parameters

token The connection token return The ID of the newly created

message id The ID of the message to clone

newName The name of the newly created message

Error messages

You must fill in the token parameter An error occured on the server

REST Example

In p u t https://{server}/apiccmd/services/rest/message/cloneMessage/{token}/11501/NewMessageName Ou tp u t <response responseStatus="success"> <result xsi:type="xs:long">11828</result> </response>

(39)

Get Message

This method retrieves a message by its ID. This is a GET method.

REST WADL

REST URL

https://{server}/apiccmd/services/rest/message/getMessage/{token}/{id}

Input parameter

Required parametersDescription Output parameter Description

id The ID of the message to retrieve

Error messages

An error occured on the server

REST Example

In p u t https://{server}/apiccmd/services/rest/message/getMessage/{token}/11501 Ou tp u t <response responseStatus="success"> <message> <body>[EMV HTMLPART]test</body> <createDate>2009-05-04T00:00:00+02:00</createDate> <description>desc test</description> <encoding>UTF8</encoding> <from>[email protected]</from> <fromEmail>[email protected]</fromEmail> <hotmailUnsubFlg>false</hotmailUnsubFlg> <hotmailUnsubUrl>http://www.smarfocus.com</hotmailUnsubUrl> <id>1972</id> <isBounceback>false</isBounceback>

(40)

Get Last Email Messages

This method retrieves the list of the last emails created. This is a GET method.

REST WADL

REST URL

https://{server}/apiccmd/services/rest/message/getLastEmailMessages/{token}/{limit}

Input parameter

token The connection token return The IDs of the messages

limit The maximum number of messages to retrieve

Error messages

REST Example

In p u t https://{server}/apiccmd/services/rest/message/getLastEmailMessages/{token}/3 Ou tp u t <response responseStatus="success"> <entities> <id>11501</id> <id>11500</id> <id>11499</id> </entities> </response>

(41)

Get Last SMS Messages

This method retrieves the last SMS messages created. This is a GET method.

REST WADL

REST URL

https://{server}/apiccmd/services/rest/message/getLastSmsMessages/{token}/{limit}

Input parameter

token The connection token return The IDs of the messages

Error messages

REST Example

In p u t https://{server}/apiccmd/services/rest/message/getLastSmsMessages/{token}/3 Ou tp u t <response responseStatus="success"> <entities> <id>2041</id> <id>1081</id> </entities> </response>

(42)

Get Email Messages by Field

This method retrieves a list of emails that contain the given value in the specified field. This is a GET method. REST WADL https://{server}/apiccmd/services/rest?_wadl&_type=xml REST URL https://{server}/apiccmd/services/rest/message/getEmailMessageByField/{token}/{field}/{value}/ {limit}

parameters

token The connection token return The IDs of the

messages field The field to search (any field of the message

object)

value The value to search for in the field

Error messages

You must fill in the token parameter You must fill in the name parameter. You must fill in the replyToEmail parameter.

The part parameter is not the same as HTML or TEXT. An error occured on the server

REST Example

In p u t https://{server}/apiccmd/services/rest/message/getEmailMessageByField/{token}/name/Welcome/2 Ou tp u t <response responseStatus="success"> <entities> <id>11123</id> <id>10962</id>

(43)

Get SMS Messages by Field

This method retrieves a list of SMS messages that contain the given value in the specified field. This is a GET method. REST WADL https://{server}/apiccmd/services/rest?_wadl&_type=xml REST URL https://{server}/apiccmd/services/rest/message/getSmsMessagesByField/{token}/{field}/{value}/ {limit}

parameters

token The connection token return The IDs of the_messages

field The field to search (any field of the message object)

value The value to search for in the field

Error messages

You must fill in the token parameter You must fill in the name parameter. An error occured on the server

REST Example

In p u t https://{server}/apiccmd/services/rest/message/getSmsMessagesByField/{token}/name/sms/3 Ou tp u t <response responseStatus="success"> <entities> <id>2041</id> <id>2045</id>

(44)

Get Messages by Period

This method retrieves a list of messages from a given period. This is a GET method. REST WADL https://{server}/apiccmd/services/rest?_wadl&_type=xml REST URL https://{server}/apiccmd/services/rest/message/getMessagesByPeriod/{token}/{dateBegin}/ {dateEnd}

parameters

token The connection token return The IDs of the

messages dateBegin The start date of the period to retrieve (yyyy-MM-dd

HH:mm:ss)

dateEnd The end date of the period to retrieve (yyyy-MM-dd HH:mm:ss)

Error messages

You must fill in the token parameter You must fill in the dateBegin parameter. You must fill in the dateEnd parameter.

dateBegin doesn't exist or is malformed (good format is : yyyy-MM-dd HH:mm:ss). dateEnd doesn't exist or is malformed (good format is : yyyy-MM-dd HH:mm:ss). An error occured on the server

REST Example

In p u t https://{server}/apiccmd/services/rest/message/getMessagesByPeriod/{token}/ 2011-08-09%2000:00:00/2011-09-09%2000:00:00 Ou tp u t <response responseStatus="success"> <entities> <id>11499</id>

(45)

Get Email Message Preview

This method provides a preview of an email. This is a GET method.

REST WADL

REST URL

https://{server}/apiccmd/services/rest/message/getEmailMessagePreview/{token}/{id}/{part}

parameters

token The connection token return The preview of the

message id The ID of the message to preview

part The part of the message (HTML or TEXT) to preview

Error messages

Message type must be email.

REST Example

In p u t https://{server}/apiccmd/services/rest/message/getEmailMessagePreview/{token}/11123/HTML Ou tp u t <response responseStatus="success"> <result xsi:type="xs:string"> <html xmlns="http://www.w3.org/1999/xhtml">

(46)

</tr> </table> </body> </html> </result> </response>

(47)

Get SMS Message Preview

This method provides a preview of an SMS message. This is a GET method.

REST WADL

REST URL

https://{server}/apiccmd/services/rest/message/getSmsMessagePreview/{token}/{id}

Input parameter

token The connection token return The preview of the SMS message

messageId The ID of the message to preview

Error messages

Message type must be sms. An error occured on the server

REST Example

In p u t https://{server}/apiccmd/services/rest/message/getSmsMessagePreview/{token}/1081 Ou tp u t <response responseStatus="success"> <result xsi:type="xs:string">Hello!</result> </response>

(48)

Track All Links

This method activates tracking for all links in an email. This is a GET method.

REST WADL

REST URL

https://{server}/apiccmd/services/rest/message/trackAllLinks/{token}/{id}

parameters

token The connection token return The ID of the last tracked

URL id The ID of the message of which to track all

links

Error messages

Message type must be email. There is no link to track. An error occured on the server

REST Example

In p u t https://{server}/apiccmd/services/rest/message/trackAllLinks/{token}/11499 Ou tp u t <response responseStatus="success"> <result xsi:type="xs:long">10</result> </response>

(49)

Untrack All Links

This method deactivates link tracking for all links in an email. This is a GET method.

REST WADL

REST URL

https://{server}/apiccmd/services/rest/message/untrackAllLinks/{token}/{id}

parameters

id The ID of the message for which to untrack all links

Error messages

Message type must be email. An error occured on the server

REST Example

In p u t https://{server}/apiccmd/services/rest/message/untrackAllLinks/{token}/11499 Ou tp u t <response responseStatus="success"> <result xsi:type="xs:boolean">true</result> </response>

(50)

Track Link by Position

This method tracks a link based on its position in an email. This is a GET method. REST WADL https://{server}/apiccmd/services/rest?_wadl&_type=xml REST URL https://{server}/apiccmd/services/rest/message/trackLinkByPosition/{token}/{id}/{position}/ {part}

parameters

token The connection token return The order number of the_URL

id The ID of the message to update position Position of the link (URL) to track in the

message

part The part of the message (HTML or TEXT)

Error messages

Message type must be email.

REST Example

In p u t https://{server}/apiccmd/services/rest/message/trackLinkByPosition/{token}/11499/10/HTML Ou tp u t <response responseStatus="success"> <result xsi:type="xs:long">11</result> </response>

(51)

Untrack Link by Order

This method untracks a link based on its order number. This is a GET method.

REST WADL

REST URL

https://{server}/apiccmd/services/rest/message/untrackLinkByOrder/{token}/{id}/{order}

parameters

id The ID of the message to update

order The order number of the_URL

Error messages

Message type must be email. An error occured on the server

REST Example

In p u t https://{server}/apiccmd/services/rest/message/untrackLinkByOrder/{token}/11499/15 Ou tp u t <response responseStatus="success"> <result xsi:type="xs:boolean">true</result> </response>

(52)

Get All Tracked Links

This method retrieves a list of all the tracked links in an email. This is a GET method.

REST WADL

REST URL

https://{server}/apiccmd/services/rest/message/getAllTrackedLinks/{token}/{id}

parameters

token The connection token return The list of IDs of the tracked

links id The ID of the message for which to retrieve the

tracked links

Error messages

You must fill in the token parameter You must fill in the id parameter. An error occured on the server

In p u t https://{server}/apiccmd/services/rest/message/getAllTrackedLinks/{token}/11501 Ou tp u t <response responseStatus="success"> <entities> <id>3</id> </entities> </response>

(53)

Get All Unused Tracked Links

This method retrieves the unused tracked links for an email. This is a GET method.

REST WADL

REST URL

https://{server}/apiccmd/services/rest/message/getAllUnusedTrackedLinks/{token}/{id}

Input parameter Required parameters Description Output parameter Description

token The connection token return The list of IDs of the unused

tracked links id The ID of the message for which to retrieve the

unused tracked links

Error messages

You must fill in the token parameter You must fill in the id parameter. An error occured on the server

REST Example

In p u t https://{server}/apiccmd/services/rest/message/getAllUnusedTrackedLinks/{token}/11501 Ou tp u t <response responseStatus="success"> <entities> <id>2</id> </entities> </response>

SmartFocus Cloud Service APIs

Service

Campaign management for managing email campaigns

Protocol

REST over HTTP

Version

11.8

Table of Contents

Introduction

About This Document

About SmartFocus APIs

Feedback

Support Options

Training Options

SmartFocus's Products and Services

Disclaimer

Overview of the Campaign Management API

Campaign Management API Use Cases

Message Use Cases

Test Group Use Cases

Getting Started with Integration

Prerequisites

Quick Start

Integration Using APIs

RESTful API

Rules

URL Encoding Considerations (for HTTP GET methods only)

Security

Connection

Recommended Token Usage

Open Connection

REST Example

Close Connection

REST Example

Message

How to Use Tracked URLs in the Message Body

How to Automatically Track All Links

The Message Object

Create Email Message

REST Example

Create SMS Message

REST Example

Create Message (POST)

REST Example

Delete Message

REST Example

Update Message

REST Example

Update Message (POST)

REST Example

Clone Message

REST Example

Get Message

REST Example

Get Last Email Messages

REST Example

Get Last SMS Messages

REST Example

Get Email Messages by Field

REST Example

Get SMS Messages by Field

REST Example

Get Messages by Period

REST Example

Get Email Message Preview

REST Example

Get SMS Message Preview

REST Example

Track All Links

REST Example

Untrack All Links

REST Example

Track Link by Position

REST Example

Untrack Link by Order

REST Example

Get All Tracked Links

Get All Unused Tracked Links

REST Example