Bridgeline Digital Logo
Menu

Subscription API

The Subscription API allows subscriptions to be listed, created, deleted, and modified. It also allows email schedules to be listed.

SubscriptionAPIRequest

A Subscription API request is made up of the following options. Availability may differ depending on the API method used:

request.parameters (Map<String, String>)

  • scheduleType: (optional, default: Automatic Mail-out), The type of schedules to return. Options are: Automatic Mail-out, Manual Mail-out.
  • subscriptionType: (optional, default: all), The type of subscriptions to return. Options are: all, scheduled, unscheduled.

request.listParameters (Map<String, List<String>>)

  • subscribers: (optional, default: current user), The list of subscribers to return subscriptions for. Subscribers are user ids, contact ids, lead ids, or email addresses. The Setup Scheduler permission is required to subscribe anyone other than yourself.
  • tagPaths: The list of taxonomy tag paths to return subscribers for.

getSchedules

This method returns all email schedules for the current site that match the schedule type.

Parameters

  • parameters.scheduleType: (optional, default: Automatic Mail-out), The type of schedules to return. Options are: Automatic Mail-out, Manual Mail-out.

Apex Request Example

SubscriptionAPIRequest request = new SubscriptionAPIRequest();
request.parameters.put(SubscriptionAPIRequest.SCHEDULE_TYPE, SubscriptionAPIRequest.SCHEDULE_TYPE_MANUAL);
 
Map<String, String> parameters = new Map<String, String>();
parameters.put('sname', 'site_name'); // Replace site_name with the name of your OrchestraCMS site
parameters.put('service', 'SubscriptionAPI');
parameters.put('action', 'getSchedules');
parameters.put('request', JSON.serialize(request));
parameters.put('apiVersion', '5.0');
 
String response = cms.ServiceEndpoint.doActionApex(parameters);
JSONMessage.APIResponse apiResponse = (JSONMessage.APIResponse) JSON.deserialize(response, JSONMessage.APIResponse.class);

if (!apiResponse.isSuccess) {
    throw new APIException('Could not retrieve information from the Subscription API');
}
if (apiResponse.type != 'List<ScheduleBundle>') {
    throw new APIException('Unexpected result from Subscription API');
}
 
System.debug(response); // Outputs response with ScheduleBundles

Javascript Request Example

var request = {
    parameters: {
        scheduleType: 'Manual Mail-out'
    }
};
var data = {
    service: 'SubscriptionAPI',
    action: 'getSchedules',
    request: JSON.stringify(request),
    apiVersion: '5.0'
};

// Handle response of a successful ajax call
var callBackHandler = function (json, Success) {
    console.log(json);
};
var options = {
    cb: callBackHandler,
    cbHandlerOnComplete: function(textStatus){},
    readonly: true
};

doServiceRequest(data, options);

getSubscriptions

This method returns all subscriptions for a list of subscribers, optionally filtered to only scheduled or unscheduled subscriptions.

Subscribers are user ids, contact ids, lead ids, or email addresses.

Parameters

  • parameters.subscriptionType: (optional, default: all), The type of subscriptions to return. Options are: all, scheduled, unscheduled.
  • subscribers: (optional, default: current user), The list of subscribers to return subscriptions for. The Setup Scheduler permission is required to subscribe anyone other than yourself.

Apex Request Example

SubscriptionAPIRequest request = new SubscriptionAPIRequest();
request.parameters.put(SubscriptionAPIRequest.SUBSCRIPTION_TYPE, 'scheduled');
request.listParameters.put(SubscriptionAPIRequest.SUBSCRIBERS, new List<String>{'a00000000000000000', 'a01000000000000000'});
 
Map<String, String> parameters = new Map<String, String>();
parameters.put('sname', 'site_name'); // Replace site_name with the name of your OrchestraCMS site
parameters.put('service', 'SubscriptionAPI');
parameters.put('action', 'getSubscriptions');
parameters.put('request', JSON.serialize(request));
parameters.put('apiVersion', '5.0');
 
String response = cms.ServiceEndpoint.doActionApex(parameters);
JSONMessage.APIResponse apiResponse = (JSONMessage.APIResponse) JSON.deserialize(response, JSONMessage.APIResponse.class);

 
if (!apiResponse.isSuccess) {
    throw new APIException('Could not retrieve information from the Subscription API');
}
if (apiResponse.type != 'Map<String, List<SubscriptionBundle>>') {
    throw new APIException('Unexpected result from Subscription API');
}
 
System.debug(response); // Outputs response with lists of SubscriptionBundles for requested subscribers

Javascript Request Example

var request = {
    parameters: {
        subscriptionType: 'scheduled'
    },
    listParameters: {
        subscriberIds: ['a00000000000000000', 'a01000000000000000']
    }
};
var data = {
    service: 'SubscriptionAPI',
    action: 'getSubscriptions',
    request: JSON.stringify(request),
    apiVersion: '5.0'
};

// Handle response of a successful ajax call
var callBackHandler = function (json, Success) {
    console.log(json);
};
var options = {
    cb: callBackHandler,
    cbHandlerOnComplete: function(textStatus){},
    readonly: true
};

doServiceRequest(data, options);

getSubscribedUsers

This method returns all subscribers who are subscribed to any of the provided taxonomy tag paths, optionally filtered by subscription type.

Parameters

  • parameters.subscriptionType: (optional, default: all), The type of subscription to filter by. Options are: all, scheduled, unscheduled.
  • listParameters.tagPaths: The list of taxonomy tag paths to return subscribers for.

Apex Request Example

SubscriptionAPIRequest request = new SubscriptionAPIRequest();
request.parameters.put(SubscriptionAPIRequest.SUBSCRIPTION_TYPE, 'scheduled');
request.listParameters.put(SubscriptionAPIRequest.TAG_PATHS, new List<String>{'/Taxonomy Path/Node A', '/Taxonomy Path/Node B'});
 
Map<String, String> parameters = new Map<String, String>();
parameters.put('sname', 'site_name');
parameters.put('service', 'SubscriptionAPI');
parameters.put('action', 'getSubscribedUsers');
parameters.put('request', JSON.serialize(request));
parameters.put('apiVersion', '5.0');
 
String response = cms.ServiceEndpoint.doActionApex(parameters);
JSONMessage.APIResponse apiResponse = (JSONMessage.APIResponse) JSON.deserialize(response, JSONMessage.APIResponse.class);

 
if (!apiResponse.isSuccess) {
    throw new APIException('Could not retrieve information from the Subscription API');
}
if (apiResponse.type != 'Map<String, List<String>>') {
    throw new APIException('Unexpected result from Subscription API');
}
 
System.debug(response); // Outputs response with a mapping of taxonomy path subscription to list of subscribers

Javascript Request Example

var request = {
    parameters: {
        subscriptionType: 'scheduled'
    },
    listParameters: {
        tagPaths: ['/Taxonomy Path/Node A', '/Taxonomy Path/Node B']
    }
};
var data = {
    service: 'SubscriptionAPI',
    action: 'getSubscribedUsers',
    request: JSON.stringify(request),
    apiVersion: '5.0'
};

// Handle response of a successful ajax call
var callBackHandler = function (json, Success) {
    console.log(json);
};
var options = {
    cb: callBackHandler,
    cbHandlerOnComplete: function(textStatus){},
    readonly: true
};

doServiceRequest(data, options);

subscribe

This method creates subscription records based on the provided SubscriptionBundles. If a duplicate subscription exists (based on subscriber and tagPath), it will be skipped.

Parameters

  • bundles[n].subscriber: (optional. default: current user) The user id, contact id, lead id, or email address to attribute this subscription to. The Setup Scheduler permission is required to subscribe anyone other than yourself.
  • bundles[n].tagPath: The taxonomy path to subscribe to.
  • bundles[n].schedule: (optional) The scheduleBundle to subscribe to (in the case of a scheduled subscription.)
  • bundles[n].suspended: (optional) Boolean indicating whether the scheduled subscription should be paused.
  • bundles[n].verified: (optional) Boolean indicating whether the subscriber's email has been verified (For scheduled subscriptions. Users are assumed verified and should be set to true. Contacts and Leads are guest subscriptions and should initially be set to false.)

Apex Request Example

// Create a scheduled subscription bundle
SubscriptionBundle bundle1 = new SubscriptionBundle();
bundle1.subscriber = 'a00000000000000000';
bundle1.tagPath = '/Taxonomy Path/Node A';
bundle1.schedule = new ScheduleBundle();
bundle1.schedule.scheduleId = 'a01000000000000000';
bundle1.verified = true;

// create an unscheduled subscription bundle
SubscriptionBundle bundle2 = new SubscriptionBundle();
bundle2.tagPath = '/Taxonomy Path/Node B';

SubscriptionAPIRequest request = new SubscriptionAPIRequest();
request.bundles = new List<SubscriptionBundle>{bundle1, bundle2};
 
Map<String, String> parameters = new Map<String, String>();
parameters.put('sname', 'site_name');
parameters.put('service', 'SubscriptionAPI');
parameters.put('action', 'subscribe');
parameters.put('request', JSON.serialize(request));
parameters.put('apiVersion', '5.0');
 
String response = cms.ServiceEndpoint.doActionApex(parameters);
JSONMessage.APIResponse apiResponse = (JSONMessage.APIResponse) JSON.deserialize(response, JSONMessage.APIResponse.class);

if (!apiResponse.isSuccess) {
    throw new APIException('Could not retrieve information from the Subscription API');
}
if (apiResponse.type != 'List<SubscriptionBundle>') {
    throw new APIException('Unexpected result from Subscription API');
}
 
System.debug(response); // Outputs response with a list of created subscriptions

Javascript Request Example

var request = {
    bundles: [
        {
            subscriber: 'a00000000000000000',
            tagPath: '/Taxonomy Path/Node A',
            schedule: {
                scheduleId: 'a01000000000000000',
            },
            verified: true
        },
        {
            tagPath: '/Taxonomy Path/Node B'
        }
    ]
};

var data = {
    service: 'SubscriptionAPI',
    action: 'subscribe',
    request: JSON.stringify(request),
    apiVersion: '5.0'
};

// Handle response of a successful ajax call
var callBackHandler = function (json, Success) {
    console.log(json);
}
var options = {
    cb: callBackHandler,
    cbHandlerOnComplete: function(textStatus){},
    readonly: true
};
doServiceRequest(data, options);

unsubscribe

This method deletes subscription records based on the provided SubscriptionBundles.

Parameters

  • bundles[n].subscriptionId: The subscription to delete. The Setup Scheduler permission is required to unsubscribe anyone other than yourself.

Apex Request Example

SubscriptionBundle bundle1 = new SubscriptionBundle();
bundle1.subscriptionId = 'a00000000000000000'

SubscriptionBundle bundle2 = new SubscriptionBundle();
bundle2.subscriptionId = 'a00000000000000001';

SubscriptionAPIRequest request = new SubscriptionAPIRequest();
request.bundles = new List<SubscriptionBundle>{bundle1, bundle2};
 
Map<String, String> parameters = new Map<String, String>();
parameters.put('sname', 'site_name');
parameters.put('service', 'SubscriptionAPI');
parameters.put('action', 'unsubscribe');
parameters.put('request', JSON.serialize(request));
parameters.put('apiVersion', '5.0');
 
String response = cms.ServiceEndpoint.doActionApex(parameters);
JSONMessage.APIResponse apiResponse = (JSONMessage.APIResponse) JSON.deserialize(response, JSONMessage.APIResponse.class);

 
if (!apiResponse.isSuccess) {
    throw new APIException('Could not retrieve information from the Subscription API');
}
if (apiResponse.type != 'Message') {
    throw new APIException('Unexpected result from Subscription API');
}
 
System.debug(response); // Outputs response with a status message

Javascript Request Example

var request = {
    bundles: [
        {
            subscriptionId: 'a00000000000000000'
        },
        {
            subscriptionId: 'a00000000000000001'
        }
    ]
};

var data = {
    service: 'SubscriptionAPI',
    action: 'unsubscribe',
    request: JSON.stringify(request),
    apiVersion: '5.0'
};

// Handle response of a successful ajax call
var callBackHandler = function (json, Success) {
    console.log(json);
}
var options = {
    cb: callBackHandler,
    cbHandlerOnComplete: function(textStatus){},
    readonly: true
};
doServiceRequest(data, options);

updateSubscriptions

This method modifies existing subscription records based on the provided SubscriptionBundles.

Parameters

  • bundles[n].subscriptionId: The subscription to update.
  • bundles[n].subscriber: The user id, contact id, lead id, or email address to attribute this subscription to. The Setup Scheduler permission is required to subscribe anyone other than yourself.
  • bundles[n].tagPath: The taxonomy path to subscribe to.
  • bundles[n].schedule: (optional) The scheduleBundle to subscribe to (in the case of a scheduled subscription.)
  • bundles[n].suspended: (optional) Boolean indicating whether the scheduled subscription should be paused.
  • bundles[n].verified: (optional) Boolean indicating whether the subscriber's email has been verified (For scheduled subscriptions. Users are assumed verified and should be set to true. Contacts and Leads are guest subscriptions and should initially be set to false.)

Apex Request Example

SubscriptionBundle bundle1 = new SubscriptionBundle();
bundle1.subscriptionId = 'a00000000000000000';
bundle1.tagPath = '/Taxonomy Path/Node A';
bundle1.schedule = new ScheduleBundle();
bundle1.schedule.scheduleId = 'a01000000000000000';
bundle1.verified = true;
bundle1.suspended = true;

SubscriptionBundle bundle2 = new SubscriptionBundle();
bundle2.subscriptionId = 'a00000000000000001';
bundle2.tagPath = '/Taxonomy Path/Node C';

SubscriptionAPIRequest request = new SubscriptionAPIRequest();
request.bundles = new List<SubscriptionBundle>{bundle1, bundle2};
 
Map<String, String> parameters = new Map<String, String>();
parameters.put('sname', 'Lightning_Components');
parameters.put('service', 'SubscriptionAPI');
parameters.put('action', 'updateSubscriptions');
parameters.put('request', JSON.serialize(request));
parameters.put('apiVersion', '5.0');
 
String response = cms.ServiceEndpoint.doActionApex(parameters);
JSONMessage.APIResponse apiResponse = (JSONMessage.APIResponse) JSON.deserialize(response, JSONMessage.APIResponse.class);

 
if (!apiResponse.isSuccess) {
    throw new APIException('Could not retrieve information from the Subscription API');
}
if (apiResponse.type != 'List<SubscriptionBundle>') {
    throw new APIException('Unexpected result from Subscription API');
}
 
System.debug(response); // Outputs response with a list of updated subscription bundles

Javascript Request Example

var request = {
    bundles: [
        {
            subscriptionId: 'a00000000000000000',
            tagPath: '/Taxonomy Path/Node A',
            schedule: {
                scheduleId: 'a01000000000000000',
            },
            verified: true
        },
        {
            subscriptionId: 'a00000000000000000',
            tagPath: '/Taxonomy Path/Node C'
        }
    ]
};

var data = {
    service: 'SubscriptionAPI',
    action: 'updateSubscriptions',
    request: JSON.stringify(request),
    apiVersion: '5.0'
};

// Handle response of a successful ajax call
var callBackHandler = function (json, Success) {
    console.log(json);
}
var options = {
    cb: callBackHandler,
    cbHandlerOnComplete: function(textStatus){},
    readonly: true
};
doServiceRequest(data, options);

setSubscriptions

This method deletes all subscription records for any subscriber provided, then creates new subscriptions based on the provided SubscriptionBundles.

Parameters

  • bundles[n].subscriber: (optional. default: current user) The user id, contact id, lead id, or email address to attribute this subscription to. The Setup Scheduler permission is required to subscribe anyone other than yourself.
  • bundles[n].tagPath: The taxonomy path to subscribe to.
  • bundles[n].schedule: (optional) The scheduleBundle to subscribe to (in the case of a scheduled subscription.)
  • bundles[n].suspended: (optional) Boolean indicating whether the scheduled subscription should be paused.
  • bundles[n].verified: (optional) Boolean indicating whether the subscriber's email has been verified (For scheduled subscriptions. Users are assumed verified and should be set to true. Contacts and Leads are guest subscriptions and should initially be set to false.)

Apex Request Example

// Create a scheduled subscription bundle
SubscriptionBundle bundle1 = new SubscriptionBundle();
bundle1.tagPath = '/Taxonomy Path/Node A';

// create an unscheduled subscription bundle
SubscriptionBundle bundle2 = new SubscriptionBundle();
bundle2.tagPath = '/Taxonomy Path/Node B';

SubscriptionAPIRequest request = new SubscriptionAPIRequest();
request.bundles = new List<SubscriptionBundle>{bundle1, bundle2};
 
Map<String, String> parameters = new Map<String, String>();
parameters.put('sname', 'site_name');
parameters.put('service', 'SubscriptionAPI');
parameters.put('action', 'setSubscriptions');
parameters.put('request', JSON.serialize(request));
parameters.put('apiVersion', '5.0');
 
String response = cms.ServiceEndpoint.doActionApex(parameters);
JSONMessage.APIResponse apiResponse = (JSONMessage.APIResponse) JSON.deserialize(response, JSONMessage.APIResponse.class);

if (!apiResponse.isSuccess) {
    throw new APIException('Could not retrieve information from the Subscription API');
}
if (apiResponse.type != 'List<SubscriptionBundle>') {
    throw new APIException('Unexpected result from Subscription API');
}
 
System.debug(response); // Outputs response with a list of created subscriptions

Javascript Request Example

var request = {
    bundles: [
        {
            tagPath: '/Taxonomy Path/Node A'
        },
        {
            tagPath: '/Taxonomy Path/Node B'
        }
    ]
};

var data = {
    service: 'SubscriptionAPI',
    action: 'setSubscriptions',
    request: JSON.stringify(request),
    apiVersion: '5.0'
};

// Handle response of a successful ajax call
var callBackHandler = function (json, Success) {
    console.log(json);
}
var options = {
    cb: callBackHandler,
    cbHandlerOnComplete: function(textStatus){},
    readonly: true
};
doServiceRequest(data, options);

JSON-Serialized Response Examples

Response messages and other fields may differ depending on the API method used and the parameters supplied.

ScheduleBundle Example

{
    "weeklyDays": [1, 5],
    "scheduleType": "Automatic Mail-out",
    "scheduleOptions": [
        {
            "contentTypeId": "a00000000000000000",
            "contentLayoutId": "a01000000000000000"
        }
    ],
    "scheduleName": "Twice Weekly Digest",
    "scheduleId": "a02000000000000000",
    "runAtTime": "08:00:00.000Z",
    "orgEmail": "a03000000000000000",
    "interval": "weekly",
    "everyNWeeks": 1,
    "emailPage": "a04000000000000000"
}

SubscriptionBundle Example

{
    "verified": true,
    "tagPath": "/Taxonomy Path/Node A",
    "suspended": true,
    "subscriptionId": "a00000000000000000",
    "subscriberType": "user",
    "subscriber": "a01000000000000000",
    "schedule":
    {
        "weeklyDays": [],
        "scheduleType": "Automatic Mail-out",
        "scheduleOptions": [],
        "scheduleName": "Immediate",
        "scheduleId": "a02000000000000000",
        "orgEmail": "a03000000000000000",
        "lastRun": "2017-06-26T00:00:00.000Z",
        "interval": "immediate",
        "emailPage": "a04000000000000000"
    }
}
Copyright © 2019 Stantive Technologies Group Inc.