API and Watson Campaign Automation folder limits

Folder limits and the standard user in the Watson Campaign Automation.

A Standard User who has Folder Limits in the Watson Campaign Automation can access and manipulate any data in the Org via API from an allowed IP address.

An entire contact source action can be restricted from the API, regardless of IP restrictions. For more information, click here.

Note: These settings override user permissions for standard users. The settings do not affect organization administrators.

API call to pull tracking metrics from archived mailings

Pulling tracking metrics from archived mailings by using API.

API calls cannot be used to pull detailed tracking metrics from archived mailings. Archived mailings have little information that is attached to them and the information that is presented in the archived mailing is the only information that is stored.

Are API call tags case-sensitive?

Case-sensitive API tags

IBM® API is based on XML tags and they ARE case-sensitive.

If you change the tag <Body> to <body>, you get the response that your request is invalid: <Envelope> <Body> <RESULT> <SUCCESS>false</SUCCESS> </RESULT> <Fault> <Request/> <FaultCode/> <FaultString>Invalid XML Request</FaultString> <detail> <error> <errorid>51</errorid> <module/> <class>SP.API</class> <method/> </error> </detail> </Fault> </Body> </Envelope>

Create a .CSV file for aggregate tracking for org API call

How to create .csv for aggregate tracking or an organization.

The API test harness does not provide a csv file for export for the Get Aggregate Tracking Metrics for an Org call. However, you can get all of the information by looking at the view frame source after successful submission of the call. In the source view, you can copy and paste all the information into Excel.

Delete a contact list by using API

Can a contact list be deleted by using API?

It is not possible to delete a contact list by using API. Data can be purged from a contact list by using API, but deleting the actual database can be achieved through the Watson Campaign Automation user interface.

Note: Purging data means that you leave the structure but delete information that is contained within said structure. Deletion means that everything about the data is removed right down to the structure as if the data never existed.

Using the ScheduleMailing API on a contact source that is being updated

Using the ScheduleMailing API call on a contact source.

An ImportList API call is submitted that adds new contacts to a database as well as updates some existing contacts. After submission of the ImportList call, the ScheduleMailing API call is submitted but the <SCHEDULED/> element is omitted to make the mailing send as soon as possible.

Since the ImportList API datajob is not completed, does the ScheduleMailing API call send a mailing to an incomplete / non-updated contact source?

The Watson Campaign Automation places a lock on any contact source that is going through a calculate/update. This security measure allows the mailing send created by the ScheduleMailing API call to commence after the datajob that is created by the ImportList API call is complete.

As an extra safe guard, you can update your process to include a GetJobStatus API call. You could then execute a SendMailing API call only after it returns a value of COMPLETE for your ImportList API call but never before.

Optimove – Watson Campaign Automation API integration

Optimove integrated solution.

The integrated solution of Watson Campaign Automation and Optimove helps increase customer engagement and spend by using predictive customer modeling to personalize retention campaigns.

Marketers use Optimove to plan their customer marketing campaigns based on advanced customer segmentation available in the product. Using Optimove’s customer modeling system, marketers are able to easily define and discover interesting groups of customers to target – groups that the company’s marketers wouldn’t have been able to identify and otherwise target.

Every night, the Optimove software generates the specific lists of customer IDs to receive each pre-planned marketing campaign – along with the IBM email template ID and scheduled send time. Optimove pushes the lists to IBM via API and IBM Engage sends out each personalized campaign at the specified time.

During and after the campaign’s execution, Optimove reports on the financial success metrics of each campaign (compared to a pre-selected control group) or the winner of an A/B campaign test, and incorporates email delivery, open and click metrics acquired via IBM’s API.

To summarize, the Optimove software connects to IBM via API for two purposes:

  1. To instruct IBM to send out a particular email template to a specified list of customer IDs.
  2. To receive from IBM email campaign metrics (delivery rate, open rate and click rate).

How it Works

1. Prepare Customer Database in IBM Engage

Once the marketer has opened the IBM account, his first step is to export the required customer data into IBM Engage. At a minimum, this data will include customer ID, first name, last name and email address. It is important that the freshness of his data be maintained on a daily basis, e.g., when new customers join, their information must be promptly updated in IBM.

2. Prepare Customer Data for import into Optimove

The marketer, usually with assistance from internal IT staff, prepares the company’s raw data into specific formats required by Optimove. These customer profile tables, which describe each customer’s attributes, will be imported daily by Optimove. Optimove uses this data to segment customers into a variety of dimensions (lifecycle stages, micro-segments, etc.) and to track the behavior of customers and target groups over time.

3. Connecting Optimove to the IBM API

In order for Optimove to connect to the IBM API, it needs to receive login credentials to the client’s API instance as well as the ID of a particular customer database in IBM. All communication between the Optimove and IBM servers is via XML over HTTP.

4. Using the Joint Optimove-IBM Solution to Create and Send Customer Campaigns

Retrieving the List of Email Templates

When the marketer sets up an email campaign in Optimove to be sent via IBM, the software retrieves a list of all available email templates via the IBM API. The user can choose the desired template for the campaign from a drop-down list and can also view a preview of the email itself from within Optimove.

Sending an Email Campaign

Each time Optimove actually sends an email campaign via IBM, Optimove connects to the IBM API and performs the following steps:

  1. Optimove creates a IBM “query” inside the Optimove folder of the IBM query library. This query contains the list of customer IDs to receive the email. This customer list is generated by Optimove according to the target group segmentation defined within Optimove.
  2. Optimove instructs IBM to send the email by providing the following parameters: the ID of the previously-created query, the ID of the email template to use (this is selected by the user, in Optimove’s Run Campaign wizard, from among all the email campaign templates created by the user inside IBM) and the date and time of day when IBM should deliver the email (this is also specified by the user in the Run Campaign wizard).

Note: Optimove does not store actual customer addresses in its database. Rather, the customer IDs used by the client to identify each customer are used by both Optimove and IBM.

Retrieving Email Campaign Metrics

Once each day, for a period of one week following the sending of each IBM mailing, Optimove connects to the API in order to retrieve delivery rate, open rate and click rate metrics for the campaign. These metrics are displayed within Optimove’s Campaign Analysis page for each executed campaign.

Passing HTML code through the API call

How to pass the full HTML code in an API call.

Can you advise on how to pass the full HTML code in the API call?

Look into following solutions that are listed in the API content:

  1. SaveMailing – Update a template (when the template is not an automated message ready to be triggered) and in this call you can send the entire HTML.
  2. ScheduleMailing – Schedule a template to be sent and allows for substitutions to be used. For example, %%HTML_BLOCK_1%% can be in the template and be replaced by code that is submitted as part of the XML.
  3. SendMailing – Could possibly be used, but would have to use personalization from either a database or Relational Table. These updates would already have to be made to code saved in those columns.
    Note: The character limit for storing HTML code in these columns is 3600.

You might also want to discuss alternative solutions with Client Support.

Does Watson Campaign Automation support CORS?

Support of CORS within Watson Campaign Automation.

Watson Campaign Automation does not support CORS.

When creating web pages on a site that interacts with Watson Campaign Automation through the API, requests must be made server-side. For example, a visitor to a web page might complete a form, click submit and send the data to PHP. PHP runs a check that 1) the data is complete and then 2) sends an API call to Watson Campaign Automation with the data.

Attempting to send the API call client-side, using JavaScript through the user’s browser, will likely fail due to the CORS standard. This is because the request to the Watson Campaign Automation API server travels from the site’s domain to the API server. For security reasons Watson Campaign Automation does not open the API server to work with CORS.

Note: CORS restriction is in place for XML APIs and REST APIs.

API JSessionID expires in minutes

Why the JSessionID expires so quickly.


Normally an API JSessionID will be valid until after 15 minutes of inactivity. But sometimes an API user can experience that the JSessionID expires in just a few minutes, which are much sooner than expected. The user has to run a Login API more frequently than usual to obtain new JSessionID.

Error Example

        <![CDATA[Session has expired or is invalid]]>


There is no guarantee on the life of a JSession. Sometimes, the JSession is sticky to one specific application server. Because the calls are not authenticated on that application server, when the subsequent calls are made by the user, the calls could go to a different application server and cause the error.


The recommendation is to use an OAuth session to permanently avoid this issue. Each OAuth access token can provide a much longer access time to the system for up to 4 hours.

Is there a limit to the number of API calls that can be submitted simultaneously?

Limitations on simultaneous API calls.

There is a limit on the number of API calls that can be made in Salesforce. This affects clients who are syncing Salesforce contacts into the Watson Campaign Automation.

If you use Salesforce and want to increase your API limit, then you must provide the following information to Support.

  • One or more tools used that need the API increase.
  • Specific duration as to how long the limit increase is to be in effect.
  • Duration for the API call increase (how long is needed for the limit increase)?
  • How many API calls are being requested for the temporary increase?
  • How many records, and what objects are loaded?
  • What specific API Calls are going to be made and how many?
  • What edition of Salesforce.com is being used?
  • Provide the Org ID (to view, go to: Set up > Company Profile > Company information)

Once this information is obtained, the Client Support Team sends the information to the CRMi Team.

Supported Date Format

Date for formats for API

IBM supports its customers globally by adapting Watson Campaign Automation to support local languages beyond English. These updates also apply to the Date, Time, and Timestamp formatting displayed in Watson Campaign Automation . As we add and support extra language and locales in Watson Campaign Automation, the XML APIs remain unchanged for now. Date formats for the XML API operations have not been updated to reflect the changes that are made in the Watson Campaign Automation platform.


For US customers, Date is displayed as MM d, y. Eventually, for customers in France, if their Organization setting is configured to their local settings, Date format in their Watson Campaign Automation platform is displayed as MM y, d.

Frequently asked questions - Restricted databases

Get answers to frequently asked questions in regards to Restricted databases.

Question Answer
Does OptOutRecipient opt out all contacts with the email address or just the contact who matches the unique key? You can use the OptOutRecipient API on a Restricted database by including all unique key columns with their corresponding name-value pairs or by specifying the email address. If you do specify a unique key, Watson Campaign Automation only opts out the contact who matches the unique key, not other contacts with the same email address. If you specify the email address, the system opts out all contacts with the specified email address.
Can you change the unique key in an existing database? No, once you define the database, you can only add unique keys.
Must you use the email address along with the unique key when calling SelectRecipientData? No, you can leave out the email address and provide the unique key.
If you have multiple unique keys and call AddRecipient, must you provide the email address and all unique keys? Yes. You must provide all unique keys and the email address when calling the AddRecipient operation.
Should the master Suppression list have the same key as a database? No, your master Suppression list must have Email as its key. Add to Master Suppression List uses email address for opting out (without a unique key, other than the email specified in the master Suppression list.).
Does the RemoveRecipient operation require that you specify all unique keys and the email address to remove a contact? Yes. If you have more than one instance of the same email address in the database, specifying all unique keys prevents removal of records with the same email address.

4 comments on"FAQs"

  1. Hello Team,

    Could you please help us how to send the share to social links (links for Facebook, Twitter etc) to Save Mailing API as HTML anchor links.
    Does it needs to be like a click through link, Does it have any click through type

    • Hello Somu,
      I’m confused by the Save Mailing API call you mention. Can you clarify?

      Thank you,
      Jeri Ellis

  2. I am trying to send automate mail from XMLAPI using SendMailing. I have given mailingid but having error like
    “Only sending Custom Automated Mailings are allowed. Please provide the Mailing ID for a Custom Automated Mailing.”
    how i get custom automate mail id from API

    • Hello Suvarna,
      You would have to created the custom automated mailing within the Watson Campaign Automation organization.

      Thank you

Join The Discussion

Your email address will not be published. Required fields are marked *