Synchronizing Email Unsubscribes Across Instances

May 11, 2015 | by

Do you manage multiple instances of Marketo?  Keeping lead information synchronized across instances can be challenging.  Here is a way to sync email unsubscribes across instances using a webhook that calls an external web service.  The external web service loops through each instance looking for the known lead that triggered the unsubscribe event.  When a matching lead is found the “unsubscribed” field in the corresponding lead record is updated.

Here is a diagram illustrating the idea.

Email_Unsubscribe_Sync_Overview

It’s up to you to implement the web service, but the code below should help you jumpstart the process!

External Web Service

Here is the proposed REST endpoint specification for the external web service:

URI: /unsubscribe

Method: POST

Parameter Description Example
id Account id that triggered the unsubscribe event. AAA-111-BBB
email Email address of the lead that triggered the unsubscribe event. jdoe@marketo.com

The external web service performs the following steps for each Marketo instance that needs to be synchronized:

  1. Composes instance-specific REST API Endpoint URL
  2. Obtains access token using Identity
  3. Obtains list of lead records that match email address using Get Multiple Leads by Filter Type
  4. Updates “unsubscribed” field of each lead record using Create/Update Leads

Here is another diagram showing the external web service call and Marketo REST API calls in detail.

Email_Unsubscribe_Sync_Detail

The sample code below is not an out of the box web service.  Rather, it is a console mode program that you can pass arguments to via the command line.  The intent here is to show how to call the appropriate Marketo APIs to update lead records across instances.  Implementing the web service is left as an exercise for the reader 😉

Sample Code

To get the sample code up and running, you will need to create a Java project in your favorite IDE.  After that, you will need to make the following changes:

1. The sample code uses json-simple to parse JSON strings.  Add the json-simple jar to your Java project.

2. The sample code has a structure that holds metadata for each Marketo instance.  Place actual values from your instances into the structure as follows:

You can find the metadata for the instance in the Marketo Admin panel:

  • Account Id
    Admin >  Integration > Munchkin > Munchkin Account
  • Client Id & Client Secret
    Admin > Integration > LaunchPoint > Email Unsubscribe Sync > View Details

3. The sample code takes two command line arguments that simulate the “id” and “email” query parameters for external web service described above.

  1. args[0] = Account Id
  2. args[1] = Email Address

Pass actual values from your instance as arguments to the program.  Here is a project configuration screenshot from Intellij IDEA.

email_unsubscribe_intellij_project

SyncEmailUnsubscribe.java

Marketo Setup

Perform the following steps for each Marketo instance that you would like to sync.

  1. Create a Custom Service with role permission: Read-Write Lead. If you are unfamiliar with creating a Custom Service, click here.
  2. Create a Webhook that calls your external web service. If you are unfamiliar with creating Webhooks, click here.
  3. Add Webhook as flow step in Smart Campaign.

The screenshot below shows how to create a webhook to invoke the service specified above using tokens to automatically populate the query parameters.

email_unsubscribe_webhook

Now that we have created our webhook, we can add it to a Smart Campaign as a flow action.

email_unsubscribe_flow_step

The Smart List should contain an “Unsubsubscribes from Email” trigger.

email_unsubscribe_smartlist

 Validation

To test this all out, create a lead with the same email address in several Marketo instances.  Make sure that you own the email address!  In one instance trigger a send email flow action, open the resultant email, and click unsubscribe.  To validate results, log into each of the other instances and inspect the lead records associated with the email address.  The “Unsubscribed” checkbox should be checked, and the “Unsubscribed Reason” field should contain a note with the source account id that initiated the sync.

email_unsubscribe_lead_record