Published — v. 16

Advanced content personalization

Owned by MailUp Dev Team (Unlicensed)
Last updated: Sept 20, 2018
7 min read

Overview

The content personalization is an advanced feature. It is very powerful but it requires some development (building or configuring an API, and edit HTML messages using a special markup language…)
It is a paid feature that is disabled by default on MailUp accounts. Please contact your sales reference person if you wish to try it out.

 

Use cases

You should be interested in the “content personalization” feature if your “job to be done” includes at least one of these:

  • Access to unlimited custom fields for content personalization, overcoming the current MailUp limit of 39 fields
  • Simplify message building when the content is mostly available outside MailUp (i.e. avoiding useless data copy)
  • Retrieve content in real time, just before sending, from an external service (e.g. for up-to-date product recommendations)

Getting started

Here is a short list of the steps to be followed:

  1. First build the external service

    1. Start building a web service on your platform. This service has to be a public URL that accepts an unique user ID as a parameter (e.g. the email, the customer ID...). When called, it must return a JSON dataset containing user specific information.

  2. Then reference your service on MailUp

    1. You can extend MailUp settings with a reference to your service(s). The URL of any of these services is called endpoint. Several endpoints may be added, then you can link them to a specific MailUp message or to a list. This operation can be done through the web interface of your MailUp account or using the API methods described in this page

  3. Finally create a message that requires the service and send it

    1. Create an email message and add HTML blocks containing a special markup language called Liquid, whose tags use curly brackets and allow very powerful statements

    2. Just before sending the email, MailUp queries the predefined endpoint for each campaign’s recipient. The returned values will replace the tags built with Liquid markup

    3. Fields are replaced in real time, so this is a perfect solution if you have a product recommendation engine that provides an URL for querying it 
    4. Note: as the provider of the external service, you are supposed to know well the returned JSON object (field names, nested structures...) so that you know the names of the placeholders/tags you have to add to your messages

Do you need help?

If you need more details or you cannot manage to implement an API on your own, the MailUp Professional Services team can help you. Either with custom development tasks or for advisory.

 

Table of Contents

Technical details

Endpoint specification (request)

The external endpoint shall be called using HTTP GET and optional querystring parameters. Basic Authentication and custom authorization headers are supported.
The endpoints’ signature should support one of the formats shown in the table below. Other formats may be supported, please ask if you need more.

TemplateDescriptionExample
MY_ENDPOINT_URL/EMAILquery by emailhttps://personalization.mysite.com/product/john@example.com
MY_ENDPOINT_URL/RECIPIENT_FIELDquery by a MailUp personal field, like firstname or ClientIDhttps://personalization.mysite.com/product/ID000111222
MY_ENDPOINT_URL/EMAIL?FIELD1=value,FIELD2=valuemore query parameters can be used by specifying key-value pairs
via querystring. The names of the allowed keys can be set on the
MailUp web application or using the API described at the bottom of
this page 		 

In additional to personal data fields, you may invoke the external endpoint by specifying also one or more of the following querystring parameters:

 

Parameter nameDescriptionExample
IdConsoleMailUp account ID59484
IdListMailUp list IDMailUp message ID
groupsMailUp groups the recipient is matching in current mailing24,25,29
filtersMailUp filters the recipient is matching in current mailing10,21

Endpoint specification (response)
You are free to design the response structure that better suits your needs when it comes to use the returned fields into a MailUp message. The required format is JSON. You can design a flat structure or a more complex one, built with arrays or nested fields.
Your services must return HTTP 200 in case of success and 4xx or 5xx in case of errors. When an error repeatedly occurs while querying services for a recipient, MailUp does not send the email to that recipient.
 
 Click here to see an example of returned format ...

For example, the endpoint https://serene-shore-87032.herokuapp.com/content/products/myemail@example.com returns a JSON object like the one on the left. As the provider of the external service, you are supposed to know well the returned JSON object (field names, nested structures...). Hence, you have all you need to create a message on MailUp where the tag names arereferenced using the Liquid markup language


 

In some cases it may be useful to let the API decide if a specific recipient has to be excluded from mailing. Here the “DoNotSend” parameter comes in our rescue.

DoNotSend is a boolean parameter to be nested in a “Flow” object. Its default value is false, which means “send the message”. The use of HTTP errors like 4xx or 5xx to skip sending has a bad impact on overall performances, please use DoNotSend instead.

This is the right syntax to be used in the API response

"Flow": {
       "DoNotSend": true,
}

 

Enable personalization at different levels

By default, the advanced personalization is set at message level. You have to turn it on and configure an endpoint for each message requiring it. In case of more available endpoints, you can decide which one has to be used for a specific message.
In some cases, you may find useful to have personalization enabled by default on all the messages of a MailUp list. By doing so, every message of the list has the personalization automatically enabled, at list level, on a predefined endpoint. You can use MailUp API or ask to MailUp support team if you want to set the personalization at list level.


Performance related best practices

  • Avoid enabling the personalization to messages that do not require it. Querying an external endpoint may introduce delays
  • Make sure your endpoint is robust, scalable and optimized to respond quickly
  • Build your own logging system. MailUp does not inform you when the API calls fail due to errors on the external system


 

Setup advanced personalization using MailUp REST API

Get list of endpoints

DescriptionRetrieve the list of personalization endpoints configurations

HTTP Method

GET
URL
https://services.mailup.com/API/v1.1/Rest/ConsoleService.svc/Console/Personalization/Endpoints
JSON request (example)none
JSON response (example)
 Click here to expand...
{
    "IsPaginated": true,
    "Items": [
        {
            "CreationDate": "2017-12-04 16:51:34Z",
            "IdEndpoint": 25,
            "Label": "pippo",
            "Url": "http://pippo.pluto/"
        },
		...
        {
            "CreationDate": "2017-12-01 11:20:19Z",
            "IdEndpoint": 11,
            "Label": "My personalization",
            "Url": "https://www.mailup.com/personalization"
        }
    ],
    "PageNumber": 0,
    "PageSize": 20,
    "Skipped": 0,
    "TotalElementsCount": 11
}
Paging and filtering (example)

5 items per page, get first page (count starts from zero)

Retrieve an orderd list of the endpoint(s) using the clause orderby="idEndpoint desc". Parameter names can be retreived from the response body. Please note that filter matching is case sensitive.

NB: no filtering querystring parameter provided!

Get endpoint details by id

DescriptionRetrieve the personalization endpoint configuration details

HTTP Method

GET
URL
https://services.mailup.com/API/v1.1/Rest/ConsoleService.svc/Console/Personalization/Endpoints/{id_endpoint}
JSON request (example)none
JSON response (example)
 Click here to expand...
{
    "CreationDate": "2017-12-01 11:20:19Z",
    "IdEndpoint": 11,
    "Label": "My personalization",
    "Url": "https://www.mailup.com/personalization",
    "Credentials": {
        "Password": "****",
        "Username": "test"
    },
    "Headers": [],
    "Parameters": [
        {
            "Field": "[field1]",
            "FieldTestValue": "Giancarlo",
            "Name": "name"
        }
    ],
    "Recipient": {
        "Field": "[email]",
        "FieldTestValue": "test@example.com"
    },
    "UpdateDate": "2017-12-01 11:25:37Z"
}
Paging and filtering (example)none

Create an endpoint

 What to know before start creating endpoints...
Does your service need a Basic authentication?Provide Username and Password using Credentials field.
Does your service need specific headers?Provide key-value data using Headers field.
Does your service get the recipient using email or mobile number from the url?

You can use Recipient field, providing one of theses placeholders:

  • [email]
  • [mobilenumber]
  • [fieldX] where X represent the dynamic content field unique identifier
Does your service get the recipient using data from the querystring?

You can use Parameters field, providing one of these placeholders:

  • [email]
  • [mobilenumber]
  • [idconsole]
  • [idlist]
  • [idnl]
  • [fieldX] where X represent the dynamic content field unique identifier
DescriptionCreate a personalization endpoint configuration

HTTP Method

POST
URL
https://services.mailup.com/API/v1.1/Rest/ConsoleService.svc/Console/Personalization/Endpoints
JSON request (example)
 How to create an endpoint...
Request body
{
	"Label":"Test",
	"Url": "https://www.mailup.com/personalization"
}
HTTP Request:
 GET https://www.mailup.com/personalization
 How to create an endpoint with credentials...
Request body:
{
	"Label":"Test",
	"Url": "https://www.mailup.com/personalization",
	"Credentials": {
		"Username": "test",
		"Password": "test"
	}
}
HTTP Request:
GET https://www.mailup.com/personalization
Authentication: Basic dGVzdDp0ZXN0
 How to create an endpoint with recipient definition...
Recipient's email definition request body:
 {
	"Label":"Test",
	"Url": "https://www.mailup.com/personalization",
	"Credentials": {
		"Username": "test",
		"Password": "test"
	},
	"Recipient": {
		"Field":"[email]",
		"FieldTestValue":"test@example.com"
	}
}
HTTP Request:
GET https://www.mailup.com/personalization/[email]
Authentication: Basic dGVzdDp0ZXN0
Recipient's phone number definition request body:
{
	"Label":"Test",
	"Url": "https://www.mailup.com/personalization",
	"Credentials": {
		"Username": "test",
		"Password": "test"
	},
	"Recipient": {
		"Field":"[mobilenumber]",
		"FieldTestValue":"1234567890"
	}
}
HTTP Request:
GET https://www.mailup.com/personalization/[mobilenumber]
Authentication: Basic dGVzdDp0ZXN0
 How to create an endpoint with headers...
Request body:
{
	"Label":"Test",
	"Url": "https://www.mailup.com/personalization",
	"Credentials": {
		"Username": "test",
		"Password": "test"
	},
	"Recipient": {
		"Field":"[email]",
		"FieldTestValue":"test@example.com"
	},
	"Headers": [{
		"Key": "From",
		"Value": "personalization@example.com"
	}]
}
HTTP Request:
GET https://www.mailup.com/personalization/[email]
Authentication: Basic dGVzdDp0ZXN0
From: personalization@example.com
 How to create an endpoint with querystring parameters...
Request body:
 {
	"Label":"Test",
	"Url": "https://www.mailup.com/personalization",
	"Credentials": {
		"Username": "test",
		"Password": "test"
	},
	"Recipient": {
		"Field":"[email]",
		"FieldTestValue":"test@example.com"
	},
	"Headers": [{
		"Key": "From",
		"Value": "personalization@example.com"
	}],
	"Parameters": [{
		"Name": "idconsole",
		"Field": "[idconsole]",
		"FieldTestValue": "1234"
	},{
		"Name": "const",
		"Field": "1234",
		"FieldTestValue": "1234"
	}]
}
HTTP Request:
GET https://www.mailup.com/personalization/[email]?idconsole=[idconsole]&const=1234
Authentication: Basic dGVzdDp0ZXN0
From: personalization@example.com
JSON response (example)
 Click here to expand...
{
    "CreationDate": "2017-12-03 11:20:19Z",
    "IdEndpoint": 12,
    "Label": "My personalization",
    "Url": "https://www.mailup.com/personalization",
    "Credentials": {
        "Password": "",
        "Username": ""
    },
    "Headers": [],
    "Parameters": [
        {
            "Name":"IdNl",
			"Field":"[idnl]",
			"FieldTestValue":"123"
        }
    ],
    "Recipient": {
        "Field":"[email]",
		"FieldTestValue": "test@example.com"
    },
    "UpdateDate": "2017-12-03 11:25:37Z"
}
Paging and filtering (example)none

Update an endpoint

DescriptionUpdate a personalization endpoint configuration

HTTP Method

PUT
URL
https://services.mailup.com/API/v1.1/Rest/ConsoleService.svc/Console/Personalization/Endpoints/{id_endpoint}
JSON request (example)
 Click here to expand...
{
	"Label":"Test",
	"Url": "https://www.mailup.com/personalization",
	"Recipient": {
		"Field":"[email]",
		"FieldTestValue": "test@example.com"
	},
	"Parameters": [{
		"Name":"IdNl",
		"Field":"[idnl]",
		"FieldTestValue":"123"
	}, {
		"Name":"IdConsole",
		"Field":"[idconsole]",
		"FieldTestValue":"987"
	}],
	"Headers": [{
		"Key": "From",
		"Value": "marketing@example.com"
	}],
	"Credentials": {
        "Password": "test",
        "Username": "test"
    },
    "UpdateDate": "2017-12-03 11:25:37Z"
}
JSON response (example)
 Click here to expand...
{
	"CreationDate": "2017-12-03 11:20:19Z",
    "IdEndpoint": 12,
	"Label":"Test",
	"Url": "https://www.mailup.com/personalization",
	"Recipient": {
		"Field":"[email]",
		"FieldTestValue": "test@example.com"
	},
	"Parameters": [{
		"Name":"IdNl",
		"Field":"[idnl]",
		"FieldTestValue":"123"
	}, {
		"Name":"IdConsole",
		"Field":"[idconsole]",
		"FieldTestValue":"987"
	}],
	"Headers": [{
		"Key": "From",
		"Value": "marketing@example.com"
	}],
	"Credentials": {
        "Password": "test",
        "Username": "test"
    },
    "UpdateDate": "2017-12-04 17:15:20Z"
}
Paging and filtering (example)none

Get endpoints of a list

DescriptionGet personalization endpoints related to a list

HTTP Method

GET
URL
https://services.mailup.com/API/v1.1/Rest/ConsoleService.svc/Console/Personalization/Endpoints/List/{id_list}
JSON request (example)

none

JSON response (example)
 Click here to expand...
[
    {
        "CreationDate": "2017-12-04 11:58:39Z",
        "IdEndpoint": 23,
        "Label": "Test",
        "Url": "https://www.mailup.com/personalization"
    }
]
Paging and filtering (example)none

Set endpoint to list

DescriptionSet a personalization endpoint to a list

HTTP Method

POST
URL
https://services.mailup.com/API/v1.1/Rest/ConsoleService.svc/Console/Personalization/Endpoints/{id_endpoint}/List/{id_list}
JSON request (example)

none

JSON response (example)

none

Paging and filtering (example)none

Remove endpoint from list

DescriptionRemove a personalization endpoint reference from a list

HTTP Method

DELETE
URL
https://services.mailup.com/API/v1.1/Rest/ConsoleService.svc/Console/Personalization/Endpoints/{id_endpoint}/List/{id_list}
JSON request (example)

none

JSON response (example)

none

Paging and filtering (example)none

Delete an endpoint

DescriptionRemove a personalization endpoint configuration

HTTP Method

DELETE
URL
https://services.mailup.com/API/v1.1/Rest/ConsoleService.svc/Console/Personalization/Endpoints/{id_endpoint}
JSON request (example)

none

JSON response (example)

none

Paging and filtering (example)none