Info |
---|
Personalization is an advanced feature and it is not enabled by default for every platform. Are you interested in? Would you like your newsletter provides contents keeping data from an external data source including conditional logic and loops? Please, contact MailUp API team for further information. |
The personalization engine allows to provide newsletters contents using Liquid template. If you can provide recipient-related JSON information via a web service, you could use this feature to personalize your newsletter. When MailUp will send your newsletter, it will call your web service and retrieve the personalized information per recipient. To reach a specified recipient the personalization engine will create an url that contains recipent-related data that you'll define creating a personalization endpoint configuration. So, let's create your first personalization endpoint!
This page provides you information about how to manage pensonalization's endpoints.
On this page:
Get list of endpoints
Description | Retrieve the list of personalization endpoints configurations |
---|
HTTP Method | GET |
---|
URL | Code Block |
---|
| https://services.mailup.com/API/v1.1/Rest/ConsoleService.svc/Console/Personalization/Endpoints |
|
---|
JSON request (example) | none |
---|
JSON response (example) | Expand |
---|
Code Block |
---|
{
"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 ordering filtering querystring parameter provided! |
---|
Get endpoint details by id
Description | Retrieve the personalization endpoint configuration details |
---|
HTTP Method | GET |
---|
URL | Code Block |
---|
| https://services.mailup.com/API/v1.1/Rest/ConsoleService.svc/ConsolePersonalization/Endpoints/{id_endpoint} |
|
---|
JSON request (example) | none |
---|
JSON response (example) | Expand |
---|
Code Block |
---|
{
"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 endpoint
...
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.
Template | Description | Example |
---|
MY_ENDPOINT_URL/EMAIL | query by email | https://personalization.mysite.com/product/john@example.com |
MY_ENDPOINT_URL/RECIPIENT_FIELD | query by a MailUp personal field, like firstname or ClientID | https://personalization.mysite.com/product/ID000111222 |
MY_ENDPOINT_URL/EMAIL?FIELD1=value,FIELD2=value | more 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 name | Description | Example |
---|
IdConsole | MailUp account ID | 59484 |
IdList | MailUp list ID | MailUp message ID |
groups | MailUp groups the recipient is matching in current mailing | 24,25,29 |
filters | MailUp filters the recipient is matching in current mailing | 10,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.
Expand |
---|
title | 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 Image Added | Image Added |
|
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
Code Block |
---|
"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
Description | Retrieve the list of personalization endpoints configurations |
---|
HTTP Method | GET |
---|
URL | Code Block |
---|
| https://services.mailup.com/API/v1.1/Rest/ConsoleService.svc/Console/Personalization/Endpoints |
|
---|
JSON request (example) | none |
---|
JSON response (example) | Expand |
---|
Code Block |
---|
{
"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
Description | Retrieve the personalization endpoint configuration details |
---|
HTTP Method | GET |
---|
URL | Code Block |
---|
| https://services.mailup.com/API/v1.1/Rest/ConsoleService.svc/Console/Personalization/Endpoints/{id_endpoint} |
|
---|
JSON request (example) | none |
---|
JSON response (example) | Expand |
---|
Code Block |
---|
{
"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
Expand |
---|
title | 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
|
---|
|
Description | Create a personalization endpoint configuration |
---|
HTTP Method | POST |
---|
URL | Code Block |
---|
| https://services.mailup.com/API/v1.1/Rest/ConsoleService.svc/ |
|
---|
...
Console/Personalization/Endpoints |
|
JSON request (example) | Expand |
---|
title | How to create an endpoint... |
---|
| Code Block |
---|
| {
"Label":"Test",
"Url": "https://www.mailup.com/personalization"
} |
Code Block |
---|
| GET https://www.mailup.com/personalization |
|
Expand |
---|
title | How to create an endpoint with credentials... |
---|
| Code Block |
---|
| {
"Label":"Test",
"Url": "https://www.mailup.com/personalization",
"Credentials": {
"Username": "test",
"Password": "test"
}
} |
Code Block |
---|
| GET https://www.mailup.com/personalization
Authentication: Basic dGVzdDp0ZXN0 |
|
Expand |
---|
title | How to create an endpoint with recipient definition... |
---|
| Code Block |
---|
title | 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"
}
} |
Code Block |
---|
| GET https://www.mailup.com/personalization/[email]
Authentication: Basic dGVzdDp0ZXN0 |
Code Block |
---|
title | 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"
}
} |
Code Block |
---|
| GET https://www.mailup.com/personalization/[mobilenumber]
Authentication: Basic dGVzdDp0ZXN0 |
|
Expand |
---|
title | How to create an endpoint with headers... |
---|
| Code Block |
---|
| {
"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"
}]
} |
Code Block |
---|
| GET https://www.mailup.com/personalization/[email]
Authentication: Basic dGVzdDp0ZXN0
From: personalization@example.com |
|
Expand |
---|
title | How to create an endpoint with querystring parameters... |
---|
| Code Block |
---|
| {
"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"
}]
} |
Code Block |
---|
| GET https://www.mailup.com/personalization/[email]?idconsole=[idconsole]&const=1234
Authentication: Basic dGVzdDp0ZXN0
From: personalization@example.com |
|
|
---|
JSON response (example) | Expand |
---|
Code Block |
---|
{
"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
Description | Update a personalization endpoint configuration |
---|
HTTP Method | PUT |
---|
URL | Code Block |
---|
| https://services.mailup.com/API/v1.1/Rest/ConsoleService.svc/Console/ |
|
---|
...
Personalization/Endpoints/{id_endpoint} |
|
JSON request (example) | Expand |
---|
Code Block |
---|
{
"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) | Expand |
---|
Code Block |
---|
{
"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
Description | Get personalization endpoints related to a list |
---|
HTTP Method | GET |
---|
URL | Code Block |
---|
| https://services.mailup.com/API/v1.1/Rest/ConsoleService.svc/ |
|
---|
...
Console/Personalization/Endpoints/List/{id_list} |
|
JSON request (example) | none |
---|
JSON response (example) | Expand |
---|
Code Block |
---|
[
{
"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
Description | Set a personalization endpoint to a list |
---|
HTTP Method | POST |
---|
URL | Code Block |
---|
| 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
Description | Remove a personalization endpoint reference from a list |
---|
HTTP Method | DELETE |
---|
URL | Code Block |
---|
| 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
Description | Remove a personalization endpoint configuration |
---|
HTTP Method | DELETE |
---|
URL | Code Block |
---|
| 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 |
---|