Marketing Cloud for Appexchange API Guide

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

To begin to use these capabilities, your Marketing Cloud account must be fully configured for Marketing Cloud for AppExchange..NET 2.0 (C#) is used as the language for code samples.

The Marketing Cloud for AppExchange API enables email to be sent to Salesforce.com reports, campaigns, contacts, or leads from Marketing Cloud via a SOAP web service. Opportunities to leverage Marketing Cloud for AppExchange's robust email sending and tracking capabilities together with Salesforce data in your business processes allow your business to access and record previously unreachable customer touch points. The Marketing Cloud for AppExchange API web service supports many business scenarios. The architecture of the web service allows many requests for Marketing Cloud for AppExchange send 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 email based on Salesforce templates and sends an the email to Salesforce.com entities.

In order to access the Marketing Cloud for AppExchange web service, you must first contact your Marketing Cloud account manager 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.

WSDL File

Marketing Cloud maintains multiple web service addresses for use with the Marketing Cloud for AppExchange SOAP web service. Use the correct address for your Marketing Cloud instance, and contact your Marketing Cloud representative if you have any questions regarding which WSDL file to use. The Marketing Cloud for Appexchange WSDL service is located at, for each instance:

These files define the objects and calls exposed to SOAP clients to interact with Marketing Cloud.

Security

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

Development Platform Support For WS-Security 1.0*

This list is for information only and does not represent supported platforms.

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

.NET/C

This section presents a sample C# application to show the five required steps for sending a Marketing Cloud 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:

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

Using the Create call to Send an Email

This example uses a Create call to send a pre-existing Marketing Cloud email to recipients who reside on a Salesforce.com report:

1. Establish secure authentication with Marketing Cloud.

2. Specify a Marketing Cloud 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 Email to a Salesforce Report

PHP

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.

SOAP Sample

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