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

SAP Marketing Cloud – Verifying E-Mail Addresses with NeverBounce (Part 2/3)

12 min read


SAP Marketing Cloud – Verifying E-Mail Addresses with NeverBounce Part 2/3

For the majority of implementation projects on SAP Marketing Cloud, outbound e-mail communication is one essential part of the project's scope. On SAP Marketing Cloud, we can aggregate and maintain data from multiple sources. However, who guarantees the validity of e-mail addresses collected from these sources?

To increase data quality, with respect to your e-mail addresses, we work with NeverBounce, a service provider for real time e-mail verification and e-mail cleaning services.

This article gives you an idea on how to validate your e-mail addresses on SAP Marketing Cloud using the NeverBounce services.

See how the SAP Integration Suite can leverage integration scenarios between SAP Marketing Cloud and non-SAP services. Learn how to build an end to end integration scenario with SAP Marketing Cloud and SAP Integration Suite.

We will create a new integration flow (iFlow) on Cloud Integration capability within SAP Integration Suite and configure the iFlow to communicate with SAP Marketing Cloud and NeverBounce to verify e-mail addresses.

Table of Contents

Configure the iFlow on SAP Integration Suite


1. Receive Message from SAP Marketing Cloud

Configure the HTTP Sender with the same address and authentication setting, defined in the Outbound Communication Arrangement in SAP Marketing Cloud.
When releasing a campaign, SAP Marketing Cloud first sends the HTTP HEAD to the service URL before sending the actual message. In our scenario, we respond with a success message in order for the campaign to be released.


This can be solved on the Cloud Integration with a simple routing condition. In the router, integration patterns use Camel Simple Expression to access the header value for CamelHttpMethod and define the condition to end the process successfully for the call from SAP Marketing Cloud. When this is successful, SAP Marketing Cloud will send out the campaign data.

2. Extract E-Mail Addresses

NeverBounce expects the list of e-mail addresses in a specified format.

  • Public URL to the CSV file
  • URL encoded string

Here, we use list verification with URL encoded string.


The received message is converted to XML and transformed to an URL encoded string, using XSLT mapping on Cloud Integration. Using XSLT is only one approach on how a specific value can be extracted from an inbound message.


Comparing the Cloud Integration Inbound and Outbound Message (sample entry from NeverBounce):

From the Cloud Integration Inbound Message (Marketing Cloud Outbound), the e-mail address needs to be extracted from the Value field. The following message is received from SAP Marketing Cloud (converted to XML):

When the message is received, the e-mail addresses are extracted and transformed into an URL encoded string. Then it is sent to NeverBounce for validation.
<?xml version=’1.0′ encoding=’UTF-8′?>
<d>
<Campaign>
<CampaignId>0000000300</CampaignId>
<Name>OC_Neverbounce</Name>
<MarketingAreaId>CXXGLOBAL</MarketingAreaId>
<SegmentationObject>SAP_CE_CONTACT_ENGAGEMENT</SegmentationObject>
<ImplementationId>ZOC_NEVERBOUNCE_EXPO</ImplementationId>
</Campaign>
<PackageId>1</PackageId>
<ExecutionStartDateTime>2017-06-16T13:42:28Z</ExecutionStartDateTime>
<ExecutionRunKey>02000A1BABB81EE794D333D60ADCBDB3</ExecutionRunKey>
<CampaignTargetGroupMembers>
<OutboundId>B8DE1F6EAC2C09B92F16A99555E690F4D2B15BFE</OutboundId>
<PackageId>1</PackageId>
<ExecutionRunKey>02000A1BABB81EE794D333D60ADCBDB3</ExecutionRunKey>
<TargetGroupMemberAttributeData>
<AttributeId>DA-SAP_CE_IC_CONTACT-IC_ID_ORIGIN</AttributeId>
<Value>EMAIL</Value>
<EdmTypeId>Edm.String</EdmTypeId>
<OutboundId>B8DE1F6EAC2C09B92F16A99555E690F4D2B15BFE</OutboundId>
</TargetGroupMemberAttributeData>
<TargetGroupMemberAttributeData>
<AttributeId>DA-SAP_CE_IC_CONTACT-IC_ID</AttributeId>
<Value>John.Doe@sap.com</Value>
<EdmTypeId>Edm.String</EdmTypeId>
<OutboundId>B8DE1F6EAC2C09B92F16A99555E690F4D2B15BFE</OutboundId>
</TargetGroupMemberAttributeData>
</CampaignTargetGroupMembers>
<CampaignTargetGroupMembers>
<OutboundId>F5C7E84C030D03ADB4E2DD963D52F2C224E7EE0E</OutboundId>
<PackageId>1</PackageId>
<ExecutionRunKey>02000A1BABB81EE794D333D60ADCBDB3</ExecutionRunKey>
<TargetGroupMemberAttributeData>
<AttributeId>DA-SAP_CE_IC_CONTACT-IC_ID_ORIGIN</AttributeId>
<Value>EMAIL</Value>
<EdmTypeId>Edm.String</EdmTypeId>
<OutboundId>F5C7E84C030D03ADB4E2DD963D52F2C224E7EE0E</OutboundId>
</TargetGroupMemberAttributeData>
<TargetGroupMemberAttributeData>
<AttributeId>DA-SAP_CE_IC_CONTACT-IC_ID</AttributeId>
<Value>Max.Mustermann@abc123.com</Value>
<EdmTypeId>Edm.String</EdmTypeId>
<OutboundId>F5C7E84C030D03ADB4E2DD963D52F2C224E7EE0E</OutboundId>
</TargetGroupMemberAttributeData>
</CampaignTargetGroupMembers>
</d>

Example of an URL encoded string for e-mail verification:

John.Doe%40sap.com%0AMax.Mustermann%40abc123.com


The following message is returned to SAP Marketing Cloud:

<?xml version=”1.0″ encoding=”UTF-8″?>
<ImportHeaders>
<ImportHeader>
<Id/>
<Interactions>
<Interaction>
<Timestamp>2017-7-06T11:32:08</Timestamp>
<Reason>EMAIL_INVALID</Reason>
<InteractionType>EMAIL_BOUNCE_HARD</InteractionType>
<ContactIdOrigin>EMAIL</ContactIdOrigin>
<ContactId>Max.Mustermann@abc123.com</ContactId>
<CommunicationMedium>EMAIL</CommunicationMedium>
<Key/>
</Interaction>
</Interactions>
</ImportHeader>
</ImportHeaders>




3. Get the NeverBounce Access Token

For authentication against the API, NeverBounces uses OAuth 2.0.

You need to request an access token before sending a request to one of the verification APIs provided by NeverBounce.


In the iFlow, the mandatory values in the message header and body are defined using a content modifier.

When using the correct request, NeverBounce responds with an access token to be used for the following request. This token is extracted from the response with a Groovy script.

{
    "access_token": "e8d91ea95de5be42cf1f71324f7fcbc33741851a",
    "expires_in": 3600,
    "token_type": "Bearer",
    "scope": "basic user"
}

For additional information on getting started with the NeverBounce APIs, see Getting Started .

4. Validate List of E-Mail Addresses with NeverBounce

Once we have saved the access token in the message header, we can prepare the request to verify the collected e-mail addresses with the NeverBounce API.

In the next step, prepare the request message that will be sent to NeverBounce. Again, we can use a content modifier to prepare the request message.

Refer to the official documentation for the expected format of the request message.

In the response, NeverBounce provides the Job-ID as well as information if the request was received successfully.

To avoid processing unsuccessful requests, we have defined a router that routes messages based on the success value from the NeverBounce response.

To use the router with XPath expressions in the iFlow, the message must be converted to XML format.

For the JSON to XML converter to work properly, there must be only one element at the root level in the body of the message. This can be done using Groovy script or a content modifier.

With the message converted to XML, we can set a routing condition, such as //success = ‘true’.

{
    "success": true,
    "job_status": 0,
    "job_id": 12345,
    "execution_time": 0.16023087501526
}

For additional documentation on API, see Verifying a List .

5. Check the Status of the List Verification

Once the request to validate the e-mail addresses is successful, we then need to wait until the job is done. Depending on the number of e-mail addresses to be validated, this can take several minutes. In our example, we have built the logic in one single iFlow. It would be also possible to split the logic between the different iFlows.

In the local integration process, we check the status every 30 seconds. We also check the response to see if the list verification is completed or not.

In the local process call, you can define an exit condition for looping process calls and a maximum number of iterations to avoid infinite loops. As long the condition expression of the local process call is true, that local process will be iterated.

In our case, we exit the loop process when the list verification has completed or has failed. Adding more than one exit expression is only allowed when using the Camel Simple Expressions.


Condition expression: ${property.status} != ‘4’ or ${property.status} = ‘5’ or ${property.success} = ‘false’




Again, capture any failed messages with the router and end the process when the validation fails.


NeverBounce Dashboard:

Status Codes

Value Description
0 Request has been received but has not started indexing
1 List is indexing and is removing identical entries
2 List is awaiting user input (typically skipped for lists submitted through API)
3 List is being processed
4 List has completed verification
5 List has failed (Click here to learn how to fix a failed list)


6. Download Verified E-Mail addresses

Now that the verification of the e-mail addresses is complete, the results are ready for download.

To download the results, you must make a new request to NeverBounce and provide the access token and Job-ID. Furthermore, you can specify through a parameter which email addresses to download. We recommend limiting the number of results by using this parameter when validating large lists of email addresses. The parameter values are described in the table below. 

NeverBounce will return a message in the following CSV format:

John.Doe@sap.com,valid
Max.Mustermann@abc123.com,invalid

Congratulations! You have successfully verified your list of e-mail addresses.

With this information, you need to update the e-mail addresses on SAP Marketing Cloud.

Parameter Description
valids Include valid e-mails
invalids Include invalid e-mails
catchall Include catchall e-mails
disposable Include disposable e-mails
unknown Include unknown e-mails
duplicates Include duplicated e-mails (duplicates will have the same verification result)
textcodes Result codes will be returned as english words instead of numbers


7. Map the Results to SAP Marketing Cloud Interactions

Before creating an interaction with the e-mail validity update, we need to convert the CSV structured payload to an XML formatted payload. This can be done using the CSV to XML converter integration pattern. To do so, you need to create a simple XML schema file that represents the structure used in the message mapping.

To get the target structure for the message mapping, create an XML schema file with the expected message structure on the receiver site. The XML schema file can be created from the OData receiver channel in the iFlow. 

Simply connect to the OData service or use the OData metadata file from the adapter specific tab. Select the entities, method, and field from the menu. This creates the XML schema file to be used for the message mapping.

For every row entry with an invalid e-mail address, create a new interaction. With this mapping, we only consider invalid e-mail addresses. However, because we download all e-mail verifications from NeverBounce, we need to have some mapping logic to only submit invalid e-mail addresses to SAP Marketing Cloud.

To make the mapping procedure even simpler, download all invalid e-mail addresses from NeverBounce. 


Field Mapping Mandatory
Timestamp currentDate(“yyyy-M-dd’T’HH:mm:ss”,”Sunday”,”1″,”true”) x
InteractionType

const(

“EMAIL_BOUNCE_HARD”)

x
ContactIdOrigin const(“”EMAIL””) x
ContactId ifWithoutElse(stringEquals(/root/row/status,const(“”invalid””)),/root/row/email,””true””) x
CommunicationMedium const(“”EMAIL””) x
Key const(“”””) x




8. Import the Interactions to SAP Marketing Cloud

Finalize the iFlow by configuring the SAP Marketing Cloud receiver. This should already be partly done, from when you completed step 7.

The authentication method is dependent on what was configured for the Inbound Communication Arrangement in SAP Marketing Cloud.



9. Review the Data on SAP Marketing Cloud

Before we started this exercise, we replicated some data to SAP Marketing Cloud, including some dummy data with invalid e-mail addresses.

When creating the target group, we made sure that Mr. Max Mustermann and Mr. John Doe were members of the defined target group.

When releasing a campaign in SAP Marketing Cloud, all target group members belonging to the campaign will be validated by NeverBounce automatically.


Contact Profile before the e-mail address was sent to NeverBounce for verification:


After importing the hard bounce interaction, the e-mail facet is no longer available in the contact profile:


Conclusion

In this article, you learned how to set up the iFlow on SAP Integration Suite to integrate SAP Marketing Cloud with NeverBounce. In the following articles, you can learn more about the overall integration between SAP Marketing Cloud and NeverBounce as well as the e-mail validations with NeverBounce.

Overlay