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 Salesforce.com 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 Salesforce.com Lead or Contact
  • A Salesforce.com workflow that sends individual email based on Salesforce.com data events
  • Sending mass email to one or many Salesforce.com 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 Salesforce.com 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 Instancehttps://etappx.exacttarget.com/etframeworksf.wsdl
S4 Instancehttps://etappx.s4.exacttarget.com/etframeworksf.wsdl
S6 Instancehttps://etappx.s6.exacttarget.com/etframeworksf.wsdl
S7 Instancehttps://etappx.s7.exacttarget.com/etframeworksf.wsdl

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

PlatformLibrary/Module
C++Axis2/C
JavaAxis2, XFire
.NETWSE 3.0
PerlWSRF::Lite
PHPsoap-wsse.php, Axis2, Instantsvc
PythonpyGridWare
Rubywss4r

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 Salesforce.com 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

The sample code below demonstrates how to connect your PHP development environment to the WSDL file.

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 create a Salesforce send through the API.

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