Smart Campaigns
Marketo offers a set of REST APIs for performing operations on smart campaigns. These APIs follow the standard interface pattern for asset APIs providing query, create, clone, and delete options. Also, you can manage smart campaign execution by scheduling batch campaigns or requesting trigger campaigns.
Query
Querying smart campaigns follows the standard query types for assets of by id,听by name, and聽browsing.
By Id
罢丑别听聽endpoint takes a single smart campaign id as a path parameter and returns a single smart campaign record.
GET /rest/asset/v1/smartCampaign/{id}.json
{
"success": true,
"errors": [],
"requestId": "7883#169838a32f0",
"warnings": [],
"result": [
{
"id": 1001,
"name": "Process Bounced Emails",
"description": "System smart campaign for processing bounced email events",
"createdAt": "2016-09-10T23:16:19Z+0000",
"updatedAt": "2016-09-10T23:16:19Z+0000",
"status": "Never Run",
"type": "batch",
"isSystem": false,
"isActive": false,
"isRequestable": false,
"isCommunicationLimitEnabled": false,
"recurrence": {
"weekdayOnly": false
},
"qualificationRuleType": "once",
"workspace": "Default",
"smartListId": 1001,
"flowId": 1001,
"computedUrl": "https://app-sjqe.marketo.com/#SC1001A1"
}
]
}
With this endpoint, there will always be a single record in the first position of the result array.
By Name
罢丑别听 endpoint takes a single smart campaign name as a parameter and returns a single smart campaign record.
GET /rest/asset/v1/smartCampaign/byName.json?name=Test Trigger Campaign
{
"success": true,
"errors": [],
"requestId": "14494#16c886ffa44",
"warnings": [],
"result": [
{
"id": 1069,
"name": "Test Trigger Campaign",
"description": "",
"createdAt": "2018-02-16T01:34:39Z+0000",
"updatedAt": "2019-08-13T00:45:21Z+0000",
"folder": {
"id": 327,
"type": "Folder"
},
"status": "Inactive",
"type": "trigger",
"isSystem": false,
"isActive": false,
"isRequestable": false,
"isCommunicationLimitEnabled": false,
"recurrence": {
"weekdayOnly": false
},
"qualificationRuleType": "once",
"workspace": "Default",
"smartListId": 2747,
"flowId": 1088,
"computedUrl": "https://app-sjqe.marketo.com/#SC1069A1"
}
]
}
With this endpoint, there will always be a single record in the first position of the result array.
Browse
The endpoint works like other Asset API browse endpoints and allows several optional query parameters to specify filtering criteria.
The earliestUpdatedAt and latestUpdatedAt parameters accept datetimes in the ISO-8601 format (without milliseconds). If both are set, then earliestUpdatedAt must precede latestUpdatedAt.
The folder parameter specifies the parent folder to browse under. The format is JSON block containing id and type attributes.
The maxReturn parameter is an integer that specifies the maximum number of entries to return. Default is 20. Maximum is 200.
The offset parameter is an integer that specifies where to begin retrieving entries. Can be used on conjunction with maxReturn. Default is 0.
The isActive parameter is a boolean that specifies to return only active Trigger campaigns.
GET /rest/asset/v1/smartCampaigns.json?earliestUpdatedAt=2016-09-10T23:15:00-00:00&latestUpdatedAt=2016-09-10T23:17:00-00:00
{
"success": true,
"errors": [],
"requestId": "626#16983a92965",
"warnings": [],
"result": [
{
"id": 1001,
"name": "Process Bounced Emails",
"description": "System smart campaign for processing bounced email events",
"createdAt": "2016-09-10T23:16:19Z+0000",
"updatedAt": "2016-09-10T23:16:19Z+0000",
"status": "Never Run",
"type": "batch",
"isSystem": false,
"isActive": false,
"isRequestable": false,
"isCommunicationLimitEnabled": false,
"recurrence": {
"weekdayOnly": false
},
"qualificationRuleType": "once",
"workspace": "Default",
"smartListId": 1001,
"flowId": 1001,
"computedUrl": "https://app-sjqe.marketo.com/#SC1001A1"
},
{
"id": 1002,
"name": "Process Unsubscribes",
"description": "System smart campaign for processing unsubscribe events",
"createdAt": "2016-09-10T23:16:19Z+0000",
"updatedAt": "2016-09-10T23:16:19Z+0000",
"status": "Never Run",
"type": "batch",
"isSystem": false,
"isActive": false,
"isRequestable": false,
"isCommunicationLimitEnabled": false,
"recurrence": {
"weekdayOnly": false
},
"qualificationRuleType": "once",
"workspace": "Default",
"smartListId": 1002,
"flowId": 1002,
"computedUrl": "https://app-sjqe.marketo.com/#SC1002A1"
}
]
}
With this endpoint, there will be one or more records in the result array.
Create
The endpoint is executed with an application/x-www-form-urlencoded POST with two required parameters. The name parameter specifies the name of the smart campaign to create. The folder parameter specifies the parent folder where the smart campaign is created. The format is JSON block containing id and type attributes.
Optionally, you may describe the smart campaign using the description parameter (maximum 2,000 characters).
POST /rest/asset/v1/smartCampaigns.json
Content-Type: application/x-www-form-urlencoded
name=Smart Campaign 02&folder={"type": "folder","id": 640}&description=This is a smart campaign creation test.
{
"success": true,
"errors": [],
"requestId": "25bc#16c9138f148",
"warnings": [],
"result": [
{
"id": 1076,
"name": "Smart Campaign 02",
"description": "This is a smart campaign creation test.",
"createdAt": "2019-08-14T17:42:04Z+0000",
"updatedAt": "2019-08-14T17:42:04Z+0000",
"folder": {
"id": 640,
"type": "Folder"
},
"status": "Never Run",
"type": "batch",
"isSystem": false,
"isActive": false,
"isRequestable": false,
"isCommunicationLimitEnabled": true,
"recurrence": {
"weekdayOnly": false
},
"qualificationRuleType": "once",
"workspace": "Default",
"smartListId": 5132,
"flowId": 1095,
"computedUrl": "https://app-sjqe.marketo.com/#SC1076A1"
}
]
}
Update
The endpoint is executed with an application/x-www-form-urlencoded POST. It takes a single smart campaign id as a path parameter. You can use the name parameter to update the name of the smart campaign, or the description parameter to update the description of the smart campaign.
POST /rest/asset/v1/smartCampaign/{id}.json
Content-Type: application/x-www-form-urlencoded
name=Smart Campaign 02 Update&description=This is a smart campaign update test.
{
"success": true,
"errors": [],
"requestId": "14b6a#16c924b992f",
"warnings": [],
"result": [
{
"id": 1076,
"name": "Smart Campaign 02 Update",
"description": "This is a smart campaign update test.",
"createdAt": "2019-08-14T17:42:04Z+0000",
"updatedAt": "2019-08-14T22:42:04Z+0000",
"folder": {
"id": 640,
"type": "Folder"
},
"status": "Never Run",
"type": "batch",
"isSystem": false,
"isActive": false,
"isRequestable": false,
"isCommunicationLimitEnabled": true,
"recurrence": {
"weekdayOnly": false
},
"qualificationRuleType": "once",
"workspace": "Default",
"smartListId": 5132,
"flowId": 1095,
"computedUrl": "https://app-sjqe.marketo.com/#SC1076A1"
}
]
}
Clone
The endpoint is executed with an application/x-www-form-urlencoded POST with three required parameters. It takes an id parameter that specifies the smart campaign to clone, a name parameter that specifies the name of new smart campaign, and a folder parameter to specify the parent folder where the new smart campaign is created. The format is JSON block containing id and type attributes.
Optionally, you may describe the smart campaign using the description聽parameter (maximum 2,000 characters).
POST /rest/asset/v1/smartCampaign/{id}/clone.json
Content-Type: application/x-www-form-urlencoded
name=Test Trigger Campaign Clone&folder={"type": "folder","id": 640}&description=This is a smart campaign clone test.
{
"success": true,
"errors": [],
"requestId": "681d#16c9339499b",
"warnings": [],
"result": [
{
"id": 1077,
"name": "Test Trigger Campaign Clone",
"description": "This is a smart campaign clone test.",
"createdAt": "2019-08-15T03:01:41Z+0000",
"updatedAt": "2019-08-15T03:01:41Z+0000",
"folder": {
"id": 640,
"type": "Folder"
},
"status": "Inactive",
"type": "trigger",
"isSystem": false,
"isActive": false,
"isRequestable": false,
"isCommunicationLimitEnabled": false,
"recurrence": {
"weekdayOnly": false
},
"qualificationRuleType": "once",
"workspace": "Default",
"smartListId": 5135,
"flowId": 1096,
"computedUrl": "https://app-sjqe.marketo.com/#SC1077A1"
}
]
}
Delete
罢丑别听聽endpoint takes a single smart campaign id as a path parameter.
POST /rest/asset/v1/smartCampaign/{id}/delete.json
{
"success": true,
"errors": [],
"requestId": "d757#16c934216ac",
"warnings": [],
"result": [
{
"id": 1077
}
]
}
Batch
Batch smart campaigns launch at a specific time and affect a specific set of leads all at once.
Schedule
Use the 聽endpoint to schedule a batch campaign to run either immediately or at a future date. The campaign id is a required path parameter. Optional parameters are聽tokens, runAt, and cloneToProgram聽which are passed in the request body as application/json.
The tokens array parameter is an array of My Tokens聽which override existing program tokens. After the campaign runs, the tokens are discarded.聽聽Each token array item contains name/value pairs. The name of the token must be formatted as聽鈥渰{my.name}}鈥�.
The runAt datetime parameter specifies when to run the campaign. If not specified, the campaign will be run 5 minutes after the endpoint has been called. The datetime value cannot be more than two years into the future.
Campaigns scheduled via this API always wait a minimum of five minutes before running.
The cloneToProgram string parameter contains the name of a resulting program.聽聽When set, this causes the campaign, parent program, and all of its assets to be created with the resulting new name. The parent program is cloned and the newly created campaign will be scheduled. The resulting program is created underneath the parent. Programs with snippets, push notifications, in-app messages, static lists, reports, and social assets may not be cloned in this way. When used, this endpoint is limited to 20 calls per day. The endpoint is the recommended alternative.
POST /rest/v1/campaigns/{id}/schedule.json
{
"input":
{
"runAt": "2018-03-28T18:05:00+0000",
"tokens": [
{
"name": "{{my.message}}",
"value": "Updated message"
},
{
"name": "{{my.other token}}",
"value": "Value for other token"
}
]
}
}
{
"requestId": "52b#161d90e1743",
"result": [
{
"id": 3713
}
],
"success": true
}
Trigger
Trigger smart campaigns affect one person at a time based on a triggered event.
Request
Use the聽聽endpoint to pass a set of leads to a trigger campaign to run through the campaign鈥檚 flow. The campaign must have a 鈥淐ampaign is Requested鈥� trigger with 鈥淲eb Service API鈥� as the source.
This endpoint requires a campaign id as a path parameter, and a leads聽integer array parameter containing lead ids聽. A maximum of 100 leads is allowed per call.
Optionally, the tokens array parameter can be used to override My Tokens local to the campaign鈥檚 parent program.聽tokens聽accepts a maximum of 100 tokens. Each tokens array item contains a name/value pair. The name of the token must be formatted as 鈥渰{my.name}}鈥�. If you use Add a System Token as a Link in an Email approach to add the 鈥渧iewAsWebpageLink鈥� system token, you cannot override it using tokens. Instead use Add a View as Web Page Link to an Email approach which allows you to override 鈥渧iewAsWebPageLink鈥� using tokens.
The leads and tokens parameters are passed in the request body as application/json.
POST /rest/v1/campaigns/{id}/trigger.json
{
"input":
{
"leads" : [
{
"id" : 318592
},
{
"id" : 318593
}
],
"tokens" : [
{
"name": "{{my.message}}",
"value": "Updated message"
},
{
"name": "{{my.other token}}",
"value": "Value for other token"
}
]
}
}
{
"requestId": "9e01#161d922f1aa",
"result": [
{
"id": 3712
}
],
"success": true
}
Activate
The 聽endpoint is straightforward. An id path parameter is required. For activation to succeed, the following must be true for the campaign:
- Must be deactivated
- Must have at least one trigger, and one flow step
- Must have error free triggers, filters, and flow steps
POST /rest/asset/v1/smartCampaign/{id}/activate.json
{
"success": true,
"errors": [],
"requestId": "a33a#161d9c0dcf3",
"result": [
{
"id": 1069
}
]
}
Deactivate
The is straightforward. An id path parameter is required.聽For deactivation to succeed, the campaign must be activated.
POST /rest/asset/v1/smartCampaign/{id}/deactivate.json
{
"success": true,
"errors": [],
"requestId": "6228#161d9c29fbf",
"result": [
{
"id": 1069
}
]
}