Custom Google List Unsubscribe Flow

Overview

Gmail offers a feature where contacts can choose to unsubscribe from a list with link in the message header. This is different than clicking on the opt-out link that a marketer might put at the bottom of an email.

The default Cordial behavior is to unsubscribe the email address when this event is received. In some cases, this might not be the desired behavior. For example, your brand might have a national list and a local list. A customer might want to continue to receive your national email while also wanting to be removed from your local email, or vice versa. This article outlines the steps needed to accomplish this with the Gmail List Unsubscribe.  

Prerequisites

• The email-mta-optout-bypass feature must be enabled in your Cordial account.
• You need your own SparkPost account.
• Your SparkPost account needs to be configured to pass unsubscribed contacts directly to Cordial.
• Data jobs are in place to handle list management based on unsubscribe events.

Add list to message

To be successful with this use case, we need to add the Cordial list to the email—so if the contact chooses List Unsubscribe, we know which list to remove them from. Next, we need to add the Gmail list name so the contact sees the correct display when they choose to List Unsubscribe.  

{$utils->addSendProperties(['listID' => 'local_email'])} {* Cordial List Name *}
{$utils->setEmailHeaders(['List-ID' => 'Local Email List'])} {* List Name as Displayed
in Gmail *}

View of the list in the Cordial platform

View of the List-ID in Gmail

Create data job

Create an automated event-triggered data job with email-mta-optout-bypass as the triggering event.

{$data.metadata = $utils->renderInfo()}
{$data.blockUpdate = 0}

{if in_array($triggerData.sp.listID, $contact.lists|default:[])}
  {* This users is on the list used for the unsub *}
  {$updateRecord.data[$triggerData.sp.listID] = false}
{else}
  {* This users is NOT on the list used for the unsub, so we optout as failsafe *}
  {$updateRecord.data.channels.email.address = $contact.channels.email.address}
  {$updateRecord.data.channels.email.subscribeStatus = 'unsubscribed'}
{/if}

{$updateRecord.waitForResult = true} 
{$updateRecord.suppressTriggers = true}
{$updateRecord.forceSubscribe = false}

{if not $data.blockUpdate and not $data.metadata.preview}
  {$updateRecord.result = $utils->updateContact($updateRecord.data, $updateRecord.waitForResult, $updateRecord.suppressTriggers, $updateRecord.forceSubscribe)}
  {if not empty($triggerData.sp.transportID)}
    {$updateRecord.sparkpost_result = $utils->removeSparkpostSuppression("email:{$contact.channels.email.address}", $triggerData.sp.transportID, $updateRecord.waitForResult)}
  {/if}
{/if}

{if $data.metadata.preview}
  <h2>Debug $updateRecord</h2>
  {$utils->jsonPrettyPrint($updateRecord)}
  
  <h2>Debug $data</h2>
  {$utils->jsonPrettyPrint($data)}
  
  <h2>Debug $contact</h2>
  {$utils->jsonPrettyPrint($contact)}

{/if}