Fetch All Campaigns
/rest/api/v1.3/campaigns
Request
- application/x-www-form-urlencoded
-
limit: integer
Number of campaigns to return in the response (defaults to 200 and cannot exceed 200)
-
offset: integer
Starts at 0 and indicates the record number for the response result set
-
type: string
The type of campaigns to return in the response (email, push, sms, mms or pushiocampaign, defaults to email)
Response
- application/json
Default Response
object
Campaign
-
appName(optional):
string
Name of the app associated with the campaign. Only applicable to Message Center campaigns
-
attachmentPaths(optional):
array attachmentPaths
Attachments for the campaign.
-
autoCloseOption(optional):
string
Allowed Values:
[ "NO_AUTO_CLOSE", "AUTO_CLOSE_X_DAYS_AFTER_LAUNCH", "AUTO_CLOSE_X_DAYS_AFTER_LAST_RESPONSE", "AUTO_CLOSE_ON_DATE" ]
Auto close options for this campaign. -
autoCloseValue(optional):
string
This represents number of days if autoCloseOption is AUTO_CLOSE_X_DAYS_AFTER_LAUNCH or AUTO_CLOSE_X_DAYS_AFTER_LAST_RESPONSE.This represents date if autoCloseOption is AUTO_CLOSE_ON_DATE.
-
bccEmail(optional):
string
Bcc Email Address for the campaign.
-
campaignStatus(optional):
string
Allowed Values:
[ "NONE", "DRAFT", "ACTIVE", "CLOSED" ]
Status of the campaign. -
campaignVariables(optional):
object campaignVariables
Additional Properties Allowed: additionalPropertiesMap
of Name and value of campaign variables which are used as default values for text replacement. -
closedCampaignURL(optional):
string
The URL to redirect to if a recipient clicks on a link of an already closed campaign.
-
description(optional):
string
Description of the campaign.
-
destinationMessageCenter(optional):
string
Destination Message Center for the campaign. Only applicable to Message Center campaigns
-
enableExternalTracking(optional):
boolean
Enable to use third-party web analytics service that use tracking parameters appended to the URLs.
-
enableLinkTracking(optional):
boolean
Enable to track the links in a campaign.
-
externalCampaignCode(optional):
string
External campaign code.
-
externalTrackingParams(optional):
object externalTrackingParams
Additional Properties Allowed: additionalPropertiesMap
of Name and value of external tracking parameters. -
filterPaths(optional):
array filterPaths
Paths of filter to be used for this campaign. This can be used to select a group of customers to receive specific messages. Either standard filter or SQL View can be specified.
-
folderName(optional):
string
Folder name for the campaign.
-
fromEmail(optional):
string
From Email Address for the campaign.
-
fromName(optional):
string
From Name for the campaign.
-
htmlMessagePath(optional):
string
HTML message folder and path for the campaign.
-
id(optional):
string
ID of the campaign.
-
linkTablePath(optional):
string
Link table to be included in this campaign.
-
listName(optional):
string
Profile list name which contains the audience for this campaign.
-
locale(optional):
string
The default recipient locale for this account.
-
marketingProgram(optional):
string
Type of marketing program. The values are defined by the Account Administrator.
-
marketingStrategy(optional):
string
Type of marketing strategy. The values are defined by the Account Administrator.
-
name(optional):
string
Name of the campaign.
-
proofListPath(optional):
string
Before sending the campaign to customers, send it to proof list for testing.
-
purpose(optional):
string
Allowed Values:
[ "PROMOTIONAL", "TRANSACTIONAL" ]
Purpose of the campaign. -
refiningDataSourcePath(optional):
string
Path of additional data sources to be used for this campaign.
-
replyToEmail(optional):
string
Reply To Email Address for the campaign.
-
salesForceCampaignId(optional):
string
Salesforce campaign id.
-
seedListPath(optional):
string
Seed lists recipients receive the campaign when it is launched but are excluded from live report.
-
segmentPaths(optional):
array segmentPaths
Segmentations are used to divide a list into segments using attributes of a profile extension table or profile list.
-
segmentTrackingColumnName(optional):
string
Column name for tracking segments.
-
sendTextIfHTMLUnknown(optional):
boolean
If HTML ability is unknown, this option allows sending MIME messages to ensure message text is displayed correctly.
-
subject(optional):
string
Campaign Subject.
-
supplementaryCampaignDataSourcePaths(optional):
array supplementaryCampaignDataSourcePaths
Supplementary data sources can be used for inclusions or exclusions of the audience.
-
supplementaryProofDataSourcePaths(optional):
array supplementaryProofDataSourcePaths
Supplementary proof data sources can be used for inclusions or exclusions from proof list.
-
supplementarySeedDataSourcePaths(optional):
array supplementarySeedDataSourcePaths
Supplementary seed data sources can be used for inclusions or exclusions from seed list.
-
suppressionListPaths(optional):
array suppressionListPaths
This is used to exclude recipients from data sources.
-
textMessagePath(optional):
string
Text message folder and path for the campaign.
-
trackConversions(optional):
boolean
This applies only when link tracking is enabled for the campaign. This option can be used to record conversion when clicking a link and following through a specific web page.
-
trackHTMLOpens(optional):
boolean
Enable tracking when each recipient with HTML capability opened the email.
-
type(optional):
string
Allowed Values:
[ "EMAIL", "PUSH", "SMS", "MMS", "PUSHIOCAMPAIGN" ]
Type of the campaign. It can be EMAIL or PUSH or SMS or MMS or PUSHIOCAMPAIGN. -
unsubscribeFormName(optional):
string
Form name to be used for unsubscribing..
-
unsubscribeOption(optional):
string
Allowed Values:
[ "NO_OPTOUT_BUTTON", "OPTOUT_SINGLE_CLICK", "OPTOUT_FORM" ]
The unsubscribe option for this campaign. -
useUTF8(optional):
boolean
Use UTF8 encoding for messages.
object
object
array
array
array
array
array
array
Examples
Use this interface to get campaigns of a particular type (EMD Email, SMS, MMS, Message Center, or Push) and their properties. Use the type
attribute to select the type of campaign objects to return.
- "Email" returns EMD email campaigns only; it does not return Classic campaigns.
- "Push" (
type=push
) includes Push, Rich Push, and In-app campaigns. To query for "Message Center" campaigns separately, use thetype=pushiocampaign
query attribute.
IMPORTANT: To get all EMD email campaigns, your account must be enabled for Email Message Designer (EMD). To get all Push campaigns, your account must be enabled for Push. To get all Message Center campaigns, your account must be enabled for Push and for Message Center. To get all SMS campaigns, you account must be enabled for SMS. To get all MMS campaigns, you account must be enabled for MMS. Otherwise using the call will result in an error with HTTPS status code of 401 Unauthorized and API_DISABLED_FOR_USER in the error message payload.
Required request headers:
FIELDS | DESCRIPTION |
---|---|
Authorization | <AUTH_TOKEN> |
Content-Type | application/json |
Request parameters:
FIELDS | DESCRIPTION |
---|---|
offset | starts at 0 and indicates the record number for the response result set (defaults to 0) |
limit | number of campaigns to return in the response (defaults to 200 and cannot exceed 200) |
type | the type of campaigns to return in the response (email, sms, mms, push, or pushiocampaign; it defaults to email if you do not specify a type) |
Response Notes:
- The response contains an array of up to 200 campaign objects per request. Use the
next
link in the response to get the next set of objects (if there are more than 200). - This API does not support fetching Classic Email campaigns, so the response will not contain Classic Email campaign objects.
- Each item in the array contains a campaign object, which includes the campaign ID and the campaign's other properties.
- The campaign properties returned in the response may vary, depending on what was configured for the campaign when it was created.
- The response also contains a links array for the interface. This array contains the endpoints for obtaining the previous and next batch of campaign objects. Campaign operations links may or may not be supported by your level of access. The campaign properties returned in the response may vary, depending on what has been configured for the campaign in Responsys.
- By default, Campaign Purpose is "Promotional" for Push.
- The response body for Push and for Message Center queries include a new property,
channelList
. The value is the App Channel List name used by the campaign, and this property is only returned whentype=push
ortype=pushiocampaign
. - The response body includes some EMD campaign attributes, which may or may not be applicable for other campaign types. These values are set either to "false" or to the account-level settings. Examples:
"trackHTMLOpens": false, "trackConversions": false, "sendTextIfHTMLUnknown": false, "unsubscribeOption": "OPTOUT_SINGLE_CLICK", "autoCloseOption": "AUTO_CLOSE_X_DAYS_AFTER_LAUNCH", "autoCloseValue": "30"
- When an account has no campaigns for the type you have requested, a
200 OK
status is returned but the campaigns array in the response body is empty.
Sample Request URL for Email:
TIP: Leave the following parameters set to their default values and use the "prev" and "next" links returned in the response to get additional EMD campaigns as needed.
/rest/api/v1.3/campaigns?type=email
Sample Response
{ "campaigns": [ { "id": 1000, "name": "testcampaign-b11", "folderName": "testfolder", "type": "EMAIL", "campaignStatus": "ACTIVE", "description": "description", "purpose": "PROMOTIONAL", "marketingStrategy": "strategy", "marketingProgram": "program", "listName": "listname", "filterPaths": [ "foldername/objectName1", "foldername/objectName2" ], "refiningDataSourcePath": "foldername/objectName1", "proofListPath": "foldername/objectName1", "seedListPath": "foldername/objectName1", "segmentPaths": [ "foldername/objectName1", "foldername/objectName2" ], "supplementaryCampaignDataSourcePaths": [ "foldername/objectName1", "foldername/objectName2" ], "supplementaryLookupDataSourcePaths"[ "foldername/objectName1", "foldername/objectName2" ], "supplementaryProofDataSourcePaths": [ "foldername/objectName1", "foldername/objectName2" ], "supplementarySeedDataSourcePaths": [ "foldername/objectName1", "foldername/objectName2" ], "suppressionListPaths": [ "foldername/objectName1", "foldername/objectName2" ], "subject": "subject", "fromName": "from name", "fromEmail": "from email", "replyToEmail": "reply to email", "bccEmail": "bcc email", "htmlMessagePath": "documentPath", "textMessagePath": "documentPath", "enableExternalTracking": true, "externalTrackingParams": { "name1": "value1", "name2": "value2" }, "enableLinkTracking": true, "linkTablePath": "foldername/objectName1", "attachmentPaths": [ "documentPath1", "documentPath2" ], "campaignVariables": { "name1": "value1", "name2": "value2" }, "useUTF8": true, "locale": "value", "trackHTMLOpens": true, "trackConversions": true, "sendTextIfHTMLUnknown": true, "segmentTrackingColumnName": "name", "unsubscribeOption": "OPTOUT_SINGLE_CLICK", "unsubscribeFormName": "name", "autoCloseOption": "NO_AUTO_CLOSE", "autoCloseValue": "value", "closedCampaignURL": "URL", "externalCampaignCode": "code", "salesForceCampaignId": "salesforce id", "links": [ { "rel": "self", "href": "/rest/api/v1.3/campaigns/testcampaign-b11", "method": "GET" }, { "rel": "create", "href": "/rest/api/v1.3/campaigns", "method": "POST" }, { "rel": "updateCampaign", "href": "rest/api/v1.3/campaigns/testcampaign-b11", "method": "PUT" } ] }, { "id": 1001, "name": "testcampaign-b12", "folderName": "testfolder", "type": "EMAIL", "campaignStatus": "ACTIVE", "description": "description", "purpose": "PROMOTIONAL", "marketingStrategy": "strategy", "marketingProgram": "program", "listName": "listname", "filterPaths": [ "foldername/objectName1", "foldername/objectName2" ], "refiningDataSourcePath": "foldername/objectName1", "proofListPath": "foldername/objectName1", "seedListPath": "foldername/objectName1", "segmentPaths": [ "foldername/objectName1", "foldername/objectName2" ], "supplementaryCampaignDataSourcePaths": [ "foldername/objectName1", "foldername/objectName2" ], "supplementaryLookupDataSourcePaths"[ "foldername/objectName1", "foldername/objectName2" ], "supplementaryProofDataSourcePaths": [ "foldername/objectName1", "foldername/objectName2" ], "supplementarySeedDataSourcePaths": [ "foldername/objectName1", "foldername/objectName2" ], "suppressionListPaths": [ "foldername/objectName1", "foldername/objectName2" ], "subject": "subject", "fromName": "from name", "fromEmail": "from email", "replyToEmail": "reply to email", "bccEmail": "bcc email", "htmlMessagePath": "documentPath", "textMessagePath": "documentPath", "enableExternalTracking": true, "externalTrackingParams": { "name1": "value1", "name2": "value2" }, "enableLinkTracking": true, "linkTablePath": "foldername/objectName1", "attachmentPaths": [ "documentPath1", "documentPath2" ], "campaignVariables": { "name1": "value1", "name2": "value2" }, "useUTF8": true, "locale": "value", "trackHTMLOpens": true, "trackConversions": true, "sendTextIfHTMLUnknown": true, "segmentTrackingColumnName": "name", "unsubscribeOption": "OPTOUT_SINGLE_CLICK", "unsubscribeFormName": "name", "autoCloseOption": "NO_AUTO_CLOSE", "autoCloseValue": "value", "closedCampaignURL": "URL", "externalCampaignCode": "code", "salesForceCampaignId": "salesforce id", "links": [ { "rel": "self", "href": "/rest/api/v1.3/campaigns/testcampaign-b12", "method": "GET" }, { "rel": "create", "href": "/rest/api/v1.3/campaigns", "method": "POST" }, { "rel": "updateCampaign", "href": "rest/api/v1.3/campaigns/testcampaign-b12", "method": "PUT" } ] } ], "links": [ { "rel": "self", "href": "/rest/api/v1.3/campaigns?type=email", "method": "GET" }, { "rel": "prev", "href": "/rest/api/v1.3/campaigns?limit=200&offset=0&type=email", "method": "GET" }, { "rel": "next", "href": "rest/api/v1.3/campaigns?limit=200&offset=200&type=email", "method": "GET" } ] }
Sample Request URL for Push campaigns
TIP: Leave the following parameters set to their default values and use the "prev" and "next" links returned in the response to get additional Push campaigns as needed.
/rest/api/v1.3/campaigns?type=push
Sample Response
{ "campaigns": [ { "id": 1000, "name": "testcampaign-b11", "folderName": "testfolder", "type": "PUSH", "campaignStatus": "ACTIVE", "description": "description", "purpose": "PROMOTIONAL", "marketingStrategy": "strategy", "marketingProgram": "program", "listName": "listname", "channelList": "channelListName", "filterPaths": [ "foldername/objectName1", "foldername/objectName2" ], "refiningDataSourcePath": "foldername/objectName1", "proofListPath": "foldername/objectName1", "seedListPath": "foldername/objectName1", "segmentPaths": [ "foldername/objectName1", "foldername/objectName2" ], "supplementaryCampaignDataSourcePaths": [ "foldername/objectName1", "foldername/objectName2" ], "supplementaryLookupDataSourcePaths"[ "foldername/objectName1", "foldername/objectName2" ], "supplementaryProofDataSourcePaths": [ "foldername/objectName1", "foldername/objectName2" ], "supplementarySeedDataSourcePaths": [ "foldername/objectName1", "foldername/objectName2" ], "suppressionListPaths": [ "foldername/objectName1", "foldername/objectName2" ], "subject": "subject", "fromName": "from name", "fromEmail": "from email", "replyToEmail": "reply to email", "bccEmail": "bcc email", "htmlMessagePath": "documentPath", "textMessagePath": "documentPath", "enableExternalTracking": true, "externalTrackingParams": { "name1": "value1", "name2": "value2" }, "enableLinkTracking": true, "linkTablePath": "foldername/objectName1", "attachmentPaths": [ "documentPath1", "documentPath2" ], "campaignVariables": { "name1": "value1", "name2": "value2" }, "useUTF8": true, "locale": "value", "trackHTMLOpens": true, "trackConversions": true, "sendTextIfHTMLUnknown": true, "segmentTrackingColumnName": "name", "unsubscribeOption": "OPTOUT_SINGLE_CLICK", "unsubscribeFormName": "name", "autoCloseOption": "NO_AUTO_CLOSE", "autoCloseValue": "value", "closedCampaignURL": "URL", "externalCampaignCode": "code", "salesForceCampaignId": "salesforce id" }, { "id": 1001, "name": "testcampaign-b12", "folderName": "testfolder", "type": "PUSH", "campaignStatus": "DRAFT", "description": "description", "purpose": "PROMOTIONAL", "marketingStrategy": "strategy", "marketingProgram": "program", "listName": "listname", "channelList": "channelListName", "filterPaths": [ "foldername/objectName1", "foldername/objectName2" ], "refiningDataSourcePath": "foldername/objectName1", "proofListPath": "foldername/objectName1", "seedListPath": "foldername/objectName1", "segmentPaths": [ "foldername/objectName1", "foldername/objectName2" ], "supplementaryCampaignDataSourcePaths": [ "foldername/objectName1", "foldername/objectName2" ], "supplementaryLookupDataSourcePaths"[ "foldername/objectName1", "foldername/objectName2" ], "supplementaryProofDataSourcePaths": [ "foldername/objectName1", "foldername/objectName2" ], "supplementarySeedDataSourcePaths": [ "foldername/objectName1", "foldername/objectName2" ], "suppressionListPaths": [ "foldername/objectName1", "foldername/objectName2" ], "subject": "subject", "fromName": "from name", "fromEmail": "from email", "replyToEmail": "reply to email", "bccEmail": "bcc email", "htmlMessagePath": "documentPath", "textMessagePath": "documentPath", "enableExternalTracking": true, "externalTrackingParams": { "name1": "value1", "name2": "value2" }, "enableLinkTracking": true, "linkTablePath": "foldername/objectName1", "attachmentPaths": [ "documentPath1", "documentPath2" ], "campaignVariables": { "name1": "value1", "name2": "value2" }, "useUTF8": true, "locale": "value", "trackHTMLOpens": true, "trackConversions": true, "sendTextIfHTMLUnknown": true, "segmentTrackingColumnName": "name", "unsubscribeOption": "OPTOUT_SINGLE_CLICK", "unsubscribeFormName": "name", "autoCloseOption": "NO_AUTO_CLOSE", "autoCloseValue": "value", "closedCampaignURL": "URL", "externalCampaignCode": "code", "salesForceCampaignId": "salesforce id" } ], "links": [ { "rel": "self", "href": "/rest/api/v1.3/campaigns?type=push", "method": "GET" }, { "rel": "prev", "href": "/rest/api/v1.3/campaigns?limit=200&offset=0&type=push", "method": "GET" }, { "rel": "next", "href": "rest/api/v1.3/campaigns?limit=200&offset=200&type=push", "method": "GET" } ] }
Sample Request URL for SMS campaigns
TIP: Leave the following parameters set to their default values and use the "prev" and "next" links returned in the response to get additional SMS campaigns as needed.
/rest/api/v1.3/campaigns?type=sms
Sample Response
The endpoint /rest/api/v1.3/campaigns?type=sms
returned the following response (in this account, the limit set was for 5 campaigns, but there were only two SMS campaigns for the account):
{ "campaigns": [ { "id": 1234, "name": "SMS_CAMP1", "folderName": "Folder1", "type": "SMS", "campaignStatus": "DRAFT", "purpose": "PROMOTIONAL", "listName": "R_SMS_LIST1", "textMessagePath": "/messagelibrary/sms/13187/Message.txt", "enableLinkTracking": false, "enableExternalTracking": false, "useUTF8": false, "trackHTMLOpens": false, "trackConversions": false, "sendTextIfHTMLUnknown": false, "unsubscribeOption": "OPTOUT_SINGLE_CLICK", "autoCloseOption": "AUTO_CLOSE_X_DAYS_AFTER_LAST_RESPONSE", "autoCloseValue": "90" }, { "id": 12345, "name": "SMS_CAMP2", "folderName": "Folder2", "type": "SMS", "campaignStatus": "ACTIVE", "purpose": "PROMOTIONAL", "listName": "R_SMS_LIST2", "textMessagePath": "/messagelibrary/sms/13687/Message.txt", "enableLinkTracking": false, "enableExternalTracking": false, "campaignVariables": { "SMS_CARRIER": null, "SMS_USER_INPUT1": null, "SMS_USER_INPUT2": null, "SMS_USER_INPUT3": null, "SMS_USER_INPUT4": null, "SMS_USER_INPUT5": null, "SMS_CODE": null, "SMS_KEYWORD": " Default" }, "useUTF8": false, "trackHTMLOpens": false, "trackConversions": false, "sendTextIfHTMLUnknown": false, "unsubscribeOption": "OPTOUT_SINGLE_CLICK", "autoCloseOption": "AUTO_CLOSE_X_DAYS_AFTER_LAST_RESPONSE", "autoCloseValue": "90" } ], "links": [ { "rel": "self", "href": "/rest/api/v1.3/campaigns?type=sms", "method": "GET" }, { "rel": "prev", "href": "/rest/api/v1.3/campaigns?limit=5&offset=0&type=sms", "method": "GET" }, { "rel": "next", "href": "rest/api/v1.3/campaigns?limit=5&offset=200&type=sms", "method": "GET" } ] }
Sample Request URL for MMS:
TIP: Leave the following parameters set to their default values and use the "prev" and "next" links returned in the response to get additional MMS campaigns as needed.
/rest/api/v1.3/campaigns?type=mms
Sample Response
{ "campaigns": [ { "id": 10016762, "name": "test-mms", "folderName": "examples", "type": "MmsCampaign", "campaignStatus": "ACTIVE", "purpose": "PROMOTIONAL", "textMessagePath": "/messagelibrary/mms/10016762/Message.txt", "enableLinkTracking": false, "attachmentPaths": [ null ], "enableExternalTracking": false, "useUTF8": false, "trackHTMLOpens": false, "trackConversions": false, "sendTextIfHTMLUnknown": false, "autoCloseOption": "None" }, . . . { "id": 11081025, "name": "AG_AudienceTest_MMS", "folderName": "AG-Test", "type": "MmsCampaign", "campaignStatus": "ACTIVE", "purpose": "PROMOTIONAL", "listName": "2018 list", "textMessagePath": "/messagelibrary/mms/11081025/Message.txt", "enableLinkTracking": false, "attachmentPaths": [ "/contentlibrary/2018_content^sale70.jpg" ], "enableExternalTracking": false, "useUTF8": false, "trackHTMLOpens": false, "trackConversions": false, "sendTextIfHTMLUnknown": false, "autoCloseOption": "None" } ], "links": [ { "rel": "self", "href": "/rest/api/v1.3/campaigns?type=mms", "method": "GET" } ] }
Sample Request URL for Message Center:
TIP: Leave the following parameters set to their default values and use the "prev" and "next" links returned in the response to get additional Message Center campaigns as needed.
/rest/api/v1.3/campaigns?type=pushiocampaign
Sample Response
The response data for Message Center campaigns returns two attributes that are specific to this channel: appName
contains the name of the mobile app, and destinationMessageCenter
contains the name of the message center to which the marketer wanted the campaign message to be sent.
{ "campaigns": [ { "id": 11896453, "name": "jmp-test-mc-021419", "folderName": "jmp-test", "type": "PushIOCampaign", "campaignStatus": "DRAFT", "purpose": "PROMOTIONAL", "marketingStrategy": "Other", "marketingProgram": "Other", "listName": "mmlist", "channelList": "mm_APP", "appName": "JMP Training App", "destinationMessageCenter": "Primary", "textMessagePath": "/messagelibrary/push/11896453/Message.txt", "enableLinkTracking": false, "enableExternalTracking": false, "useUTF8": false, "trackHTMLOpens": false, "trackConversions": false, "sendTextIfHTMLUnknown": false } ], "links": [ { "rel": "self", "href": "/rest/api/v1.3/campaigns?type=pushiocampaign", "method": "GET" } ] }