Mailing list opt-outs

A new method is available for managing mailing list opt-outs. There is no obligation to use it, but it offers some advantages.

Previously, the link which a recipient could click to opt-out from mailings identified them (and the list to opt-out from) by a combination of membership number, qrcode and list name. Now, a new-style link can instead include just an un-guessable string which identifies the actual email message. (This is actually the same identifier which is already used in view message in browser links).

How the new link works

If someone clicks an opt-out link in the new format, the identifier is user to look up the email message in Cameo’s database. That in turn provides the membership number, qrcode and, via the template which produced the email, the list name which is needed to complete the opt-out, rather than supplying this information directly in the URL.

This new format for the opt-out link is somewhat more secure: it doesn’t contain any identifying details.

But the main advantage is that it is now possible to automatically include the link in the email header (metadata) in a standard format (called List-Unsubscribe). This allows email apps to offer a standard opt-out link or button in their user interface, as well as the link you put in the message itself. It only does this with the new format link. Not all email clients show this and those that do only according to some reputational criteria that they alone decide. But when they do, this helps mailing list maintenance and makes it less likely that people will mark an email as spam when they are merely don’t want it any more (which affects delivery success for everyone).

Instead of using the opt-out link, automatic opt-outs shown by an email app may choose to send an email to an address also given in the List-Unsubscribe email header. Cameo always sets this to the from email address of the email. Any such emails will need to be acted on manually in the Subscriptions section of Membership Tasks.

Using opt-out links

There are two pieces involved in using opt-out links:

• Including the link in relevant email messages. The format of the URL for the link is set in the Organisation Details section of Organisation Settings, and is substituted into an email template using {show: optout link}
• responding to the link when someone clicks on it (whether explicitly in the email or, now, in an email app’s automatically generated button). This is done using either Cameo’s optout form, or possibly a custom form you have written using Cameo’s API.

Opt-out link format

The opt-out link in Organisation Details itself contains some text to be substituted. Using the old format, it might look something like this:

https://example.com/optout.html?m=_M_&q=_Q_&l=_L_

_M_, _Q_ and _L_ are substituted with the membership number, qrcode and list name when the template using it is merged. Setting the link like this lets you customise the names (m, q and l) of the query parameters in the URL, as well as where your opt-out page is located.

Now, in the new format, you use just _H_ instead, with a different parameter name, to identify the message. For example:

https://example.com/optout.html?msg=_H_

Once you make this change, any opt-out link substitutions in your templates will include the new format when they are merged, and the List-Unsubscribe header will also be added when the email is actually sent.

Incidentally, if you ever change the location of the page, you should make a redirect in your website so old links already in people’s emails continue to work.

Opt-out form

The opt-out form is simplified. You previously had to tell the form what query parameters to expect in the opt-out URL (m, q, l and msg in the above examples). These details have been removed from the form definition because it now works this out for you from the opt-out link set in Organisation Settings as above, whether in new or old format.

Therefore once you have changed the opt-out link, just re-install your forms to let the opt-out form use the new link. It will respond to either the old or new format (it should continue to recognise the old format as people may have such links in their older emails already).

UPDATE Dec 2019: Cameo version 9 now previews the form, but the principle is the same: you don’t need to name the query parameters.

API

There is a new API endpoint to support custom forms doing the same job when the message identifier is provided in the opt-out page’s URL. It is quite likely you will have hard-coded the parameter names to match the format in Organisation Details, so it is now just a matter of recognising the new one for message identifier instead and acting on it using the new API. This is:

emailinfo.json?hash=H

where H is the message identifier. This returns a JSON structure containing the corresponding membershipnumber, qrcode and listname that would previously have been supplied directly in the URL. For example:

    {
        "membershipnumber": 1234,
        "qrcode": "ABCDEF",
        "listname": "our list"
    }