How can we help?

Custom Google list unsubscribe flow


Gmail offers a feature where contacts can choose to unsubscribe from a list with a 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.  


  • 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

1. To be successful with this use case, you need to add the Cordial list to the emailso if the contact chooses List Unsubscribe, you know which list to remove them from.

2. Next, add the Gmail list name so the contact sees the correct display when they choose to List Unsubscribe.  

It's important to remember that the word 'list' means different things to different vendors.

{$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

Navigate to Data > Lists to access, add, and edit lists. 

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 *}
  {$[$triggerData.sp.listID] = false}
  {* This users is NOT on the list used for the unsub, so we optout as failsafe *}
  {$ = $}
  {$ = 'unsubscribed'}

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

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

{if $data.metadata.preview}
  <h2>Debug $updateRecord</h2>
  <h2>Debug $data</h2>
  <h2>Debug $contact</h2>




Please sign in to leave a comment.