Overview

Cordial provides a standard opt-out page for unsubscribing contacts via the default opt-out link. In some cases, however, you may want greater control over functionality and branding. You can achieve this by building and hosting your own custom preference center page while utilizing the Cordial REST API to update a contact's subscribe status and list memberships.

This article will provide examples of how to take advantage of Cordial's REST API for updating a contact record. Please view the article on API summary and usage for more information on authentication, Cordial's API endpoint, supported methods and more.

Example preferences form

The following is an example form used to update a contact's list membership and subscribe status:

Retrieve the contact record

Create the URL to your preference page

In order to populate the form with a contact's profile data you will need to retrieve the contact's record using the contact's ID (cID). The cID may be passed in the URL to your preferences form using a system variable in the query string.

Example URL with cID appended as a query string:

https://example.com/preference_form.html?cID={$contact._id}

Password protect your preference page

In order to maintain security, we strongly recommend protecting your preference form behind a password protected page, such as an account login. However, we recognize that many clients do not require or support authenticated access to their domains. In this case, clients should follow our recommended best practices below.

Best practices: use a hash-based message authentication code (HMAC)

If you're unable to password protect your page, we recommend hashing the URL using a hashing algorithm and HMAC to authenticate.

Cordial supports a hash_hmac Smarty modifier you can use to generate an HMAC signed link:

{$hmac_secret = 'some long secret value'}
{$link = "https://example.com/preference_form.html?cID={$contact._id}"}
{$hmac = "{$link|hash_hmac:'sha256':$hmac_secret}"}

<a href="{$link}&hmac={$hmac}">{$link}&hmac={$hmac}</a>

• For more information on using HMAC for authentication please view the following page:
  https://en.wikipedia.org/wiki/HMAC

Retrieve contact data using the API

Using the GET <path>/contacts/cID:{cID} API call, you can retrieve data about the contact.

For example:

GET <path>/contacts/cID:5552fc99990c811781477777

Sample response from a GET <path>/contacts API call:

{
    "_id": "5552fc99990c811781477777",
    "channels": {
      "email": {
        "address": "john@example.com",
        "subscribeStatus": "subscribed"
      }
    },
    "attributes": {
        "firstName": "John",
        "lastName": "Smith",
        "lists": [
            "daily_promotions",
            "weekly_promotions",
            "monthly_newsletter"
        ]
    }
}

In the past, the ?isCid=true URI parameter was used to specify the contact identifier type being passed. This query parameter is still supported, however, we recommend the key:value structure going forward, which is consistent with the Cordial REST resource naming convention.

Update the contact record

Once you have contact data available, you can update the contact record using the PUT methods to the contact collection with the contact's primary key (most likely email address).

Remember to use all the appropriate web security measures to assure that only authenticated users are allowed to submit a request to modify a contact. Ensure that the contents of the changes are valid, and that the form itself is protected against abuse.

Update contact's email address

Using the PUT <path>/contacts/{primary_key} or /{secondary_key}:{value} API call, you can update the contact's email address to a new value.

Example JSON request to update the contact's email address:

{ 
   "channels":{ 
      "email":{ 
         "address":"new_email@example.com"
      }
   }
}

Update list membership

To update the list membership of the contact, use the PUT <path>/contacts/{primary_key} or /{secondary_key}:{value} API call.

Example JSON request to update the list membership:

{
  "daily_promotions": false,
  "weekly_promotions": false,
  "monthly_newsletter": true,
}

Update subscribe status

Unsubscribe a contact

To unsubscribe a contact, use the PUT <path>/contacts/{primary_key} or /{secondary_key}:{value}/unsubscribe/{channel} API call.

Example request to unsubscribe the contact from the email channel:

PUT <path>/contacts/email:john@exampe.com/unsubscribe/email

Attribute an unsubscribe

By adding the mcID (message contact ID) query parameter, you can attribute the unsubscribe to a specific message.

Example request to unsubscribe the contact from the email channel with attribution:

PUT /contacts/email:john@exampe.com/unsubscribe/email?mcID=252:5bb795c36fc360de221c03ae:ot:5bb647499dadbb3b3b14d855:1

Unsubscribing a contact using the above methods will change the subscribe status of a contact to "unsubscribed" and create a new opt-out event in the contact activities collection.

Sample response of an opt-out event using GET <path>/contactactivities.

{
      "cID": "5552fc99990c811781477777",
      "mcID": "252:5bb795c36fc360de221c03ae:ot:5bb647499dadbb3b3b14d855:1",
      "first": true,
      "_id": "5bb796bf2cab4e1b1697573e",
      "action": "optout",
      "time": "2018-10-05T16:52:15+0000",
      "bmID": "252:5bb795c36fc360de221c03ae:ot",
      "email": "john@example.com",
      "system_properties": {
        "mTags": []
      }
    }

Subscribe a contact

Using the POST <path>/contacts API call you can subscribe a contact.

Example JSON request to subscribe a contact to the email channel:

{ 
   "channels":{ 
      "email":{ 
         "address":"john@example.com",
         "subscribeStatus":"subscribed"
      }
   }
}

Resubscribe a contact

Using the POST<path>/contacts API call you can re-subscribe a contact.

Example JSON request to re-subscribe the contact from the email channel:

{
  "channels": {
    "email": {
      "address": "john@example.com",
      "subscribeStatus": "subscribed",
      "invalid": false
    }
  },
  "forceSubscribe": true
}

In the request body above forceSubscribe is required to re-subscribe a contact if previously unsubscribed. The "invalid" : false parameter is required if a contact's email had been previously invalidated due to a hard bounce.

If a contact unsubscribes via the list-unsubscribe mechanism of an inbox provider (i.e. Gmail) and added to an MTA (message transport agent) suppression list, re-validating the contact using the invalid parameter will not update the MTA suppression.

• Learn more about unsubscribe status.