REST API for Oracle Responsys Marketing Cloud Service

Changes and Enhancements in Recent Releases

This section summarizes Responsys REST API changes and enhancements in recent releases. In addition, readiness material is published on the cloud.oracle.com site, providing a preview of new and changed functionality available in our latest updates.

Changes and Enhancements in 22B

There are no significant updates to the Standard REST API.

Enhancements to other APIs in 22B:

Changes and Enhancements in 22A

The Responsys Advanced API (34 APIs) and the Responsys Asynchronous Reporting API (4 APIs) are now Generally Available to all customers. We have no updates to the Standard REST API.

Changes and Enhancements in 21D

Updates to API Infrastructure: Post 21D, we've updated the Responsys APIs to have a built-in Smart API Controller that manages your Internal Capacity Limits. This change will not impact any of your existing API limits for any accounts. The API Controller smartly manages your API health for all accounts and acts for any performance issues or API anomalies. See Internal Capacity Limits to learn more.

Changes and Enhancements in 21C

There are no significant updates to the Standard REST API, see what's new in the Asynchronous REST API.

Changes and Enhancements in 21B

There are no significant updates to the Standard REST API, however the Asynchronous REST API endpoints are now Generally Available in this release.

Changes and Enhancements in 21A

New and updated standard REST API endpoints: Oracle Responsys has updated and added new APIs for the following tasks. See the sections in this guide for usage details.

Preview a campaign: This new endpoint enables you to preview a campaign in HTML and text. See Preview a campaign for details.
Retrieve segment groups: This new endpoint enables you to retrieve all segment groups for an account. See Retrieve segment groups for details.
Get all data sources associated with a campaign: You can now get a list of all data sources associated with a campaign. See Get all data sources associated with a campaign for more details.
Update a supplemental table: You can now update a supplemental table's properties. See Update a supplemental table for more details.
Trigger Email Message with Attachments: You can now send Responsys Email Campaigns with attachments to existing members of a profile list. See Trigger Email Message with Attachments for more details.

Enhancements to other APIs in 21A:

Changes and Enhancements in 20D

New and updated standard REST API endpoints: Oracle Responsys has updated and added new APIs for the following tasks. See the sections in this guide for usage details.

Get a Campaign's Proof List: This new endpoint enables you to retrieve the proof list associated with a campaign. See Get a Campaign's Proof List for details.
Update a Campaign's Proof List: This new endpoint enables you to update a campaign's proof list. See Update a Campaign's Proof List for details.
Hashed Email Support: You can now use MD5 and SHA256 hashed emails when triggering email and SMS messages. See Triggering Email Messages and Triggering SMS Messages for details.

Changes and Enhancements in 20C

New and updated standard REST API endpoints: Oracle Responsys has updated and added new APIs for the following tasks. See the sections in this guide for usage details.

Add Email Domain Rules: This new endpoint allows you to add web domains to include or ignore in a campaign to an existing set of email domain rules. See Add Email Domain Rules for details.
Delete Email Domain Rules: There is also a new endpoint that lets you delete web domains from a set of email domain rules. See Delete Email Domain Rules for details.
Fetch a Program by Name: This new endpoint allows you to retrieve details of an individual program by its name. Some of the details included are the program's current run status and a list of the program channels. See Fetch a Program by Name for details.
Fetch Programs for a Profile List: There is also a new endpoint that will retrieve a list of programs associated with a profile list. This returns the same properties as the Fetch All Programs endpoint. See Fetch Programs for a Profile List for details.
Create a Folder: This new endpoint allows you to create a new folder. See Create a Folder for details.
Retrieve Proof Lists: This new endpoint allows you to retrieve all proof lists associated with an account. See Retrieve Proof Lists for details.
Fetch Campaigns Using Filters: This new endpoint allows you to search campaigns based on a keyword and up to 2 filter critera. This returns up to 20 results, sorted by criteria you provide. See Fetch Campaigns Using Filters for details.
Trigger REI Event: This endpoint has been updated to allow you to trigger an REI event for Web Push recipients. See Trigger REI Event for details.

Changes and Enhancements in 20B

New and updated standard REST API endpoints: Oracle Responsys has updated and added new APIs for the following tasks. See the sections in this guide for usage details.

Exit Enactments: We've added a new API endpoint that enables you to exit enactments from a Program. This new endpoint provides the ability to move blocked program enactments out of programs. Programs must have been published at least once, but be in an unpublished state to exit enactments. See Exit Enactments for details.
Retrieve Profile List Fields: The new Profile List Fields endpoint enables retrieving all fields within a profile list, including standard fields and custom fields. See Retrieve Profile List Fields for details.
Retrieve Profile List Recipients Count with query attribute: We've added a new endpoint that enables you to retrieve the count of profile list recipients within a profile list, using query attributes to filter. See Retrieve Profile List Recipient Count using query attribute for details.
Delete Profile List Recipients using query attribute: This new endpoint enables you to delete Profile List Recipients using query attributes to filter recipients to delete. See Delete Profile List Recipients using query attribute for details.
Get all Filters: You can now retrieve all Filters in your Responsys account using this API endpoint. See Retrieve All Filters for details.
Get Email Domain Rules: We've added a new API endpoint that enables you to retrieve your account's Email Domain Rules. See Get Email Domain Rules for details.
Get Email Footer Contents: This new API endpoint enables you to retrieve your account's Email Footer contents in text and HTML. See Get Email Footer contents for details.
New campaign status property: A new property, campaignStatus, has been added to the campaigns object to the Fetch All Campaigns endpoint. The campaignStatus property signifies the status of a campaign. Values include: "NONE", "DRAFT", "ACTIVE", or "CLOSED". See Fetch All Campaigns for details.

Documentation enhancements of note:

The Retrieve Multiple Profile Extension Recipients API endpoint has been added in this documentation update. This endpoint was released in 20A.
The Create Profile List API endpoint was moved to the Advanced API guide. This endpoint was released in 20A.

Changes and Enhancements in 20A

New and updated standard REST API endpoints: Oracle Responsys has updated and added new APIs for the following tasks. See the sections in this guide for usage details.

Create a Profile List: We've added a new API endpoint to enable creating Profile Lists. See Create Profile Lists for details.
Trigger SMS Message: We've added a new API endpoint that enables you to trigger SMS messages. See Trigger SMS Message for details.
Get Account Settings for a User: We've added a new API endpoint that enables you to get account settings for the user sending the request. See Get Account Settings for a User for details.
Get User Information: We've added a new API endpoint that enables you to retrieve information for the user sending the API request. See Get User Information for details.
Get Endpoint URL for a User: We've added a new API endpoint that enables you to retrieve Endpoint URLs for the account. See Get Endpoint URL for details.
Retrieve Profile Extension Recipient using a query attribute: We've updated this endpoint to enable you to query Profile Extension Table records using a modified date range. The sdate and edate query parameters enable you to query based on a date range. See Retrieve Profile Extension Recipient using a query attribute for details.
Trigger REI Event: We've enhanced this endpoint to enable you to trigger REI events for mobile app channel users. See Trigger REI Event for details.
Retrieve Multiple Profile Extension Recipients: This new endpoint retrieves multiple profile extension recipients in an existing profile extension table. By supplying an ID for a recipient (for example email address) you can retrieve up to 200 recipients in a single request. See Retrieve Multiple Profile Extension Recipients for details.

Changes and Enhancements in 19D

New and updated standard REST API endpoints: Oracle Responsys has updated and added new APIs for the following tasks. See the sections in this guide for usage details.

Retrieve Folder Content: This new API endpoint enables you retrieve all objects in a specified folder. See Retrieve Folder Content for more information.
Retrieve Account Folders: This new API endpoint enables you to retrieve all folders within your account. See Retrieve Account Folders for more information.
Trigger Custom Event: We've updated this endpoint to enable you to specify two new recipientData parameters: emailMD5Hash and emailSHA256Hash. This enhancement enables you to specify a hashed email address using the MD5 and SHA-256 algorithms as unique identifiers for a recipient. See Trigger Custom Event for details.
Trigger REI Event: We've added a new API endpoint that enables you to trigger Responsys Event Interface (REI) events. See Trigger REI Event for details.
Retrieve List Recipient using query attribute: We've added two new query attributes to the qa query parameter: e_md5 (EMAIL_MD5_HASH_) and e_sha256 (EMAIL_SHA256_HASH_). This enhancement enables you to query a Profile List recipient using hashed email addresses. See Retrieve List Recipient using query attribute for details.

IMPORTANT NOTICE: Oracle Responsys has deprecated Transport Layer Security (TLS) 1.0 and 1.1. Ensure that your client systems use TLS version 1.2.

Changes and Enhancements in 19C

New standard REST API endpoints: Oracle Responsys has added new APIs for the following tasks. See the sections in this guide for usage details.

Publish or Unpublish a Program: This new API endpoint enables you to publish or unpublish a program. See Publish or Unpublish a Program for more information.
Create new Profile Extension Table v1.4: This new API endpoint enables you to set the number of days a profile extension table will exist before expiring. See Create a new profile extension table for details.

IMPORTANT NOTICE: Oracle Responsys's TLS 1.0 and 1.1 deprecation has been postponed to August 5th, 2019 for I2 accounts and August 6th, 2019 for I5 accounts. Oracle is updating Responsys application security mechanisms to meet modern security requirements. On the specified dates, Responsys will no longer allow inbound connections using TLS 1.0 and TLS 1.1 protocols. Responsys will continue to support inbound connections using the TLS 1.2 protocol.

Because Responsys already supports modern browsers that support TLS 1.2, there should be no impact on Responsys users. However, any Internet connections made to Responsys from browsers or external applications using TLS 1.0 or TLS 1.1 will fail. For example, if a consumer uses an older browser not supporting TLS 1.2 to open a Responsys-generated email message, that message may not get rendered properly. Please note that Responsys will not generate any error or warning messages in response to an incoming request using TLS 1.0 or TLS 1.1 protocols.

For APIs and App access, verify that all applications accessing Responsys, including custom apps, support TLS 1.2. If your application does not support TLS 1.2, it will not be allowed to establish a connection to Responsys. In the event that your application does not use TLS 1.2, it will need to be updated to allow connections via a supported protocol.

See the Responsys Bulletin for more information.

Changes and Enhancements in 19B

New and updated standard REST API endpoints: Oracle Responsys has updated and added new APIs for the following tasks. See the sections in this guide for usage details.

Organizations REST API endpoints: New API endpoints that enable you update and retrieve organizational access for campaigns and programs. For more details, see the Organizations topic.
Fetch all programs: A new query parameter, status was added. This new query parameter enables you to filter programs by program status. For example, /rest/api/v1.3/programs?status=RUNNING. For more details, see the Fetch all Programs topic.
Fetch a campaign: A new Campaign API endpoint was added. Use the Fetch a Campaign API endpoint to get an existing EMD Email campaign object. For more details, see the Fetch A Campaign topic.

IMPORTANT NOTICE: Oracle is updating Responsys application security mechanisms to meet modern security requirements. On August 5th, 2019, Responsys will no longer allow inbound connections using TLS 1.0 and TLS 1.1 protocols. Responsys will continue to support inbound connections using the TLS 1.2 protocol.

Changes and Enhancements in 19A

New and updated standard REST API endpoints: Oracle Responsys has updated and added new APIs for the following tasks. See the sections in this guide for usage details.

Get all campaigns: You can now get all campaigns and their details for MMS and Message Center campaigns. For more details, see the Fetch all Campaigns topic.
Get all programs: Using the new Fetch all Program API, you can fetch meta-data of your account's Responsys program orchestrations. To learn more, go to the All REST Endpoints topic, locate the Programs section, and then click the link for Fetch all Programs.

Changes and Enhancements in 18D

REST API Version 1 was deprecated September 2018

IMPORTANT NOTICE: Oracle has deprecated version 1 of the Oracle Responsys REST API. If you are using version 1 right now, it will still function. However, version 1 may be turned off completely at any time. To avoid disruption to your API service, you must upgrade your client applications to use version 1.1 or later (preferably 1.3, which is the latest version). More details about migration are available in the Oracle Responsys REST API Upgrade Guide. (To access the document, you must be a member of our customer and partner group, "Responsys Insiders". If you are not a customer or partner but are working on a client application that uses the Oracle Responsys REST API, your Responsys contact can provide the document.)

New standard REST API endpoints: Oracle Responsys has added new APIs for the following tasks. See the sections in this guide for usage details and examples.

Retrieve primary keys or all fields for a single supplemental table: For an existing supplemental table, you can now get the primary key field names or all of the field names.
Retrieve multiple profile list records: You can now retrieve multiple profile list records by using a single batch request.
Delete multiple profile list records: You can now delete multiple profile list records by using a single batch request.
Delete multiple PET records: You can now delete multiple Profile Extension Table (PET) records by using a single batch request.

Document enhancements of note:

We have clarified information about how login IP enforcement control affects API user authentication. See "Login IP Enforcement Access Control".
You can perform Email campaign proof launches using the existing APIs for campaign scheduling and Trigger Email Message. Please refer to the Create an Email or Push campaign schedule and Trigger Email Message topics for additional details.

Changes and Enhancements in 18C

There were no changes to the Responsys REST API in this release.

Support for real-time custom events: Real-time custom events are a special type of custom event that override how Responsys handles enactments when the Enactment Batching feature is enabled. If your account has Enactment Batching enabled and you need to send near-real-time messages, then we highly recommend having your account enabled for the Real-time Events feature. This feature is intended for Responsys customers who use the Mobile App channel. Part of this feature enables you to create real-time custom events. When a real-time custom event is triggered, Responsys handles the enactments in near real-time instead of batching them. This ensures that your customers receive the campaign messages (including Email, SMS, Push, and In-app) without the delay imposed by enactment batching. To have this feature enabled for your account, contact your Oracle Customer Success Manager. For more information, see the Defining Custom Event Types topic in the Oracle Responsys Help Center.

Documentation corrections and enhancements: The request payload example shown for Trigger Push Message incorrectly omitted the deviceID and apiKey properties when listType is PROFILE. The properties must be present for each recipient, but the value may be null. The topic has also been enhanced with additional information regarding the request and response payloads.

Changes and Enhancements in 18B

REMINDER - REST API Version 1 will be deprecated September 2018

IMPORTANT NOTICE: Oracle has announced the deprecation of the version 1 of the Oracle Responsys REST API. To avoid problems with your client applications, you must upgrade your client applications to use version 1.1 or later (preferably 1.3, which is the latest version). More details are available in the Oracle Responsys REST API Upgrade Guide. (To access the document, you must be a member of our customer and partner group, "Responsys Insiders". If you are not a customer or partner but are working on a client application that uses the Oracle Responsys REST API, your Responsys contact can provide the document.)

Updated throttling limits

Oracle Responsys has implemented throttling limit changes on its APIs. These changes included imposing throttling limits on APIs that did not have limits before. Throttling limits now apply for following APIs:

retrieveListMembers
login
All Content Library APIs

To obtain the current list of throttling limits for your account, use the Get Throttling Limits API.

New standard REST API endpoints

The REST API now includes the following new and updated APIs:

Get All Campaigns now supports SMS campaigns. Use the type=sms parameter to get all SMS campaigns in an Oracle Responsys account.
Get All Custom Events is a new API that enables you to get all of the custom event names for your account. This helps you obtain the names for other API requests that require a custom event name.
If your Oracle Responsys account has Targeting by Organization enabled, you can use the new API, Add or Update RIID-to-Audience Scope Code Mapping Data, to update the RIID-to-organizational scope mapping for recipients in your Profile List. Previously, you could only update this mapping table by using a Connect job.