The comprehensive guide to setting up the unsubscribe link

As this is a recurrent request in this community, here are the various ways of setting up the unsubscribe links in Marketo, and when one should use them.

0-Summary

The following table summarizes the possible approaches, when to use them and what chapter you should read:

IfRecommended implementation steps
You want a quick and minimal version that works well and guarantees compliance
  1. Customize the default code (See 2)
  2. Customize the default page (See 3)
You want to properly brand your unsubscribe landing page, and continue using Marketo default or system token
  1. Create a new Unsubscribe page with your own template. Place it preferably in a marketing activities program together with it's follow-up page and any smart campaign you may need
  2. Redirect the /UnsubscribePage.html URL to your page (See 4)
  3. If you plan to use it, customize the default code (See 2)
You need various unsubscribe pages for different audiences (segments, language, ...)
  1. Create your various unsubscribe pages. Place them preferably in marketing activities programs together with their follow-up pages and any additional smart campaigns you may need
  2. Add a snippet element in a dedicated module at the bottom of your email templates (or a text element if you are still using email 1.0)
  3. Deactivate the default link (6)
  4. Create unsubscribe snippets using the customized URL (See 5 ). You can even make these snippets dynamic if the various Unsub LP's are linked to segments.

1-The 3 ways to add an unsubscribe link to an email

There are 3 ways to get the unsub link added to an email:

  1. just ignore the problem. When you send an email, Marketo will detect that no unsubscribe link is included and will automatically add it's default one, that is defined in the admin -> email section and which code is:
    • <p><font face="Verdana" size="1">This email was sent to {{lead.Email Address}}. If you no longer wish to receive these emails you may <a href="%mkt_opt_out_prefix%UnsubscribePage.html?mkt_unsubscribe=1&mkt_tok=##MKT_TOK##">unsubscribe</a> at any time. </font></p>

  2. add the {{system.unsubscribeLink}} to your emails as the href in an <a> tag. This can be done in the template (even hard coded there) or left to the user. That will be enough and Marketo will automatically understand that it should replace the token with the proper link and that it should not add the default unsubscribe link. So <a href="{{system.unsubscribeLink}}">my unsub link</a> will become <a href="http://mktolpsubdomain.company.com/UnsubscribePage.html?mkt_unsubscribe=1&mkt_tok=##MKT_TOK##">my unsub link</a> at runtime.
  3. Add a link towards any LP in Marketo, with "?mkt_unsubscribe=1&mkt_tok=##MKT_TOK##" at the end of the href. This will be enough for Marketo to know not to add the default link to the email.

2-Customize the Marketo default code

The default admin-> email code can be customized by anyone who knows some rudiments of HTML. Text, fonts, colors, layout, etc.. can be changed. Just always make sure you do not remove the "?mkt_unsubscribe=1" from the link href.

Typically:

<table align="center" width="600">
     <tr>
          <td style="font-family: helvetica; font-size:10px; color:#555;">
               This email was sent to {{lead.Email Address}}. In order to stop receiving our spammy emails <a href="
http://mktolpsubdomain.company.com/myniceunsubpage.html?mkt_unsubscribe=1&mkt_tok=##MKT_TOK##" class="mktNoTrack" target="_blank">click here.</a>
          </td>
     </tr>
</table>

will work perfectly well.

Please note that, in order to prevent Marketo to track the click on the link, you will have to add class="mktNoTrack" to the <a> tag.

3-Customize the Marketo Default page

By default, all Marketo instances come up with an unsubscribe page that use the ugly akward Standard free form template:

pastedImage_1.png

This page will be located in the design studio, and it's name will be localized in the language in which you instance was initially created.

The most obvious and simplest move is to customize this page and make it a little more looking like a page from your company

You can also move this page in a program in the marketing activities. As long as it's URL keeps being UnsubscribePage.html (see below) it will continue to work.

4-Redirect the default link to another, nicer, page

Now, maybe you would like to use another template for your landing page. Or maybe you want to replace this unsubscribe page with a thoroughly designed subscription center. But you want to keep the usability for your Marketo users, so you would like to keep the {{system.unsubscribeLink}} token or the Marketo Default driving the visitors to your nicer LP.

For this, you need to know that, whatever the config of your instance, the {{system.unsubscribeLink}} token always direct to /UnsubscribePage.html. So you will just need to have this URL reassigned to your new and nice unsubscribe page. This is again quite easy using Marketo URL tools. Once your new unsubscribe page is ready and tested:

  1. Go to your old unbsubscribe page. In Marketo UI, click the Landing Page actions -> URL Tools -> Edit URL settings:pastedImage_9.png
  2. In the dialog box, change the URL to anything (I personally simply add "old" to the end of it.
    pastedImage_13.png
    Tip: What is important here is to throw away to previous URL so that the URL becomes available
  3. Then go to your new unsubscribe page and do exactly the same thing, granting this new page the UnsubscribePage.html URL

To run this process, wait until a moment when no email has been sent in the past hours, since you will have no unsub page available between steps 2 and 3.

5-Use a different URL for the unsubscribe page

May be you want to use a different URL for this page, or even have various URLs for various contexts. In fact, nothing mandates you to always use the {{system.unsubscribeLink}} or the /UnsubscribePage.html URL. Any Marketo LP URL will do the job here, as long as it is appended with the "?mkt_unsubscribe=1" to indicate to Marketo that this is an unsubscribe link. You should also add the &mkt_tok=##MKT_TOK## to make the click on the link carry the token value and enable cookie value reconciliation. Please also note that, in order to prevent Marketo to track the click on the link, you will have to add class="mktNoTrack" to the <a> tag.

The following is a perfect unsubscribe link in an email template:

<tr><td>This email was sent to {{lead.Email Address}}. In order to stop receiving our spammy emails <a href="http://mktolpsubdomain.company.com/myniceunsubpage.html?mkt_unsubscribe=1&mkt_tok=##MKT_TOK##" class="mktNoTrack" target="_blank">click here.</a></td><tr>

As you can see, it takes no token and not event the /UnsubscribePage.html URL.

This method will be necessary in a multi language / international roll out: you will need to have multiple, different Unsubscribe pages for each language and the Marketo default or {{system.unsubscribeLink}} token can only link to one of them.

Also please note that the unsub code can be added to snippets, which in turn can be added to the emails for maximum flexibility.

6-Disable the default Marketo unsub link.

If you are sure that your email templates always include the necessary links and you want to avoid Marketo adding it's own link just replace the default unsubscribe links with HTML comments in admin->email

pastedImage_35.png

Hope this helps,

-Greg

58075
74
74 Comments
Michael_Florin
Level 10

Yes, that looks exactly right. I'd even suggest to do something like 

<a href="https://{{my.unsubscribe-link}}" class="mktNoTrack" target="_blank">

where the token value for my.unsubscribe-link is

info.mydomain.com/custom-unsubscribepage.html?mkt_unsubscribe=1&mkt_tok=##MKT_TOK##  

And yes, that token/snippet/footer would need to exist in all your workspaces. That's the downside of workspaces that you cannot just place one token like this in your highest folder and reference it in every email - or every footer snippet - underneath that folder.

 

And of course you have to set up the page "https://info.mydomain.com/custom-unsubscribepage.html", where either "Unsubscribed" is a hidden form field with the value "TRUE" or a Smart Campaign sets Unsubscribed to TRUE. That field value change IS the actual unsubscription action.

haliddelkic-cr
Level 1

Thanks @Michael_Florin - appreciate the suggestions re token & setting the Unsubscribe field. 

 

However my specific issue is slightly different.

We are using two different Workspaces for two separate business units, with a shared database (no partitions). There is a crossover of leads actively involved, and receiving emails from, both BU's. 

 

As such, we're using custom fields associated with each BU to manage preferences across two custom landing pages. 

 

Ideal set-up should work something like this:

  • Workspace 1 - emails template has custom footer embedded, system footer should not append; directs leads to custom preference page 1
  • Workspace 2 - system footer appended (no custom footer created); directs leads to custom preference page 2

My testing in Workspace 1 includes the code I referred to in my earlier post, but Marketo is still adding the global footer to those emails. 

 

Below is a screenshot of my test email in Workspace 1. 

 

It's in Workspace 1 where I'm experience the issue of both footers appearing on emails and having trouble figuring out why.

 

Workspace 1 - Custom FooterWorkspace 1 - Custom Footer

Andrew_Cutting1
Level 2

I've read through the whole chain of responses here, but I still have a few questions that I didn't see explicitly answered. Namely, what is actually happening behind the scenes as a result of including the query string:

 

 

?mkt_unsubscribe=1&mkt_tok=##MKT_TOK##

 

 


The second half (mkto token) kind of makes sense to me. I've set the class to "mktNoTrack", but still need a way to reconcile the cookie value....although aren't these two ideas sort of going against eachother? If you're turning off link tracking, but then just adding the token back on, what are we actually doing? My only assumption is that this set up prevents unsubscribe clicks from impacting click reports while still letting you reconcile the cookie. If so, then great. Just want to confirm that's what is actually happening here.

 

The unsubscribe=1 part is really what I'm confused on. What actually is this? Is its sole purpose just to let marketo know that clicks on links containing that parameter are unsubscribe clicks? If yes, does that just used for counting how many unsubscribe clicks your email gets? Someone also mentioned it could affect the "unsubscribed from email" filter. Is that true? Does it also affect the system unsubscribe field in any way?

 

Note, in our setup, someone who clicks a manage preferences link shouldn't actually be "unsubscribing" (meaning the system-level field changes to true) until they hit submit on the communication preferences form on that landing page, and only if they didn't request to still receive certain types of emails from us. So unsubscribed could be misleading here. That said i'd rather a report be directional and show unsubscribe link clicks (even if all don't fully unsubscribe) than it show we have a 0% opt-out rate on all our emails because there's no query string value to count.

 

More context: I have the more complex set up--different communication preference centers for different brands we manage. I have a different email footer snippet for each brand, each containing their own link (to a branded mkto landing page). As a result we do not use the generic system opt out link and have commented-out that value in admin. Right now the link looks like "https://www.subdomain.domain.com/manage-preferences-brand". Basically trying to determine if adding that query string to the link in each snippet is really necessary or not.

 

Thanks!

josecolella
Level 1

@Grégoire_Miche2 Thanks for your comprehensive answer. I have the following use-case. 

 

I'm create a subscription center page outside of Marketo, in order to have our local branding and styling. I have attached the following query parameters to the unsubscription url: ?mkt_unsubscribe=1&mkt_tok=##MKT_TOK## . My question is:

 

1. Does the created page need to have an embedded Marketo form to work? or is it possible to leverage standard HTML forms that will send make a call to a backend to use Marketo REST API to modify the field based on the user changes?

2. Is it possible to identify the lead somehow so I can retrieve their current preferences when the person lands on the page?

SanfordWhiteman
Level 10 - Community Moderator
1. Does the created page need to have an embedded Marketo form to work? or is it possible to leverage standard HTML forms that will send make a call to a backend to use Marketo REST API to modify the field based on the user changes?

The Submit Form REST API endpoint exists, but it's not recommended unless absolutely proven to be necessary.

 

It's far better, if you don't want to use a visible Marketo form, to use a hidden Marketo form to submit vanilla HTML form data using the Forms 2.0 JS API. There are many examples of this if you search past community threads.

 

2. Is it possible to identify the lead somehow so I can retrieve their current preferences when the person lands on the page?

If you use my Form Pre-Fill JS, yes. Search for "Pre-Fill. Any Site. Any Form" (no other method is safe to use due to DoS attacks).

josecolella
Level 1

Thanks @SanfordWhiteman ,

one more question is it possible to identify a user/lead based on the mkt_tok value using the REST API?

SanfordWhiteman
Level 10 - Community Moderator

Can you explain exactly why you'd want/need to do this?

josecolella
Level 1

@SanfordWhiteman Basically the new subscription center will be hosted outside of Marketo and will need to use the React component library components to create the form. Currently I was able to add the following query parameters to the unsubscription url: ?mkt_unsubscribe=1&mkt_tok=##MKT_TOK##

Next steps:

1. Identify the user that clicked the unsubscribe link to lead their subscription preferences, with associated email

 

In order to do this I need to be able to get the user associated with that click. is that possible in marketo? Please let me know if this makes sense

SanfordWhiteman
Level 10 - Community Moderator

That's exactly what you don't want to do. It's the DoS attack vector of a lifetime - all I need to do is randomize a mkt_tok and drain all your API calls.

 

The right way to look it up is using my client-side method Dave links to here: https://nation.marketo.com/t5/product-discussions/filling-in-field-hidden-by-visibility-rules-on-emb...

 

melissabasisty
Level 1

Hello there!

 

I am updating our email footer snippet to include a customized URL to replace the Marketo Unsubscribe page in our new email template.

 

After reading this resource and adding ?mkt_unsubscribe=1 then trying ?mkt_unsubscribe=1&mkt_tok=##MKT_TOK## to the customized URL, the Marketo default text "If you no longer wish to receive these emails, click on the following link: Unsubscribe " is still appearing in email footers. 

 

I also tested {{system.unsubscribeLink}} in the email snippet. When applying the token, the Marketo default text did not appear.

 

Can someone please advise on what I am missing? Thank you in advance!