Set User Vars or List Membership On-Click with URL Parameters

Sailthru provides two special query parameters which, when present in clicked URLs, will trigger custom actions on the user’s profile based on the values you pass.

These parameters work with hard-coded values as well as dynamic values inserted by your Zephyr code, for example, metadata available on your feed items or any other data accessible in your template.

  • sailthru_vars – adds or modifies a custom variable value on a user’s profile.This can be used to maintain data about the users who have engaged with particular topics or campaign types, but you may also find your own unique uses for this flexible feature.To add or update a var, append ?sailthru_vars[VarName]=value to the URL.
    • If the variable name already exists on the profile, its value is updated. If not, it is created.
    • By default, the data type is auto-detected, e.g. true is set to boolean. If you want to manually define the data type for a VarName that you have specified in the URL, append this additional parameter after an ampersand: sailthru_vars_type[VarName]=boolean/number/string
    • Complex data types, such as arrays or objects, are not supported by this feature.
  • sailthru_lists – adds a user to a list or removes the user from a list.This can be used to automatically enroll users in segment-specific email campaigns based on their engagement with particular topics in your broader email sends, or any other case where it is appropriate to subscribe or unsubscribe to a list upon a user’s single click. Note that for opt-outs, we recommend using a user-management page to allow further options, including opt-downs.
    • To subscribe the user to list “ListName”, append to the URL:
      ?sailthru_lists[ListName]=1The list must already exist, otherwise, this parameter will have no effect.
    • To unsubscribe the user from list “ListName”, append to the URL:
      ?sailthru_lists[ListName]=0

    Note: With sailthru_lists, you can add or remove users from existing natural lists only. You cannot use this feature to create a new list or modify a Smart List. (Smart lists are built dynamically, based on your chosen criteria, and do not support the manual addition or removal of individual users. However, you can use sailthru_vars to modify a user’s vars that are used in smart list criteria, thereby affecting the user’s smart list memberships.) If you specify a list name in the sailthru_lists parameter that is not recognized as an existing natural list, the URL will still open the intended page, but the parameter will have no effect.

Note: Link tracking must be implemented for your emails in order for these query parameters to be detected and utilized by Sailthru. They cannot be used on links to Sailthru hosted pages.

URL Format

  • You can choose to append multiple instances of these parameters to your URLs, separated by ampersands (&). For example:
    http://example.com/path/?sailthru_vars[TopicA]=Example&sailthru_lists[ListX]=1There is a limit of 5 vars and 5 lists per URL. If you inadvertently include more than five of either parameter type, Sailthru will only process the first five of each, and the user will still reach the intended destination page.
  • If you need to pass a string that contains spaces–a common occurrence with list names–you must encode the string. You can encode it on the fly within your template using the Zephyr function u(). For example:
    http://example.com?sailthru_lists[{u("XKCD Fans")}]=1
  • These features do not work when hash marks are included in the URL. For example, the following URL will not affect any vars:
    http://example.com?sailthru_vars[TopicA]=Example#sectionName

When your URL is properly formatted according to these specifications, users will not see these parameters and values. After they are stripped out for processing by Sailthru, any other custom parameters are retained on the URL and available for processing by your site.

Examples

var modifications

Use this feature to save the top-level categories a user is interested in. Use Zephyr to add each content item’s category as a var name in its link with a value of true. When a user clicks, they will have a profile var of that category name created and set to a value of true.

Zephyr code:

{foreach content as c}
<a href="{c.url}?sailthru_vars[{c.category}]=true">{c.title}</a>
{/foreach}

Resulting HTML in the email body:

<a href="http://example.com/article/101?sailthru_vars[Sports]=true">Super Bowl 52 Location Set</a>
<a href="http://example.com/article/102?sailthru_vars[Music]=true">Coachella Announces Full Lineup</a>

list modifications

Allow a user to perform a single-click sign-up to one of your lists.

<a href="http://example.com/signup_thank_you_page.html?sailthru_lists[{u("Fall Harvest Festival 2016")}]=1">Click to join this year's Fall Harvest Festival Newsletter!</a>
Top