Integration options

Access to customer RSS feed(s)

In order for Piano ESP to gain access to new content you publish fully automatically, you must provide links to appropriate RSS feeds with data to be used for future mailings to your user base. Multiple feeds can be grouped and targeted to different segments of users. Details should be discussed with your Piano representative.

Piano ESP Supports RSS, Atom, and RDF feeds. ESP can access feeds with restricted access (basic/digest HTTP auth) or by accessing feeds from whitelisted ESP IP addresses on your side.

Installation of integration code

The only mandatory action in the integration process is the insertion of the Piano ESP Integration Code on every page (or a defined subset of pages) of your site. This allows for automatic user behavior analysis and user reading preferences tracking.

The integration code has the following structure:

<script type="text/javascript">
;!function(){
    window.PianoESPConfig = {
        id: XX
    }
    var e=document.createElement("script");e.setAttribute("id","pnesplucidsdksel"),e.type="text/javascript",e.src="//sandbox-api-esp.piano.io/public/sdk/v04/sdk.js?v="+(localStorage&&localStorage.lucidsdkver||"xxx"),e.async=!0,document.getElementsByTagName("script")[0].parentNode.appendChild(e);
}();
</script>

It should be placed at the very end of your page code. It is loaded in an asynchronous manner and generally has no or insignificant influence on page load time. If you have specific requirements on page load time, we support time-shifted delayed loading.

Additionally, in order to display embedded opt-in widgets in the proper location on-page, a corresponding placeholder should be specified for each such widget. The placeholder code looks like this:

Modal widgets do not require placeholders to be specified.

Note: Currently, both the Piano ESP Integration Code and embedded widget placeholders are generated and displayed in the Piano ESP Dashboard. Therefore, it’s a simple copy-paste operation where no manual substitution of <integration.id> or <widget_uid> are required.

Acknowledging Piano ESP SDK about user@email.address

Under certain integration scenarios, you may not want to display any Piano ESP widgets on your website. At the same time, you may have information about current visitors’ email addresses which might be passed to Piano ESP in order to perform accurate behavioral tracking of a visitor. In this case, you can pass visitors’ email addresses right from a web page, omitting any user input. To do so, execute the following JavaScript:

1

window.PianoESP && "function" == typeof window.PianoESP.handleUserEmail && window.PianoESP.handleUserEmail ( 'email@address' );

Once executed, Piano ESP is aware of the current visitor and is able to track their visiting history in conjunction with their email address.

Subscribers management

To manage ESP subscriptions, you can also utilize our API and make calls to the respective endpoints via an HTTP FORM POST.

ESP offers two different environments to the public: sandbox and production. The base URLs for the production environment API are:

https://api-esp.piano.io (America)

https://api-esp-eu.piano.io (Europe)

https://api-esp-ap.piano.io (Asia-Pacific)

The base URL for the sandbox environment API is:

https://sandbox-api-esp.piano.io

Please note, that in the below examples of API calls the base URL for the US Production environment is used. In case your application is located in any other regional dashboard, you would need to adjust the call accordingly and use the relevant base URL.

Submission of new subscribers to ESP

If you decide to provide Piano ESP with new subscribers using your own subscription form (or any other automated or manual process) rather than using the Piano ESP opt-in widget, you must call our API via an HTTP FORM POST:

http(s)://api-esp.piano.io/tracker/securesub?api_key=<api_key>.

The set header for this call is Content-Type: application/x-www-form-urlencoded, and parameters passed as:

1

2

email: "<reader_email>"
mlids: "idX, idY, ..."

mlids - list of mailing lists IDs

api_key - a unique identifier used to authenticate a user. To get the API key please visit the Integration tab of your Piano ESP dashboard or contact Piano Support

Alternatively, JSON POST to http(s)://api-esp.piano.io/tracker/securesub?api_key=<api_key>

with set headers:

1

2

3

4

5

6

Content-Type: application/json
JSON body: 
{
    "email": "<reader_email>",
    "mlids": [ idX, idY, ... ]
}

mlids - the list of mailing lists IDs

api_key - a unique identifier used to authenticate a user. To get the API key please visit the Integration tab of your Piano ESP dashboard or contact Piano Support

Submission of unsubscribed users to ESP

If you would like to provide unsubscribed users using your own unsubscription form (or any other implemented automated or manual process) rather than using the Piano ESP Unsubscription Link located in every email distributed by Piano ESP, the following API call has to be performed to remove existing subscribers:

HTTP FORM DELETE to http(s)://api-esp.piano.io/tracker/securesub?api_key=<api_key>

with set headers: Content-Type: application/x-www-form-urlencoded, with form fields to be submitted:

1

2

email: "<reader_email>"
mlids: "idX, idY, ..."

mlids - list of mailing lists IDs

Alternatively, JSON DELETE to

http(s)://api-esp.piano.io/tracker/securesub?api_key=<api_key>

with set headers:

1

2

3

4

5

6

7

Content-Type: application/json
JSON body: 
{
    "email": "<reader_email>",
    "mlids": [ idX, idY, ... ]
}

mlids - the list of mailing lists IDs
api_key - a unique identifier used to authenticate a user. To get the API key please visit the Integration tab of your Piano ESP dashboard or contact Piano Support

Notification of new subscriptions (callback)

You can be notified automatically by receiving HTTP event(s) (callback requests) in JSON format regarding new subscribers to your mailing list(s).

The HTTP request may be performed on any number of HTTP(s) endpoints with the following JSON body:

1

2

3

4

5

{
 "email": "<reader_email>",
 "sqid": <squad_id>,
 "action": <action>
}

<squad_id> - is the mailing list ID

<action> - for new subscriptions, this will have the value user_added

The HTTP method used for each endpoint for receiving notifications can be chosen arbitrarily and should be provided to Piano ESP for the corresponding setup.

To receive the callbacks, establish an HTTPS endpoint capable of receiving the JSON object. To register your endpoint in ESP, kindly reach out to your Account Manager or contact support@piano.io.

Notification of unsubscriptions (callback)

You can be notified automatically by receiving HTTP event(s) (callback requests) in JSON format regarding user unsubscriptions from your mailing list(s) handled through the Piano ESP unsubscribe link.

The HTTP request may be performed on any number of HTTP(s) endpoints with the following JSON body:

1

2

3

4

5

{
 "email": "<reader_email>",
 "sqid": <squad_id>,
 "action": <action>
}

<squad_id> - is the mailing list ID

<action> - for new unsubscriptions, this will have the value user_removed

The HTTP method used for each endpoint for receiving notifications can be chosen arbitrarily and should be provided to Piano ESP for the corresponding setup.

Please note, that a user's unsubscription from the campaign means simultaneous user unsubscription from all mailing lists attached to a certain campaign.

To receive the callbacks, establish an HTTPS endpoint capable of receiving the JSON object. To register your endpoint in ESP, kindly reach out to your Account Manager or contact support@piano.io.

Subscription status query

At any point, you can query Piano ESP regarding the subscription status of any user within Piano ESP using the following HTTP GET method:

http(s)://api-esp.piano.io/tracker/securesub/email/<email>/ml/<mailing_list_id>?api_key=<api_key>

The returned HTTP code indicates their subscription status:

// the user is subscribed
HTTP 200: <email> is subscribed to mailing list ID

// the user is and was not subscribed at any time
HTTP 404: <email> is not subscribed to mailing list ID

//  the user is not subscribed, because they were deactivated via API, dashboard or email
HTTP 404: <email> is not subscribed to mailing list ID (Reason: subscription status "0")

// the user is not subscribed, because they have received a hard bounce (invalid email)
HTTP 404: <email> is not subscribed to mailing list ID (Reason: subscription status "-2")

// the user is not subscribed, because they have marked the email as spam
HTTP 404: <email> is not subscribed to mailing list ID (Reason: subscription status "-3")

// the user is not subscribed, because because their email address was blacklisted by ESP
HTTP 404: <email> is not subscribed to mailing list ID (Reason: subscription status "-9")

// see HTTP logs or contact Piano support for further advice
HTTP 500: server error encountered

Get customer’s feedback

At any point, you can query Piano ESP regarding the unsubscribe feedback of any user using the following HTTP GET method:

/publicpages/feedback/<PUB_ID>?event=<event_type>&campid=<camp_id>&sbid=<sb_id>&userid=<user_id>&date_start=<date_start>&date_end=<date_end>&api_key=<api_key>

Path parameters:

PUB_ID - REQUIRED

integer

ID of the Publisher

Query parameters:

event_type - REQUIRED	string	Possible values: unsubscribe \| faq
camp_id - OPTIONAL	integer	ESP Campaign ID
sb_id - OPTIONAL	integer	Sendbucket ID
user_id - OPTIONAL	integer	The ESP User ID
<date_start> - REQUIRED	YYYY-MM-DD	start date of a period
<date_end> - REQUIRED	YYYY-MM-DD	end date of a period
API_KEY - REQUIRED	string	API_KEY of publisher

The returned response contains the text of the user's unsubscribe feedback (if provided). For example:

[
    {
        "added": "2022-12-07T07:41:43.765Z",
        "publisherId": 2,
        "campaignId": 396,
        "sbId": -1,
        "userId": 7,
        "reasons": [
            -3
        ],
        "freeFeedback": "Some message"
    }
  ]

GDPR data deletion via email

If needed or requested by an end user, you have the ability to delete user data in compliance with GDPR using the following HTTP DELETE method:

/userdata/gdpr/data/email/<email>/<PUB_ID>

Path parameters:

PUB_ID - REQUIRED	integer	ID of the Publisher
email - REQUIRED	integer	The email of the user whose GDPR data should be deleted

Query parameters:

API_KEY - REQUIRED

string

API_KEY of publisher

The returned response contains the information about the data deletion. For example:

[{
        "2": false,
        "3": {
            "recordsets": [],
            "output": {},
            "rowsAffected": [
                10
            ]
        },
        "4": {
            "recordsets": [],
            "output": {},
            "rowsAffected": [
                7
            ]
        },
        "5": false,
        "6": false
    },
    {
        "0": false
    },
    {
        "1": false,
        "7": false,
        "8": false,
        "9": [{
            "took": 324,
            "timed_out": false,
            "total": 12,
            "deleted": 12,
            "batches": 1,
            &hellip;
        }],
        "10": [{
            "took": 66,
            "timed_out": false,
            "total": 1,
            "deleted": 1,
            "batches": 1,
            &hellip;
        }],
        "11": false,
        "12": false,
        "13": false,
        "14": false,
        "15": false,
        "16": [{
            "took": 4383,
            "timed_out": false,
            "total": 87,
            "deleted": 87,
            "batches": 1,
            &hellip;
        }],
        "17": false,
        "18": false,
        "19": false,
        "20": false
    }
]

Query parameters:

<api_key> - REQUIRED

string

API_KEY of publisher

Push List Statistics via API

Full Push list statistics by date

The below endpoint allows getting full statistics on push list(s) within a selected date range and for the entire existence of the push list.

HTTP [GET] to:

/stats/push/squads/full/<sqids>?date_start=<date_start>&date_end=<date_end>&api_key=<api_key>

Will return a response:

{
    "permissionPromt": {
        "byDate": [
            {
                "key": "prompt_was_accepted",
                "values": [
                    {
                        "x": 1603843200000,
                        "y": 0
                    },
                    {
                        "x": 1603929600000,
                        "y": 0
                    }
                ]
            },
            {
                "key": "prompt_was_closed",
                "values": [
                    {
                        "x": 1603843200000,
                        "y": 96
                    },
                    {
                        "x": 1603929600000,
                        "y": 80
                    }
                ]
            },
            {
                "key": "prompt_was_declined",
                "values": [
                    {
                        "x": 1603843200000,
                        "y": 0
                    },
                    {
                        "x": 1603929600000,
                        "y": 0
                    }
                ]
            },
            {
                "key": "prompt_was_shown",
                "values": [
                    {
                        "x": 1603843200000,
                        "y": 0
                    },
                    {
                        "x": 1603929600000,
                        "y": 0
                    }
                ]
            }
        ],
        "totalsForSelectedTime": {
            "prompt_was_accepted": 0,
            "prompt_was_closed": 176,
            "prompt_was_declined": 0,
            "prompt_was_shown": 0
        }
    },
    "subscriptionEvents": {
        "byDate": [
            {
                "key": "bad_subscription",
                "values": [
                    {
                        "x": 1603843200000,
                        "y": 69
                    },
                    {
                        "x": 1603929600000,
                        "y": 84
                    }
                ]
            },
            {
                "key": "old_subscription_was_imported",
                "values": [
                    {
                        "x": 1603843200000,
                        "y": 7
                    },
                    {
                        "x": 1603929600000,
                        "y": 3
                    }
                ]
            },
            {
                "key": "subscription_was_renewed",
                "values": [
                    {
                        "x": 1603843200000,
                        "y": 0
                    },
                    {
                        "x": 1603929600000,
                        "y": 0
                    }
                ]
            },
            {
                "key": "subscribed",
                "values": [
                    {
                        "x": 1603843200000,
                        "y": 2484
                    },
                    {
                        "x": 1603929600000,
                        "y": 2674
                    }
                ]
            }
        ],
        "totalsForSelectedTime": {
            "bad_subscription": 153,
            "old_subscription_was_imported": 10,
            "subscription_was_renewed": 0,
            "subscribed": 5158
        }
    },
    "performanceByDevice": {
        ...
        "subscribed": {
            "byDate": [
                {
                    "key": "mobile",
                    "values": [
                        ...
                        {
                            "x": 1603929600000,
                            "y": 84
                        }
                        ...
                    ]
                },
            ],
            "totalsForSelectedTime": {
                ...
                "mobile": 153,
                ...
            }
        },
        ...
    },
    "performanceByBrowser": {
        ...
        "subscribed": {
            "byDate": [
                {
                    "key": "chrome",
                    "values": [
                        ...
                        {
                            "x": 1603929600000,
                            "y": 84
                        }
                        ...
                    ]
                },
            ],
            "totalsForSelectedTime": {
                ...
                "chrome": 153,
                ...
            }
        },
        ...
    },
    "performanceByLocation": {
        ...
        "subscribed": {
            "byDate": [
                {
                    "key": "ua",
                    "values": [
                        ...
                        {
                            "x": 1603929600000,
                            "y": 84
                        }
                        ...
                    ]
                },
            ],
            "totalsForSelectedTime": {
                ...
                "ua": 153,
                ...
            }
        },
        ...
    },
    "performanceLocationByDevice": {
        ...
        "mobile": {
            ...
            "subscribed": {
                "byDate": [
                    {
                        "key": "ua",
                        "values": [
                            ...
                            {
                                "x": 1603929600000,
                                "y": 84
                            }
                            ...
                        ]
                    },
                ],
                "totalsForSelectedTime": {
                    ...
                    "ua": 153,
                    ...
                }
            },
            ...
        }
        ...
    }
}

Path Parameters:

<sqids> - REQUIRED

string

a comma-separated list of Push List IDs list (e.g.: 5,9,34)

ID of push list(s).

Note: if you indicate several IDs you will receive aggregated statistics for all listed push lists (not separately for every push list)

Query parameters:

<date_start> - REQUIRED	YYYY-MM-DD	start date of a period
<date_end> - REQUIRED	YYYY-MM-DD	end date of a period
<api_key> - REQUIRED	string	API_KEY of publisher

Images:

Performance testing article

Table of Contents

Integration options

Access to customer RSS feed(s)

Installation of integration code

Acknowledging Piano ESP SDK about user@email.address

Subscribers management

Submission of new subscribers to ESP

Submission of unsubscribed users to ESP

Notification of new subscriptions (callback)

Notification of unsubscriptions (callback)

Subscription status query

Get customer’s feedback

Path parameters:

Query parameters:

GDPR data deletion via email

Path parameters:

Query parameters:

Query parameters:

Push List Statistics via API

Full Push list statistics by date

Path Parameters:

Query parameters:

Articles in this section