Marketing Cloud Engagement for Appexchange API Guide

This guide presents the details needed to use the capabilities of Marketing Cloud Engagement for AppExchange via a SOAP (Simple Object Access Protocol) web service in your business application.

To begin to use these capabilities, your account must be fully configured for Marketing Cloud Engagement for AppExchange.

The Marketing Cloud Engagement for AppExchange API enables email to be sent to reports, campaigns, contacts, or leads using a SOAP web service. The Marketing Cloud Engagement for AppExchange API web service supports many business scenarios. The architecture of the web service allows multiple send requests in a single call. Additionally, a send can consist of many Salesforce entities providing support for sophisticated business processes and marketing workflows.

Some scenarios that would benefit from this feature follow:

  • A custom landing page that sends an individual confirmation email to a Lead or Contact
  • A workflow that sends individual email based on data events
  • Sending mass email to one or many Campaigns or Reports on a recurring basis triggered from an external application
  • An application that creates a Marketing Cloud Engagement email based on Salesforce templates and sends an the email to entities.

In order to access the Marketing Cloud Engagement for AppExchange web service, you must first contact your Account Executive to configure your account and create a service user. A service user is a combination of user permissions and user settings. A user in your account is given permissions to access the web service and has the API User setting checked. Users who have the API User setting checked are not subject to the account's security settings.

Use the correct address for your Marketing Cloud Engagement instance, and contact your Account Executive if you have any questions regarding which WSDL file to use. The Marketing Cloud Engagement for Appexchange WSDL service is located at the URLs in this table.

S1 Instance
S4 Instance
S6 Instance
S7 Instance

These files define the objects and calls exposed to SOAP clients.

Authenticating to the Integration Framework requires passing a WS-Security 1.0 security token in the SOAP header.

Development Platform Support For WS-Security 1.0

JavaAxis2, XFire
PHPsoap-wsse.php, Axis2, Instantsvc

This list is for information only and doesn't represent supported platforms.

This section provides code samples and guidance for developing against the Marketing Cloud Engagement for AppExchange API.

This section presents a sample C# application to show the five required steps for sending a Marketing Cloud Engagement for AppExchange email. This example demonstrates the invocation and subsequent handling of API calls.

The result of all calls resulting in a outbound email are.

  • Emails contain personalization and dynamic content driven by Salesforce data mapped to Marketing Cloud Engagement attributes.
  • Email results are tracked in Marketing Cloud Engagement and Salesforce.

This example uses a Create call to send a an email to recipients who reside on a report.

  1. Establish secure authentication with Marketing Cloud Engagement.

  2. Specify a Marketing Cloud Engagement email using the email ID.

  3. Specify a target. Only one is specified by this call, but it contain many types of targets.

    • Salesforce ID is the ID of the Salesforce object.
    • Salesforce object type is the type of Salesforce object.
  4. Create a SalesforceSend object.

    • Sets Targets
    • Sets From Name (Optional)
    • Sets From Address (Optional)
    • Sets Targets to exclude from send (Optional)
  5. Send the SalesforceSend object into the web service Create call.

  6. Print result of the Create call to the console.

Listing 1: Sending a Marketing Cloud Engagement Email to a Salesforce Report

When sending a message to a Contact or Lead, set the IndividualResults property to true if you want individual email results to show in your Salesforce instance.

The sample code below demonstrates how to send to a single Lead in Salesforce: