CX Works

CX Works brings the most relevant leading practices to you.
It is a single portal of curated, field-tested and SAP-verified expertise for SAP Customer Experience solutions

Email Campaign Using the Email Service Provider of Your Choice

15 min read

Email Campaign using the Email Service Provider of Your Choice

SAP Marketing Cloud outbound integration enables you to send campaign emails and text messages using known service providers, such as SAP Digital Interconnect*, Amazon*, or Alibaba*. However, what if you would like to use other service providers? How can you achieve the integration with them to send campaign emails or text messages?

*For setting up emails and text messages via these known service providers, please refer to the SAP Help Portal for SAP Marketing Cloud.

In this article, we are going to provide you a practical example of how you can set up integration between SAP Marketing Cloud and email service provider of your choice to send campaign emails.

Table of contents


Use Case

We are going to demonstrate how you can set up integration between SAP Marketing Cloud and email service provider of your choice to send campaign emails. In this use case, we are going to use Infobip as the email service provider. This solution was randomly picked and does not suggest any preferences compared to other email service providers.

Integration Scenario

In the chart below you can see an overview workflow on how to integrate SAP Marketing Cloud with email service provider of your choice using SAP Integration Suite.

  1. Develop an integration flow in SAP cloud integration capability in SAP Integration Suite to verify the sender as this is required to complete the configuration of the sender profile.
  2. Create a communication arrangement with scenario ID SAP_COM_0234, Marketing - Campaign Execution - Generic E-Mail Integration.
  3. Complete the configuration of the sender profile, which is generated in step 2, Generic Email adapter - GNML.
  4. Create an email template and assign the sender profile created in step 3 to it.
  5. Perform segmentation to create a target group that will be the recipients of the email campaign.
  6. Release the target group so it can be used for email campaign.
  7. Create an email campaign with the target group created in step 6, and an email template created in step 4.
  8. Develop an integration flow in the cloud integration capability in SAP Integration Suite to send campaign emails to the email service provider.
  9. Email service provider send the campaign emails to customers and prospects and provide status back to cloud integration capability in SAP Integration Suite which in turn capture the email status back in SAP Marketing Cloud.

Email Service Provider

As mentioned in the use case, we are going to use Infobip as the email service provider. Thus, it is good to get some familiarity with its API before we use it to send campaign emails to our customers and prospects.

Once you have registered for a free account with Infobip, you will be given 14 days of trial with 30 free SMS and emails. You are also given a sender email address (with selfserviceib.com as email domain) which you can use to send emails using the platform. Infobip has quite a good email API documentation, it provides a payload sample as well as the code snippet in various programming languages.

Infobip Sample Request Payload

Just like any other email service provider, Infobip chooses to use Multipart Form format as the body of its email API. Thus, we need to use the groovy script step in the integration flow to transform the JSON content from SAP Marketing Cloud into Multipart Form content before calling the API. Please refer to the Multipart Form sample payload below for better understanding.

------=_Part_15_435184360.1594276383168
Content-Disposition: form-data; name="from"

xxx@selfserviceib.com
------=_Part_15_435184360.1594276383168
Content-Disposition: form-data; name="to"

xxx@yyy.com
------=_Part_15_435184360.1594276383168
Content-Disposition: form-data; name="subject"

Fashion
------=_Part_15_435184360.1594276383168
Content-Disposition: form-data; name="text"

------=_Part_15_435184360.1594276383168
Content-Disposition: form-data; name="html"

<!DOCTYPE html>
<html style="margin: 0;padding: 0;width: 100%;">

<head>
 ...
</head>

<body>
 ...
</body>

</html>
------=_Part_15_435184360.1594276383168--

Nevertheless, the API response is provided in JSON format, so it should be quite easy to parse the response back to SAP Marketing Cloud.

Infobip Sample Response Payload

If the request payload is received and stored successfully, Infobip will send the following response back to sender system.

{
    "messages": [
        {
            "to": "xxx@yyy.com",
            "messageCount": 1,
            "messageId": "uxyjk2hcdgi2jtce48y4",
            "status": {
                "groupId": 1,
                "groupName": "PENDING",
                "id": 7,
                "name": "PENDING_ENROUTE",
                "description": "Message sent to next instance"
            }
        }
    ]
}

If the request payload is somehow error out, Infobip will send the following response back to the sender system.

{
  "requestError": {
    "serviceException": {
      "additionalDescription": "string",
      "text": "string",
      "variables": "string",
      "messageId": "uxyjk2hcdgi2jtce48y4"
    }
  }
}


Integration Flow Development

As mentioned in the integration scenario, we need to create 2 integration flows in the Cloud Integration capability within SAP Integration Suite, those are:

  1. An integration flow to verify the sender email address, which will be called by SAP Marketing Cloud during sender profile configuration and email campaign execution.
  2. An integration flow to send campaign emails to an email service provider, which will be called by SAP Marketing Cloud during email campaign execution.

Verify Sender Integration Flow

We are going to use the integration flow to verify the sender email address whether it can be used for email campaigns. Ideally, there should be an API provided by the email service provider to perform this action. However, Infobip does not provide this capability at least for the trial version, thus we need to simulate the response from within the integration flow itself.


As you can see it is just a very simple workflow with content modifier step to return a list of verified sender email addresses and domains. You may want to refer to the response sample expected by SAP Marketing Cloud in the corresponding section of the SAP Help Portal for SAP Marketing Cloud.

As mentioned in the SAP help documentation, the HTTPS address of the integration flow must follow this naming pattern: /<name>/verifiedSenders. SAP proposes you to use sap_mkt_cloud as the name, but you may choose any name you like.

Send Email Integration Flow

The purpose of the integration flow is to transform the incoming JSON content from SAP Marketing Cloud into Multipart Form content and call the send email API from the email service provider. Upon getting the response from the email service provider, the integration flow sends the response status back to SAP Marketing Cloud for reporting purposes. Now let’s take a closer look at the integration flow. 

  1. HTTPS Call: Receive an email campaign message from SAP Marketing Cloud in JSON format.

    In this use case, we use User Role and uncheck CSRF Protected field for ease of testing purposes. In a real project, however, it is recommended to use Client Certificate and mark the CSRF Protected field instead.

    Also please note, the HTTPS address must follow this naming pattern: /<name>/send as mentioned in the SAP help documentation.

  2. JSON to XML Converter: Convert the incoming JSON content into XML format, so we can retrieve the email attributes using XPaths.

  3. Content Modifier: Get the email attributes and store them into message properties

  4. Groovy Script: Construct Multipart Form email message based on the email attributes retrieved in step 3.

    import com.sap.gateway.ip.core.customdev.util.Message
    import java.util.HashMap
    
    import javax.mail.internet.ContentType
    import javax.mail.internet.MimeBodyPart
    import javax.mail.internet.MimeMultipart
    import javax.mail.util.ByteArrayDataSource
    
    
    Message processData(Message message) {
    
        //get Properties 
        map = message.getProperties();
    
        //create multipart
        MimeMultipart multipart = new MimeMultipart()
    
        //set sender email address
        createBodyPart(map, multipart, "sender", "from")
    
        //set recipient email address
        createBodyPart(map, multipart, "recipient", "to")
        
        //set email subject
        createBodyPart(map, multipart, "subject", "subject")
    
        //set email text body
        createBodyPart(map, multipart, "text", "text")
        
        //set email html body
        createBodyPart(map, multipart, "html", "html")
     
        //set multipart into body of the message
        ByteArrayOutputStream outputStream = new ByteArrayOutputStream()
        multipart.writeTo(outputStream)
        message.setBody(outputStream)
        
        //set Content type with boundary
        String boundary = (new ContentType(multipart.contentType)).getParameter('boundary');
        message.setHeader('Content-Type', "multipart/form-data; boundary=${boundary}")
        
        return message
    }
    
    //set email part to multipart
    def createBodyPart(HashMap<String,Object> map, MimeMultipart multipart, String property, String name) {
    
        String value = map.get(property);
        MimeBodyPart part = new MimeBodyPart()
        part.setText(value, "utf-8")
        String formName = """form-data; name="${name}" """
        part.setDisposition("${formName}")
        multipart.addBodyPart(part)
    
    }
  5. Request-Reply: Call the API from the email service provider synchronously and wait for the response.

  6. HTTPS call: Call the API from the email service provider using HTTP protocol.

    Even though it is possible to use the SMTP protocol to send campaign emails asynchronously, but the HTTP protocol is preferred because we want to send the email service provider response back to SAP Marketing Cloud.

  7. JSON to XML Converter: Convert the JSON response into XML format, so we can retrieve the email message ID and its status using XPaths.

  8. Content Modifier: Get the email attributes and store them into message properties
  9. Groovy Script: Construct JSON response message to SAP Marketing Cloud based on the email status retrieved in step 8.

    import com.sap.gateway.ip.core.customdev.util.Message;
    import java.util.HashMap;
        
    def processData(Message message) {
        
        //set messsage Id 
        map = message.getProperties()
        def messageId = map.get("messageId")
        def errorCategory = map.get("errorCategory")
        def errorText = map.get("errorText")
        
        def body = ""
        //success
        if (errorText == '') {
            //set response header
            message.setHeader("CamelHttpResponseCode", 202)
            message.setHeader("CamelHttpResponseText", 'Accepted')
            
            //set body
            body = """{"messageId" : "${messageId}" }"""
        } 
    
        //error 
        else {
            //set response header
            message.setHeader("CamelHttpResponseCode", 500)
            message.setHeader("CamelHttpResponseText", 'Error')
            
            //set body
            body = """{"errorCategory" : "${errorCategory}", "errorText": "${errorText}" }"""
    
        }
        message.setBody(body)
        
        return message
    }

    You may find it useful to refer to the JSON response message which is required by SAP Marketing Cloud in this SAP help documentation.

SAP Marketing Cloud Configuration

Create a Communication System

We need to create a communication system to represent the cloud integration capability in SAP Integration Suite using the Communication Systems application. You may name the system ID as you like, in this case, we name it as ‘CPI_GENERIC_EMAIL_PROVIDER’.

  1. Under the Technical Data section, enter the cloud integration capability in SAP Integration Suite instance hostname and port you want to use for the campaign execution.


  2. Under User for Outbound Communication tab, maintain user ID and password to access SAP cloud integration capability in SAP Integration Suite.

    In this example, we have used basic authentication (user name and password) to access the cloud integration capability in SAP Integration Suite instance in order to ease the testing process. However, in a real project, you should use an SSL client certificate instead.

Create a Communication Arrangement

We need to create a communication arrangement to enable communication between SAP Marketing Cloud and SAP cloud integration capability in SAP Integration Suite via the Communication Arrangement application. You must use the predefined scenario ID SAP_COM_0234, Marketing - Campaign Execution - Generic E-Mail Integration.

  1. Under the Common Data section, select the communication system which you have created in the previous step, all the required fields under the Outbound Communication section will be filled automatically.
  2. Under the Outbound Services section, enter the path with this naming pattern: /http/<name>. 

    Please ensure the path naming pattern is in sync with the HTTPS addresses which you have chosen for your integration flows.

Configure a Sender Profile

Once you save the communication arrangement, a new entry Generic Email adapter - GNML is created in the Sender Profiles application.

  1. Edit the sender profile and add other information as per your requirement.

If the Verify Sender integration flow is not created and deployed, the sender profile will be in Incomplete status.

Create Email Template

Now you need to create an email template that is going to be used in the email campaign using Content Studio application.

  1. Copy from the existing templates or create a new email template.

  2. Ensure the sender profile created in the previous step is chosen.

  3. Once this is done, press on the Check button, and Release it so it can be used for email campaigns.

Perform Segmentation and Create Target Group

As part of a marketing campaign, we need to assign a target group which can be created using Segmentation Models application

  1. Perform segmentation to create a relevant target group for the email campaign.
  2. Save and release the target group.

Create Email Campaign

You may create a marketing campaign from a Target Group or Campaigns application. 

  1. Choose the target group you have created in the previous step in the email campaign screen.

  2. Select Send Email step in the campaign flow and choose the email template you have created in the previous step.

  3. Start the campaign.

If your integration flows are not triggered after you start the campaign, please ensure you have allowlisted the recipient email addresses in Campaign Execution Allowlist application.


Email Campaign Performance

When we start the email campaign, SAP Marketing Cloud retrieves all the contacts from the target group and merge them with the email template in the background. Based on the sender profile configuration attached to the email template, it will call the integration flow below:

  1. the Verify Sender integration flow to verify the sender email address.
  2. Once it is verified successfully, it will call the Send integration flow to send the campaign message to the email service provider. 

Before long, if all the steps mentioned are configured and developed correctly, your customers and prospects will receive the campaign emails, like the one below.

  1. Campaign email which is sent to your customers and prospects.

  2. In the performance tab of your campaign, you can find the statistics which shows number of emails sent and opened.

There you go, the generic email adapter in SAP Marketing Cloud works just like charm!

Conclusion

Even though SAP Marketing Cloud outbound integration enables you to send campaign emails and text messages via known service providers, such as SAP Digital Interconnect, Amazon, or Alibaba. In this article, we have demonstrated how you can also integrate SAP Marketing Cloud with email service provider of your choice using the cloud Integration capability in SAP Integration Suiteas a middleware. Depending on the capability of email service provider, you may also implement bounce scenario to remove those bounced email addresses from your future campaign. In this case, the HTTPS address of the integration flow must follow this naming pattern: /<name>/bounces as mentioned in the SAP help documentation.

There are configuration and development works which are required to realize this integration, those are: 

  1. Develop two integration flows in SAP Integration Suite to verify sender email address and to send campaign message to the email service provider of your choice.
  2. Configure communication arrangement and sender profile; create email template, segmentation and target group; and execute email campaign in SAP Marketing Cloud.

Do you want to learn even more about the integration aspect of SAP Marketing Cloud?  While we are going to release more articles which are related to this subject in the future, please also look into the already published articles below:


Overlay