Campaign Management API Guide - REST

291 Pages·2017·1.52 MB·English

SmartFocus Cloud Service APIs
Documentname CampaignManagementRESTAPIGuide
Service Campaignmanagementformanagingemailcampaigns
Protocol RESToverHTTP
Version 11.20
Lastupdated on Monday,March26,2018
CampaignManagementRESTAPIGuide
TableofContents
Table ofContents
TableofContents 2
Introduction 7
AboutThisDocument 7
AboutSmartFocusAPIs 7
Feedback 7
SupportOptions 7
TrainingOptions 7
SmartFocus'sProductsandServices 7
Disclaimer 7
OverviewoftheCampaignManagementAPI 8
CampaignManagementAPIUseCases 13
GettingStartedwithIntegration 15
Prerequisites 15
QuickStart 15
IntegrationUsingAPIs 15
Rules 16
URLEncodingConsiderations(forHTTPGETmethodsonly) 16
Security 17
Connection 18
RecommendedTokenUsage 18
API AuthenticationRequest:CallVolumeThrottling 18
OpenConnection 19
CloseConnection 21
Message 22
HowtoUseTrackedURLsintheMessageBody 22
HowtoAutomaticallyTrackAllLinks 22
TheMessageObject 22
CreateEmailMessage 24
CreateSMSMessage 26
CreateMessage(POST) 28
DeleteMessage 31
UpdateMessage 32
UpdateMessage(POST) 35
CloneMessage 38
GetMessage 39
GetLastEmailMessages 40
GetLastSMSMessages 41
GetEmailMessagesbyField 42
GetSMSMessagesbyField 43
www.smartfocus.com 2
CampaignManagementRESTAPIGuide
TableofContents
GetMessagesbyPeriod 44
GetEmailMessagePreview 45
GetSMSMessagePreview 47
TrackAllLinks 48
UntrackAllLinks 49
TrackLinkbyPosition 50
UntrackLinkbyOrder 51
GetAllTrackedLinks 52
GetAllUnusedTrackedLinks 53
GetAllTrackableLinks 54
TestHTMLValidity 55
TestEmailMessageonaGroup 56
TestEmailMessageonaMember 57
TestSMSMessage 58
GetDefaultSender 59
GetValidatedAlternateSenders 60
GetUnvalidatedSenders 61
URL 62
CreateStandardURL 62
CreateandAddStandardURL 63
CreateUnsubscribeURL 64
CreateandAddUnsubscribeURL 66
CreatePersonalizedURL 67
CreateandAddPersonalizedURL 68
CreateUpdateURL 69
CreateandAddUpdateURL 70
CreateActionURL 71
CreateandAddActionURL 73
CreateMirrorURL 75
CreateandAddMirrorURL 76
AddaShareLink 78
UpdateURLbyField 80
DeleteURL 81
GetURLbyOrder 82
Segment 83
TheSegmentObject 83
TheSegmentCriteriaObjects 83
CreateSegment 90
DeleteSegment 92
UpdateSegment 94
www.smartfocus.com 3
CampaignManagementRESTAPIGuide
TableofContents
AddStringDemographicCriteriatoaSegment 96
AddNumericDemographicCriteriatoaSegment 99
AddDateDemographicCriteriatoaSegment 102
AddCampaignActionCriteriatoaSegment 107
AddCampaignTrackableLinkCriteriatoaSegment 110
AddTriggerCampaignActionCriteriatoaSegment 113
AddTriggerCampaignTrackableLinkCriteriatoaSegment 116
AddSocialCriteriatoaSegment 119
AddRecencyCriteriatoaSegment 123
AddDataMartCriteriatoaSegment 126
IncludeorExcludeaSegmentfromAnotherSegment 128
GetSegmentbyID 130
GetSegmentList 131
GetSegmentCriteria 132
GetDataMartSegmentList 133
DeleteSegmentCriteria 134
UpdatetheStringDemographicCriteriaofaSegment 135
UpdatetheNumericDemographicCriteriaofaSegment 138
UpdatetheDateDemographicCriteriaofaSegment 140
UpdatetheCampaignActionCriteriaofaSegment 145
UpdatetheCampaignTrackableLinkCriteriaofaSegment 148
UpdatetheTriggerCampaignActionCriteriaofaSegment 151
UpdatetheTriggerCampaignTrackableLinkCriteriaofaSegment 153
UpdatetheSocialCriteriaofaSegment 156
UpdatetheRecencyCriteriaofaSegment 160
UpdatetheDataMartCriteriaofaSegment 163
UpdatetheIncluded/ExcludedSegmentCriteriaofaSegment 165
CountSegment 167
CountDistinctSegmentMembers 168
Campaign 169
TheCampaignObject 169
CreateCampaign 170
CreateCampaignwithAnalytics 172
CreateCampaign(POST) 174
DeleteCampaign 176
UpdateCampaign 177
UpdateCampaign(POST) 179
PostCampaign 182
UnpostCampaign 183
GetCampaign 184
www.smartfocus.com 4
CampaignManagementRESTAPIGuide
TableofContents
GetCampaignsbyField 186
GetCampaignsByStatus 188
GetCampaignsByPeriod 189
GetCampaignStatus 191
GetLastCampaigns 192
TestCampaignonaGroup 193
TestCampaignonaMember 194
PauseCampaign 195
UnpauseCampaign 196
GetCampaignReport 197
GetCampaignSnapshotReport 199
GetCampaignSummaryList 200
DynamicContent 204
TheBannerObject 204
CreateDynamicContentBlock 205
CreateDynamicContentBlock(POST) 207
DeleteDynamicContentBlock 209
UpdateDynamicContentBlock 210
UpdateDynamicContentBlockPOST 212
CloneDynamicContentBlock 214
GetDynamicContentBlockPreview 215
GetDynamicContentBlock 217
GetDynamicContentBlocksbyField 218
GetDynamicContentBlocksbyPeriod 220
GetLastDynamicContentBlocks 221
TrackAllDynamicContentBlockLinks 222
UntrackAllDynamicContentBlockLinks 223
TrackDynamicContentBlockLinkbyPosition 224
UntrackDynamicContentBlockLinkbyOrder 225
GetAllDynamicContentBlockTrackedLinks 226
GetAllUnusedDynamicContentBlockTrackedLinks 227
GetAllDynamicContentBlockTrackableLinks 228
DynamicContentBlockLinks 229
CreateDynamicContentBlockStandardLink 229
CreateandAddDynamicContentBlockStandardLink 230
CreateDynamicContentBlockUnsubscribeLink 231
CreateandAddDynamicContentBlockUnsubscribeLink 233
CreateDynamicContentBlockPersonalizedLink 234
CreateandAddDynamicContentBlockPersonalizedLink 235
CreateDynamicContentBlockUpdateLink 236
www.smartfocus.com 5
CampaignManagementRESTAPIGuide
TableofContents
CreateandAddDynamicContentBlockUpdateLink 238
CreateDynamicContentBlockActionLink 239
CreateandAddDynamicContentBlockActionLink 241
CreateDynamicContentBlockMirrorLink 242
CreateandAddDynamicContentBlockMirrorLink 243
UpdateDynamicContentBlockLinkbyField 245
GetDynamicContentBlockLinkbyOrder 247
Webforms 248
TheWebformObject 248
CreateaWebform 251
UpdateaWebform 258
CopyaWebform 266
UpdateaWebform'sStatus 268
GetaWebform 270
GetWebformIntegrationCode 272
TestGroup 275
TheTestGroupObject 275
CreateaTestMember 276
DeleteaTestMember 277
CreateanSMSTestMember 278
GetaTestMember 279
GetTestMembers 280
CreateaTestGroup 281
CreateaTestGroup(POST) 282
DeleteaTestGroup 284
AddTestMembertoaTestGroup 285
RemoveTestMember 286
UpdateaTestGroup(POST) 287
GetTestGroup 289
GetAllTestGroups 290
Reference 291
www.smartfocus.com 6
CampaignManagementRESTAPIGuide
Introduction
Introduction
About ThisDocument
ThisdocumentisareferencedocumentforusingSmartFocusAPIs.ItdoesnotexplainthepurposeorfunctionsofSmartFocus
features.Forinformationonthesefeatures,pleaseconsulttheSmartFocusOnlineHelportheSmartFocusUserGuide.
Thisdocumentisintendedfordevelopersandprojectmanagers.
About SmartFocusAPIs
AnApplicationProgrammingInterface(API)isasourcecodeinterfacethatacomputersystemorprogramlibraryprovidesin
ordertosupportrequestsforservicesmadefromanothercomputerprogram.
ThegoalofSmartFocusAPIsistooffercustomerstheabilitytopilotacompletecampaignfromtheirownsystem.
Feedback
TheCampaignManagementRESTAPIGuideisconstantlybeingenhancedtoprovideyouwithmoreandmoreinformationon
usingSmartFocusAPImethods.
Ifyoucan'tfindtheinformationyouneedorwanttoprovidefeedback,simplydropusalineat
[email protected].
Welookforwardtohearingfromyou!
Support Options
SmartFocusprovidesyouwithadedicatedAccountManagertoaccompanyyouthroughouttheexecutionofyourprojectsin
SmartFocus.YourAccountManageristhegatewaytosupport,training,andprofessionalservices.WorkingwithyourAccount
Manager,youcanrelyonSmartFocus’sdeliverabilityandtechnicalsupportteamsforcomplextroubleshootingand
optimization.
Training Options
SmartFocusprovidesfullycomprehensivetrainingrangingfrombasicproducttrainingthroughtoadvancedmodulesandboth
strategicandtacticalmarketingcourses.Thetrainingcoursesaredesignedtohelpyouincreaseproductivity,developnew
methods,andsharebestpracticestooptimizeyouremail,mobile,andsocialmarketingcampaigns.
Togetmoreinformationontraining,pleasecontactyourAccountManager.
SmartFocus'sProductsand Services
FormoreinformationonSmartFocus'sproductsandservices,pleaseseewww.smartfocus.com
Disclaimer
Whiletheinformationcontainedinthispublicationisbelievedtobetrueandaccurate,SmartFocuscannotacceptanylegal
responsibilityforanyerrorsoromissionscontainedherein.Allinformationissubjecttochangewithoutnotice.
Noneofthematerialinthispublicationmaybereproducedortransmittedinwholeorinpartwithouttheexpresswritten
permissionofSmartFocus.
www.smartfocus.com 7
CampaignManagementRESTAPIGuide
OverviewoftheCampaignManagementAPI
Overview ofthe CampaignManagement API
TheCampaignManagementAPIallowsyouto:
Create,edit,anddeleteemailandSMSMessages
l
Create,edit,anddeleteDynamicContentBlocks
l
Add,edit,track,anduntrackMessageandDynamicContentBlocklinks
l
Create,edit,anddeleteSegments
l
RetrievelistsofMessages,DynamicContentBlocks,andCampaigns
l
Forfurtherinformationonhowtocreate,edit,andmanagecampaigns,pleaseconsulttheSmartFocusUserGuideor
SmartFocusOnlineHelp.
Thefollowingmethodsareavailable:
Connection
l
Method Description
OpenConnection Thismethodprovidesasessiontokenwhengivenvalidcredentials.
CloseConnection Thismethodterminatesthesessiontoken.
Message
l
Method Description
CreateEmailMessage Thismethodcreatesanemail.
CreateSMSMessage ThismethodcreatesanSMSmessage.
CreateMessage(POST) Thismethodcreatesanemail.
DeleteMessage Thismethoddeletesamessage.
UpdateMessage Thismethodupdatesamessagefield.
UpdateMessage(POST) ThismethodupdatesanemailorSMSmessage.
CloneMessage Thismethodclonesamessage.
GetMessage ThismethodretrievesamessagebyitsID.
GetLastEmailMessages Thismethodretrievesthelistofthelastemailscreated.
GetLastSMSMessages ThismethodretrievesthelastSMS messagescreated.
Thismethodretrievesalistofemailsthatcontainthegivenvalueinthespecified
GetEmailMessagesbyField
field.
ThismethodretrievesalistofSMSmessagesthatcontainthegivenvalueinthe
GetSMSMessagesbyField
specifiedfield.
GetMessagesbyPeriod Thismethodretrievesalistofmessagesfromagivenperiod.
GetEmailMessagePreview Thismethodprovidesapreviewofanemail.
GetSMSMessagePreview ThismethodprovidesapreviewofanSMSmessage.
TrackAllLinks Thismethodactivatestrackingforalllinksinanemail.
UntrackAllLinks Thismethoddeactivateslinktrackingforalllinksinanemail.
TrackLinkbyPosition Thismethodtracksalinkbasedonitspositioninanemail.
UntrackLinkbyOrder Thismethoduntracksalinkbasedonitsordernumber.
GetAllTrackedLinks Thismethodretrievesalistofallthetrackedlinksinanemail.
GetAllUnusedTrackedLinks Thismethodretrievestheunusedtrackedlinksforanemail.
GetAllTrackableLinks Thismethodretrievesallthetrackablelinksinanemail.
TestHTMLValidity ThismethodverifiesthevalidityoftheHTMLusedinyouremail.
www.smartfocus.com 8
CampaignManagementRESTAPIGuide
OverviewoftheCampaignManagementAPI
Method Description
TestEmailMessageona
Thismethodsendsatestemailcampaigntoagroupofrecipients.
Group
TestEmailMessageona
Thismethodsendsatestemailcampaigntoamember.
Member
TestSMSMessage ThismethodsendsatestSMSmessagetoamember.
ThismethodretrievestheemailaddressofthedefaultsenderfortheSmartFocus
GetDefaultSender
account.
GetValidatedAlternate ThismethodretrievesthelistofvalidatedalternatesendersfortheSmartFocus
Senders account.
ThismethodretrievesthelistoftheunvalidatedalternatesendersfortheSmartFocus
GetUnvalidatedSenders
account.
URL
Note:TocreateoraddlinksinREST,youmustusetheHTTPGETQueryString(QS)format:
HTTPSGETQS(QueryString):
l
o Thequerystringiscomposedofaseriesoffield-valuepairs.
o Thefield-valuepairsareeachseparatedbyanequalssign(=).
o Theseriesofpairsisseparatedbytheampersand(&).
o BelowisanInternetbrowserURLlocationbarshowingaURLwheretheQueryStringis:
title=Main_page&action=raw
o APIcallsummary:
HTTP GET(Query String) 
Submission&sampleURLcall:
http://{server}/apiccmd/services/rest/campaign/get?token={token}&id={email}
Segment
l
Method Description
Thismethodcreatesasegment.
CreateSegment Note:Itisimperativethatyoursegmentcontainsmembersandthatallnecessary
criteriaisdefined.Ifasegmentwithoutcriteriaisusedinacampaign,allmembersin
thedatabasewillbeselected.
DeleteSegment Thismethoddeletesasegment.
UpdateSegment Thismethodupdatesasegment.
AddStringDemographic
Thismethodaddalphanumericdemographiccriteriatoasegment.
CriteriatoaSegment
AddNumericDemographic
Thismethodaddsnumericdemographiccriteriatoasegment.
CriteriatoaSegment
AddDateDemographic
Thismethodaddsdatedemographiccriteriatoasegment.
CriteriatoaSegment
AddCampaignAction
Thismethodaddscampaignactioncriteriatoasegment.
CriteriatoaSegment
www.smartfocus.com 9
CampaignManagementRESTAPIGuide
OverviewoftheCampaignManagementAPI
Method Description
AddCampaignTrackable
Thismethodaddscampaigntrackedlinkcriteriatoasegment.
LinkCriteriatoaSegment
AddTriggerCampaign
ThismethodaddsTriggerCampaignactioncriteriatoasegment.
ActionCriteriatoaSegment
AddTriggerCampaign
TrackableLinkCriteriatoa ThismethodaddsTriggerCampaigntrackedlinkcriteriatoasegment.
Segment
AddSocialCriteriatoa
Thismethodaddssocialcriteriatoasegment.
Segment
AddRecencyCriteriatoa
Thismethodaddsquicksegmentcriteriatosegment.
Segment
AddDataMartCriteriatoa
ThismethodaddsDataMartcriteriatoasegment.
Segment
IncludeorExcludea
SegmentfromAnother Thismethodincludesorexcludesanexistingsegmentinthecriteriaofanewsegment.
Segment
GetSegmentbyID ThismethodretrievesasegmentbyitsID.
GetSegmentList Thismethodretrievesalistofsegments.
GetSegmentCriteria Thismethodretrievesthecriteriausedinasegment.
GetDataMartSegmentList ThismethodretrievesalistofDataMartsegments.
DeleteSegmentCriteria Thismethoddeletesacriteriacellfromasegment.
UpdatetheString
DemographicCriteriaofa Thismethodupdatesalphanumericdemographiccriteria.
Segment
UpdatetheNumeric
DemographicCriteriaofa Thismethodupdatesnumericdemographiccriteria.
Segment
UpdatetheDate
DemographicCriteriaofa Thismethodupdatesdatedemographiccriteria.
Segment
UpdatetheCampaignAction
Thismethodupdatescampaignactioncriteria.
CriteriaofaSegment
UpdatetheCampaign
TrackableLinkCriteriaofa Thismethodupdatescampaigntrackedlinkcriteria.
Segment
UpdatetheTrigger
CampaignActionCriteriaof ThismethodupdatesTriggerCampaignactioncriteria.
aSegment
UpdatetheTrigger
CampaignTrackableLink ThismethodupdatesTriggerCampaigntrackedlinkcriteria.
CriteriaofaSegment
UpdatetheSocialCriteriaof
Thismethodupdatessocialcriteria.
aSegment
UpdatetheRecencyCriteria
Thismethodupdatesquicksegmentcriteria.
ofaSegment
UpdatetheDataMart
ThismethodupdatesDataMartcriteria.
CriteriaofaSegment
www.smartfocus.com 10