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 are required.
ESP SDK Setup Guide
Welcome to the guide for integrating the ESP SDK into your website. It provides comprehensive instructions for integrating the SDK with or without using a Data Layer and adapting to various user consent scenarios, ensuring compliance with privacy laws such as GDPR and ePrivacy.
This setup guide complements the Consent Management for Client Storage (Cookies).
Consent Management: Modes and Purposes
The Consent Management module ensures compliance by default. It categorizes trackers into four consent modes:
-
Optional: ‘opt-in’
-
Essential: ‘essential’
-
Mandatory: ‘opt-out’
-
Reject all: ‘custom’
In ESP SDK, all cookies are mandatory. The custom mode is configured to reject all user-related cookies, refraining from tracking page visits and user actions. Google Analytics is activated when ‘essential’ or ‘opt-in’ modes are selected.
Products are distributed by purpose, with the ESP product falling under the Personal Relationship (PR) category by default:
| Personal Relationship (PR) | ID, Management + Billing, ESP |
Enabling Consent Management on Your Website
To use Consent Management, declare the requireConsent variable, implement showConsentModal method and invoke window.pdl.setConsent('PR', selectedMode) with consent mode selected by user. Please note, checkConsent function is added as ‘onload’ event handler and called after SDK is loaded (e.onload = checkConsent).
Example:
<script>
;!function() {
window.pdl = window.pdl || {};
window.pdl.requireConsent = 'v2';
window.PianoESPConfig = {
// Replace INTEGRATION_ID with your publisher integration ID number
id: INTEGRATION_ID
};
function checkConsent() {
if (window?.pdl?.requireConsent) {
// showConsentModal method shoud be implemented on publisher side
window.showConsentModal((selectedMode) => {
window.pdl.setConsent('PR', selectedMode);
});
}
}
var e = document.createElement("script");
e.setAttribute("id","pnesplucidsdksel");
e.type="text/javascript";
// Replace ENVIRONMENT with the corresponding client's environment, for example: sandbox-api-esp.piano.io
e.src="https://ENVIRONMENT/public/sdk/vx/sdk.js?v=" + (localStorage&&localStorage.lucidsdkver||"xxx") + '&i=' + window.PianoESPConfig.id;
e.async=true;
e.onload = checkConsent;
document.getElementsByTagName("script")[0].parentNode.appendChild(e);
}();
</script>
To verify the Consent object, use the API: window?.pdl?.getConsent();. If consents are set, it returns the full map of {purpose:mode:products}; otherwise, it returns null.
Altering the Default Purposes
If the default purposes do not align with client’s cookie banner, it can be customized:
window.pdl.consent = {};
window.pdl.consent.defaultPurposes = { esp: 'ESP' };
In the example above, ‘ESP’ is moved to a different purpose, removing it from the ‘PR’ purpose enabling to set consent mode given by user to ‘ESP’ purpose only:
window.pdl.setConsent('ESP', selectedMode);
ESP SDK Setup Without Consent Management
In regions where user consent is unnecessary, the setup can omit the requireConsent variable initialization. In this case visitor and their actions will be tracked, analytics will be attached and all cookies will be set without relying on the user consent.
In case any questions arise, feel free to contact our Support team for assistance during integration.
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:
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.
API keys are not interchangeable between environments or regions. Each Site has its own key, and sandbox and production keys for the same Site are distinct. Confirm you are using the matching key for the host you are calling.
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=.
The set header for this call is Content-Type: application/x-www-form-urlencoded, and parameters passed as:
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 Setup → Integration (tab) of your Piano ESP dashboard or contact Piano Support.
mlids Formatting Rules
The mlids parameter must be formatted differently depending on the request's Content-Type:
-
application/json—mlidsis a JSON array of integers, no quotes around the integers:{ "email": "reader@example.com", "mlids": [5628, 5629] } -
application/x-www-form-urlencoded—mlidsis a comma-separated string, no spaces:email=reader%40example.com&mlids=5628,5629
The common failure mode is an HTTP client that serializes an array into form parameters as mlids[0]=5628&mlids[1]=5629. ESP does not accept that shape and returns 400 Bad Request.
Also verify that the mlids exist in the environment you are calling against. IDs from the production dashboard will not work against sandbox, and vice versa.
Alternatively, JSON POST to http(s)://api-esp.piano.io/tracker/securesub?api_key=
with set headers:
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 Setup → Integration (tab) of your Piano ESP dashboard or contact Piano Support.
If you've never generated an API key before, contact Piano Support to set one up for your site. The same goes if you ever need to rotate your key, just reach out to Support.
Keep in mind that creating a new API key turns off the old one right away. There's no transition period where both keys work, so the switch is immediate.
Before you replace your key:
-
Make a list of everywhere the current key is used: integrations, scripts, scheduled jobs, and any saved settings.
-
Get ready to update all of them at roughly the same time.
-
Ask Support to generate the new key and update each place that uses it.
Once the old key is replaced, anything still using it will stop working immediately and you'll see an error like query / api_key failed validation.
Finally, treat your API key like a password. Only use it in trusted, behind-the-scenes systems, and never put it directly in code that runs in someone's browser or in web addresses that could show up in logs or browsing history.
Disposable / blacklisted addresses
When you make a subscribe call for an address that the ESP identifies as coming from a disposable or temporary email service (such as Mailinator), the address is silently rejected. The request may come back as successful, but the user's status on the target list is immediately set to -9 (blacklisted), and no emails will be delivered to them.
This blacklisting is intentional. Disposable addresses are a common tool for faking signups, and sending to them damages your sender reputation.
If you think a legitimate address has been flagged by mistake, reach out to Piano Support with the specific email address and an explanation of how it was collected. Avoid retrying the subscribe call automatically, as it will simply produce the same result.
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=
with set headers: Content-Type: application/x-www-form-urlencoded, with form fields to be submitted:
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=
with set headers:
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 Setup → 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:
{
"email": "<reader_email>",
"sqid": <squad_id>,
"action": <action>
}
- is the mailing list ID
- 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.
ESP supports one callback URL per Site, which receives both subscription and unsubscription events. If you need to forward events to multiple systems, use your own intermediary service as the configured callback endpoint.
To prevent delivery to an unavailable endpoint, ESP automatically suspends failing callback URLs. Please note that events that occurred before a new URL was configured cannot be resent automatically.
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:
{
"email": "<reader_email>",
"sqid": <squad_id>,
"action": <action>
}
- is the mailing list ID
- 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//ml/?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 the user's record was deleted HTTP 404: <email> is not subscribed to mailing list ID (Reason: subscription status "-1") // 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 they failed Mailgun verification HTTP 404: <email> is not subscribed to mailing list ID (Reason: subscription status "-8") // 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
Users in status -2 (hard bounce), -3 (spam complaint), or -9 (blacklisted) cannot be resubscribed through POST /tracker/securesub. Calling the subscribe endpoint for these users either returns an error or leaves the status unchanged.
To resubscribe users whose email addresses have been blocked due to bounce or complaint statuses, submit a request to Piano Support.
Include the following information in your ticket:
-
The email addresses that should be resubscribed.
-
The date range during which the delivery errors occurred.
-
A brief explanation of why the users should be resubscribed (for example, the delivery issue has been resolved or the status was applied in error).
Piano Support will review the request and remove the relevant statuses from the affected email addresses. Once the changes have been made, verify that the affected users are successfully receiving newsletter emails again.
Get customer’s feedback
You can query Piano ESP regarding the unsubscribe feedback of any user using the following HTTP GET method:
/publicpages/feedback/?event=&campid=&sbid=&userid=&date_start=&date_end=&api_key=
Path parameters:
|
PUB_ID - REQUIRED |
integer |
ID of the Publisher |
Query parameters:
|
event_type - REQUIRED |
string |
Possible values: |
|
camp_id - OPTIONAL |
integer |
ESP Campaign ID |
|
sb_id - OPTIONAL |
integer |
Sendbucket ID |
|
user_id - OPTIONAL |
integer |
The ESP User ID |
|
- REQUIRED |
YYYY-MM-DD |
start date of a period |
|
- 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"
}
]
Please note, that the number of returned documents is limited by the selected period, and the maximum is 1000000.
Statistics can only be retrieved for a maximum period of 90 days. Requests where date_end is more than 90 days after date_start return HTTP 400. For longer reporting periods, loop in 90-day chunks and concatenate the results client-side.
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//
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,
…
}],
"10": [{
"took": 66,
"timed_out": false,
"total": 1,
"deleted": 1,
"batches": 1,
…
}],
"11": false,
"12": false,
"13": false,
"14": false,
"15": false,
"16": [{
"took": 4383,
"timed_out": false,
"total": 87,
"deleted": 87,
"batches": 1,
…
}],
"17": false,
"18": false,
"19": false,
"20": false
}
]
Common API error codes
|
Response |
Cause |
Remediation |
|---|---|---|
|
|
Wrong API key — most often a non-ESP token (Composer, Management + Billing, or Identity Management) used against an ESP endpoint. |
Use the key from Setup → Integrations in the ESP dashboard. Each ESP Site and environment has its own key. |
|
|
API key does not match the endpoint, the environment, or the Site. |
Confirm you are using the ESP key for the correct environment (sandbox vs. production) and the correct Site. Stale-after-rotation keys produce the same error. |
|
|
Key/environment mismatch — typically the production key against a sandbox URL or vice versa. |
Verify both the key and the base URL match the same environment. |
|
|
One or more |
Verify |
|
|
|
Validate the body shape. For JSON, |
|
|
Credentials reached the endpoint but are wrong, or a required body parameter is missing. On |
Verify the API key, then check that all required body parameters are present. |
|
|
Either the API URL is wrong for the region (for example, |
Confirm the region of the base URL matches the dashboard region, then confirm with an admin that the user holding the key has the required permissions. |
|
|
The user is not currently subscribed. Read the response body for the |
Use the subscription-status code table to determine the underlying state. A |
|
|
The request used |
Issue an |
|
|
Request rate exceeded ESP's threshold. |
Back off, cache responses, and reduce concurrency. |
|
Cloudflare 403 / security challenge |
The request originated from a browser context that Cloudflare flagged as suspicious — typical for JavaScript subscription forms. |
Reduce the Cloudflare Security Level for the rule covering the origin, verify the rule allows the ESP endpoint, and reproduce in a REST client (Insomnia, Postman) to confirm the block is on the Cloudflare side. Where supported, allow-list the Piano ESP host in your Cloudflare configuration. |
|
|
Server-side error. |
Check logs, retry with exponential backoff, and contact Piano Support if the error persists with the request ID and timestamp. |
Server-side user tracking
This section describes API for tracking users via API. This is useful if precise control over exposed information is required for non-browser environments, browser environments with runtime (e.g. javascript) limitations, etc.
Submission of new page visits to Piano ESP
If you would like to provide Piano ESP with new page visits using your own tracking mechanism rather than using Piano ESP internal tracking, the following API call has to be performed to record/add each page visit:
HTTP POST to http(s)://api-esp.piano.io/tracker/secure/visit/?api_key=&src=&visitor=
where is a URL-encoded page URL (should be accessible by Piano ESP for parsing) and is a visitor ID string (unique value denoting a visitor, see below).
Visitor ID is a unique value per reader, so you should use a consistent visitor ID for each reader to the extent possible. Visitor ID is generated during the user's first tracking request lacking this parameter and will be contained in the response. We highly recommend that you use the previously generated visitor ID for subsequent requests.
Submission of "Visitor-subscriber" relation to Piano ESP
Submitting new page visits to Piano ESP as described above uses an abstract (anonymous) visitor ID to reference users. At some point, it will be necessary to link one or more visitor IDs to actual user email(s), in order to let Piano ESP perform recommended content distributions (which ultimately uses email addresses).
For this, the following API call has to be performed to establish such a Visitor-Subscriber relation:
HTTP PUT to http(s)://api-esp.piano.io/tracker/secure/impersonate/?api_key=&email=&visitor=
where is the URL-encoded subscriber’s email address, and is the visitor ID string.
Subscriber's custom user data values manipulation
Custom user data values manipulation allows automated manipulation of custom values attributable to each subscriber (also known as "merge fields," "merge variables," "custom data," etc.).
In order to be able to successfully manipulate custom user data values, you must first configure corresponding custom merge fields for each site where custom user data shall be used. Attempting to reference "non-existing" (unknown / unconfigured / etc.) user merge fields in the APIs listed below will result in API invocation errors.
Additionally, each user (subscriber) referenced in the APIs listed below must be already present in one or more mailing lists. Attempts to manipulate custom user data for a "non-existing" (unknown / deleted) user will result in API invocation errors.
Set the user's merge fields values
This method allows setting values of up to 16 different custom user merge fields for up to 16 users in one invocation.
HTTP [POST] to:
/userdata/umfval/pub//set?[api_key=]
with the following JSON body:
[ {
"user": <id> / <email>, // user id / email
"umf": <id> / <name>, // umf id / name
"value": <value> // umf value to set },
{ ... }
]
will return HTTP code 200 upon success and the corresponding error code and message otherwise.
The JSON body array consists of a list of objects of which each object is a - pair.
Please note, this API accepts users as user IDs OR user EMAILs and user merge fields as user merge field IDs OR user merge field NAMEs interchangeably. Whichever referencing is used, the same identifier will be returned in the results.
(also known as ) should be retrieved from the Piano ESP dashboard or integration code. This value uniquely represents a Site in the ESP dashboard.
Deleting custom user data values (individual subscribers)
This method allows you to delete values of up to 16 different custom user merge fields for up to 16 users in one invocation.
HTTP [POST] to:
http(s)://api-esp.piano.io/userdata/umfval/pub//delete?api_key=
with the following JSON body:
{
"user": <user_id> | "user_email" | [ <user_id>, "user_email" ],
"umf": <umf_id> | "umf_name" | [ <umf_id>, "umf_name" ]
}
will return HTTP code 200 upon success and the corresponding error code and message otherwise.
The API accepts users as user IDs, user EMAILs, and user merge fields as user merge field IDs and user merge field NAMEs interchangeably.
(also known as ) should be retrieved from the Piano ESP dashboard or integration code. This value uniquely represents a Site in the ESP dashboard.
Listing campaigns, mailing lists, and their relations
Piano ESP allows programmatic access to the list of Email campaigns, Mailing lists, and relations between them.
Listing campaigns for a publisher (site)
This method allows you to list all campaigns available in your account.
HTTP [GET] to:
http(s)://api-esp.piano.io/publisher/list/?api_key=
will return a JSON object:
{
"lists": [ {
"Id": <int>,// campaign id
"Name": <string>,// campaign name
"Publisher_Id": <int>,// publisher (site) id
"Active": <int>,// campaign active status,// (enabled / disabled)
"FriendlyName": <string>, // campaign friendly name
"Type": <int>,// campaign type (internal value)
}, { ... } ]
}
(also known as ) should be retrieved from the Piano ESP dashboard or integration code. This value uniquely represents a Site in the ESP dashboard.
Listing mailing lists attached to a campaign
This method allows you to list all Mailing lists attached to a given Campaign.
HTTP [GET] to:
http(s)://api-esp.piano.io/publisher/pub//ml//sq?api_key=
will return a JSON array:
[{
"Id": <int>,// mailing list id
"Name": <string>,// mailing list name
"InternalName": <string>,// internal mailing list name
"HideOnSubPage": <binary>,// the value 1 means that the mailing list is hidden on the subscribe page, and 0 that it is not
"Publisher_Id": <int>,// publisher (site) id
"Active": <int>,// mailing list active state,// (enabled / disabled)
"mailingLists" : [ <int>, ... ], // list of campaigns that have this mailing list attached
}, { ... } ]
(also known as ) should be retrieved from the Piano ESP dashboard or integration code. This value uniquely represents a Site in the ESP dashboard.
should be queried from the Piano ESP dashboard. This value uniquely represents a campaign within the Piano ESP dashboard.
Note: Please pay attention to the field within returned objects array called "mailingLists" which actually contains a list of campaign IDs that have a given mailing list attached. This ambiguity comes from the historical naming within the inside of our product. Treat members of that array as "campaign IDs".
Listing mailing lists for a publisher (site)
This method allows you to list all Mailing lists available in your account.
HTTP [GET] to:
http(s)://api-esp.piano.io/publisher/pub//sq?api_key=
will return a JSON array:
[{
"Id": <int>,// mailing list id
"Name": <string>,// mailing list name
"Publisher_Id": <int>,// publisher (site) id
"Active": <int>,// mailing list active state, // (enabled / disabled)
"mailingLists" : [ <int>, ... ], // list of campaigns that have this mailing list attached
}, { ... } ]
(also known as ) should be retrieved from the Piano ESP dashboard or integration code. This value uniquely represents a Site in the ESP dashboard.
Note: Please pay attention to the field within returned objects array called "mailingLists" which actually contains a list of campaign IDs that have a given mailing list attached. This ambiguity comes from the historical naming within the inside of our product. Treat members of that array as "campaign IDs".
Client-side integration
Besides server-side API Piano ESP supports a number of in-browser (client-side) integration capabilities:
-
RETRIEVAL OF CURRENTLY SHOWN WIDGETS ("IMPRESSION", MIGHT NOT BE WITHIN A VIEWPORT)
-
RETRIEVAL OF CURRENTLY VISIBLE WIDGETS ("REAL IMPRESSION", ACTUALLY SHOWN WITHIN A VIEWPORT)
-
VISITORS IMPERSONATION
-
ABILITY TO FORCIBLY SUPPRESS WIDGET DISPLAYING (COMPLETELY OR TEMPORARILY)
-
ABILITY TO VERIFY WIDGET LOCK STATUS (SDK MAY LOCK WIDGETS AS WELL BASED ON INTERNAL RULES / CONDITIONS)
-
ABILITY TO PROGRAMMATICALLY SUBSCRIBE USERS TO MAILING LISTS (CLIENT-SIDE)
In this section, you may find some proven code snippets making use of Piano ESP API applicable for certain common tasks
Please note, that we reserve the right to add and remove undocumented fields from our API responses without prior notice.
Client-side visitor impersonation without (SDK loading status race condition agnostic)
The following snippet allows you to perform visitor client-side impersonation without a need to worry about Piano ESP SDK load status. Once you know the email address of the current visitor, simply invoke the function below.
function impersonateVisitor(email) {
if (window.PianoESPConfig &&
typeof window.PianoESPConfig === 'object') {
window.PianoESPConfig.email =
window.PianoESPConfig.email || email;
}
window.PianoESP &&
"function" == typeof window.PianoESP.handleUserEmail &&
window.PianoESP.handleUserEmail(email);
}
Client-side programmatic users' subscription
The following snippet allows users to be subscribed to mailing lists (squads) client-side programmatically.
window.PianoESP &&
"function" == typeof window.PianoESP.handleUserDataPromise &&
window.PianoESP.handleUserDataPromise
({ email: "user@example.com", squads:
[ mailing_list_ID0, mailing_list_ID1, ... ] });
Email Campaign Statistics via API
Full campaign statistics by date
The below endpoint allows getting full statistics on campaigns within a selected date range and for the entire existence of the campaign.
HTTP [GET] to:
http(s)://api-esp.piano.io/stats/campaigns/full/?date_start=&date_end=&api_key=
will return a JSON array:
{
"deliverability": {
"total": {
"byDate": [
{
"key": "sent",
"values": [
{
"x": 1603843200000,
"y": 0
},
{
"x": 1603929600000,
"y": 0
}
]
},
{
"key": "no_stories_found",
"values": [
{
"x": 1603843200000,
"y": 0
},
{
"x": 1603929600000,
"y": 0
}
]
},
{
"key": "deferral",
"values": [
{
"x": 1603843200000,
"y": 96
},
{
"x": 1603929600000,
"y": 80
}
]
},
{
"key": "hard_bounce",
"values": [
{
"x": 1603843200000,
"y": 0
},
{
"x": 1603929600000,
"y": 0
}
]
},
{
"key": "other",
"values": [
{
"x": 1603843200000,
"y": 0
},
{
"x": 1603929600000,
"y": 0
}
]
},
{
"key": "reject",
"values": [
{
"x": 1603843200000,
"y": 12240
},
{
"x": 1603929600000,
"y": 12300
}
]
},
{
"key": "retry",
"values": [
{
"x": 1603843200000,
"y": 12240
},
{
"x": 1603929600000,
"y": 12300
}
]
},
{
"key": "soft_bounce",
"values": [
{
"x": 1603843200000,
"y": 12240
},
{
"x": 1603929600000,
"y": 12300
}
]
},
{
"key": "spam",
"values": [
{
"x": 1603843200000,
"y": 12240
},
{
"x": 1603929600000,
"y": 12300
}
]
}
],
"totalsForSelectedTime": {
"sent": 0,
"no_stories_found": 0,
"deferral": 176,
"hard_bounce": 0,
"other": 0,
"reject": 24540,
"retry": 24540,
"soft_bounce": 24540,
"spam": 24540,
}
}
},
"performance": {
"total": {
"byDate": [
{
"key": "click",
"values": [
{
"x": 1603843200000,
"y": 69
},
{
"x": 1603929600000,
"y": 84
}
]
},
{
"key": "promo_click",
"values": [
{
"x": 1603843200000,
"y": 7
},
{
"x": 1603929600000,
"y": 3
}
]
},
{
"key": "open",
"values": [
{
"x": 1603843200000,
"y": 0
},
{
"x": 1603929600000,
"y": 0
}
]
}
],
"totalsForSelectedTime": {
"click": 153,
"promo_click": 10,
"open": 0
}
},
"unique": {...}
},
"performanceByDevice": {
"total": {
...
"click": {
"byDate": [
{
"key": "mobile",
"values": [
...
{
"x": 1603929600000,
"y": 84
}
...
]
},
],
"totalsForSelectedTime": {
...
"mobile": 153,
...
}
},
...
},
"unique": {...}
},
"performanceByClient": {
"total": {
...
"click": {
"byDate": [
{
"key": "gmail",
"values": [
...
{
"x": 1603929600000,
"y": 84
}
...
]
},
],
"totalsForSelectedTime": {
...
"gmail": 153,
...
}
},
...
},
"unique": {...}
},
"performanceByLocation": {
"total": {
...
"click": {
"byDate": [
{
"key": "ua",
"values": [
...
{
"x": 1603929600000,
"y": 84
}
...
]
},
],
"totalsForSelectedTime": {
...
"ua": 153,
...
}
},
...
},
"unique": {...}
},
"performanceLocationByDevice": {
"total": {
...
"mobile": {
...
"click": {
"byDate": [
{
"key": "ua",
"values": [
...
{
"x": 1603929600000,
"y": 84
}
...
]
},
],
"totalsForSelectedTime": {
...
"ua": 153,
...
}
},
...
}
...
},
"unique": {...}
}
}
Path Parameters:
|
- REQUIRED |
string a comma-separated list of campaign IDs list (e.g.: 5,9,34) |
IDs of campaigns. Note: if you indicate several IDs you will receive aggregated statistics for all listed campaigns (not separately for every campaign) |
Query parameters:
|
- REQUIRED |
YYYY-MM-DD |
start date of a period |
|
- REQUIRED |
YYYY-MM-DD |
end date of a period |
|
- REQUIRED |
string |
API_KEY of publisher |
Full campaign statistics by sendbucket
The below endpoint allows getting full campaign statistics by sendbuckets.
In the context of ESP campaigns, a sendbucket represents a pivotal element that defines the specific instance when a campaign is sent. A campaign, comprising various settings such as sending mode, templates, sources (i.e. RSS feeds), and mailing lists, is initiated through the concept of sendbuckets. Essentially, a sendbucket encapsulates the details of 'when' the campaign is sent, 'to whom' it is sent (active users at that moment), and 'what' content is included (stories picked up at that time).
If needed, the sendbucket ID can be retrieved from Piano Support.
HTTP [GET] to:
/stats/campaign//sb/?api_key=
will return a JSON array:
{
"deliverability": {
"total": {
"byDate": [
{
"key": "sent",
"values": [
{
"x": 1603843200000,
"y": 0
},
{
"x": 1603929600000,
"y": 0
}
]
},
{
"key": "no_stories_found",
"values": [
{
"x": 1603843200000,
"y": 0
},
{
"x": 1603929600000,
"y": 0
}
]
},
{
"key": "deferral",
"values": [
{
"x": 1603843200000,
"y": 96
},
{
"x": 1603929600000,
"y": 80
}
]
},
{
"key": "hard_bounce",
"values": [
{
"x": 1603843200000,
"y": 0
},
{
"x": 1603929600000,
"y": 0
}
]
},
{
"key": "other",
"values": [
{
"x": 1603843200000,
"y": 0
},
{
"x": 1603929600000,
"y": 0
}
]
},
{
"key": "reject",
"values": [
{
"x": 1603843200000,
"y": 12240
},
{
"x": 1603929600000,
"y": 12300
}
]
},
{
"key": "retry",
"values": [
{
"x": 1603843200000,
"y": 12240
},
{
"x": 1603929600000,
"y": 12300
}
]
},
{
"key": "soft_bounce",
"values": [
{
"x": 1603843200000,
"y": 12240
},
{
"x": 1603929600000,
"y": 12300
}
]
},
{
"key": "spam",
"values": [
{
"x": 1603843200000,
"y": 12240
},
{
"x": 1603929600000,
"y": 12300
}
]
}
],
"totalsForSelectedTime": {
"sent": 0,
"no_stories_found": 0,
"deferral": 176,
"hard_bounce": 0,
"other": 0,
"reject": 24540,
"retry": 24540,
"soft_bounce": 24540,
"spam": 24540,
}
}
},
"performance": {
"total": {
"byDate": [
{
"key": "click",
"values": [
{
"x": 1603843200000,
"y": 69
},
{
"x": 1603929600000,
"y": 84
}
]
},
{
"key": "promo_click",
"values": [
{
"x": 1603843200000,
"y": 7
},
{
"x": 1603929600000,
"y": 3
}
]
},
{
"key": "open",
"values": [
{
"x": 1603843200000,
"y": 0
},
{
"x": 1603929600000,
"y": 0
}
]
}
],
"totalsForSelectedTime": {
"click": 153,
"promo_click": 10,
"open": 0
}
},
"unique": {...}
},
"performanceByDevice": {
"total": {
...
"click": {
"byDate": [
{
"key": "mobile",
"values": [
...
{
"x": 1603929600000,
"y": 84
}
...
]
},
],
"totalsForSelectedTime": {
...
"mobile": 153,
...
}
},
...
},
"unique": {...}
},
"performanceByClient": {
"total": {
...
"click": {
"byDate": [
{
"key": "gmail",
"values": [
...
{
"x": 1603929600000,
"y": 84
}
...
]
},
],
"totalsForSelectedTime": {
...
"gmail": 153,
...
}
},
...
},
"unique": {...}
},
"performanceByLocation": {
"total": {
...
"click": {
"byDate": [
{
"key": "ua",
"values": [
...
{
"x": 1603929600000,
"y": 84
}
...
]
},
],
"totalsForSelectedTime": {
...
"ua": 153,
...
}
},
...
},
"unique": {...}
},
"performanceLocationByDevice": {
"total": {
...
"mobile": {
...
"click": {
"byDate": [
{
"key": "ua",
"values": [
...
{
"x": 1603929600000,
"y": 84
}
...
]
},
],
"totalsForSelectedTime": {
...
"ua": 153,
...
}
},
...
}
...
},
"unique": {...}
}
}
Path parameters:
|
- REQUIRED |
number |
ID of campaign |
|
- REQUIRED |
string a comma-separated list of sendbucket IDs (e.g.: 100,101,102) |
IDs of sendbucket(s). Note: if you indicate several IDs you will receive aggregated statistics for all listed campaigns (not separately for every sendbucket) |
Query parameters:
|
- REQUIRED |
string |
API_KEY of publisher |
Advanced statistics about clicks
The below endpoint allows getting advanced statistics about email campaign clicks.
HTTP [GET] to:
/stats/advancedclicks///?api_key=
will return a JSON array:
{
"mailingListIds": [
1220
],
"clicks": 4,
"advertisement_clicks": 4,
"stats": [{
"date": "2019-01-01",
"clicks": 2,
"advertisement_clicks": 2,
"by_block": [
{
"block_id": 1040000001,
"clicks": 1,
"advertisement_clicks": 1,
"by_order": [
{
"order_num": 0,
"clicks": 1,
"advertisement_clicks": 1
}
],
"by_feed": [
{
"feed_id": 1030000001,
"clicks": 1,
"advertisement_clicks": 1
}
]
},
{
"block_id": 1040000002,
"clicks": 1,
"advertisement_clicks": 1,
"by_order": [
{
"order_num": 0,
"clicks": 1,
"advertisement_clicks": 1
}
],
"by_feed": [
{
"feed_id": 1030000001,
"clicks": 1,
"advertisement_clicks": 1
}
]
}
]
},
{
"date": "2017-01-02",
"clicks": 0,
"advertisement_clicks": 0,
"by_block": []
}]
}
Path parameters:
|
- REQUIRED |
string a comma-separated list of campaign IDs list (e.g.: 5,9,34) |
IMPORTANT: for advanced clicks stats it makes little sense to return stats for more than 1 campaign, as block IDs, and order numbers in different campaigns are not compatible. But, it is still possible to query data for several campaigns together. |
|
- REQUIRED |
YYYY-MM-DD |
start date of a period |
|
- REQUIRED |
YYYY-MM-DD |
end date of a period |
Query parameters:
|
API_KEY - REQUIRED |
string |
API_KEY of publisher |
|
- OPTIONAL |
['true', 'false'] |
aggregate data as unique metrics (only applicable to promo clicks) |
Most clicked story in a campaign
This endpoint allows you to get the most clicked stories from email campaigns.
HTTP [GET] to:
/stats/topstories///?api_key=
Will return a response:
[
{
"urlid": "TfQ91msBIAFtmLlfPivw",
"clicks": 4,
"storyids": [
1010000001
],
"link": "https://example.com/7374",
"title": "https://example.com/7374",
"id": "1010000001 / TfQ91msBIAFtmLlfPivw"
}
]
Path parameters:
|
- REQUIRED |
string a comma-separated list of campaign IDs list (e.g.: 5,9,34) |
IMPORTANT: for advanced clicks stats it makes little sense to return stats for more than 1 campaign, as block IDs, and order numbers in different campaigns are not compatible. But, it is still possible to query data for several campaigns together. |
|
- REQUIRED |
YYYY-MM-DD |
start date of a period |
|
- REQUIRED |
YYYY-MM-DD |
end date of a period |
Query parameters:
|
API_KEY - REQUIRED |
string |
API_KEY of publisher |
Mailing List Statistics via API
Full mailing list statistics by date
The below endpoint allows getting full statistics about mailing lists within a selected date range and for the entire existence of the mailing list.
HTTP [GET] to:
/stats/squads/full/?date_start=&date_end=&api_key=
Will return a response:
{
"mailingListActivity": {
"total": {
"byDate": [
{
"key": "subAdded",
"values": [
{
"x": 1603843200000,
"y": 0
},
{
"x": 1603929600000,
"y": 0
}
]
},
{
"key": "subRemoved",
"values": [
{
"x": 1603843200000,
"y": 96
},
{
"x": 1603929600000,
"y": 80
}
]
}
],
"totalsForSelectedTime": {
"subAdded": 0,
"subRemoved": 176
}
},
"unique": {...},
"new": {...}
},
"subscribeDetails": {
"total": {
"byDate": [
{
"key": "userInitiated",
"values": [
{
"x": 1603843200000,
"y": 0
},
{
"x": 1603929600000,
"y": 0
}
]
},
{
"key": "apiInitiated",
"values": [
{
"x": 1603843200000,
"y": 96
},
{
"x": 1603929600000,
"y": 80
}
]
},
{
"key": "dashInitiated",
"values": [
{
"x": 1603843200000,
"y": 0
},
{
"x": 1603929600000,
"y": 0
}
]
},
{
"key": "igSync",
"values": [
{
"x": 1603843200000,
"y": 96
},
{
"x": 1603929600000,
"y": 80
}
]
},
{
"key": "testEmail",
"values": [
{
"x": 1603843200000,
"y": 0
},
{
"x": 1603929600000,
"y": 0
}
]
},
{
"key": "directSub",
"values": [
{
"x": 1603843200000,
"y": 96
},
{
"x": 1603929600000,
"y": 80
}
]
},
{
"key": "other",
"values": [
{
"x": 1603843200000,
"y": 0
},
{
"x": 1603929600000,
"y": 0
}
]
}
],
"totalsForSelectedTime": {
"userInitiated": 0,
"apiInitiated": 176,
"dashInitiated": 0,
"igSync": 176,
"testEmail": 0,
"directSub": 176,
"other": 0,
}
},
"unique": {...},
"new": {...}
},
"unsubscribeDetails": {
"total": {
"byDate": [
{
"key": "userInitiated",
"values": [
{
"x": 1603843200000,
"y": 0
},
{
"x": 1603929600000,
"y": 0
}
]
},
{
"key": "apiInitiated",
"values": [
{
"x": 1603843200000,
"y": 96
},
{
"x": 1603929600000,
"y": 80
}
]
},
{
"key": "hardBounce",
"values": [
{
"x": 1603843200000,
"y": 0
},
{
"x": 1603929600000,
"y": 0
}
]
},
{
"key": "spam",
"values": [
{
"x": 1603843200000,
"y": 96
},
{
"x": 1603929600000,
"y": 80
}
]
},
{
"key": "dashInitiated",
"values": [
{
"x": 1603843200000,
"y": 0
},
{
"x": 1603929600000,
"y": 0
}
]
},
{
"key": "igSync",
"values": [
{
"x": 1603843200000,
"y": 96
},
{
"x": 1603929600000,
"y": 80
}
]
},
{
"key": "other",
"values": [
{
"x": 1603843200000,
"y": 0
},
{
"x": 1603929600000,
"y": 0
}
]
}
],
"totalsForSelectedTime": {
"userInitiated": 0,
"apiInitiated": 176,
"hardBounce": 0,
"spam": 176,
"dashInitiated": 0,
"igSync": 176,
"other": 0,
}
},
"unique": {...},
"new": {...}
},
}
Path Parameters:
|
- REQUIRED |
string a comma-separated list of Mailing List IDs (e.g.: 5,9,34) |
IDs of MLs. Note: if you indicate several IDs you will receive aggregated statistics for all listed mailing lists (not separately for every mailing list) |
Query parameters:
|
- REQUIRED |
YYYY-MM-DD |
date start of a period |
|
- REQUIRED |
YYYY-MM-DD |
date end of a period |
|
- REQUIRED |
string |
API_KEY of publisher |
Total mailing list subscribers
To get information about all users and active subscribers for a specific mailing list, you can use the below API endpoint.
HTTP [POST] to:
/publisher/pub//sq/subscribers?api_key=
with the following JSON body:
{
"sqIds": [1, 2, 3, ...]
}
Will return a response:
{
"1": {
"squad_users": 4,
"squad_users_active": 1
},
"2": {
"squad_users": 0,
"squad_users_active": 0
},
"3": {
"squad_users": 1000,
"squad_users_active": 999
},
...
}
Path parameters:
|
PUB_ID - REQUIRED |
integer |
ID of the Publisher |
Query parameters:
|
API_KEY - REQUIRED |
string |
API_KEY of publisher |
Body:
|
sqIds - REQUIRED |
array of integers |
Mailing List ID(s) |
Push Campaign Statistics via API
Full push campaign statistics by date
This endpoint allows getting full statistics on push campaigns within a selected date range and for the entire existence of the campaign.
HTTP [GET] to:
/stats/push/campaigns/full/?date_start=&date_end=&api_key=
Will return a response:
{
"deliverability": {
"byDate": [
{
"key": "error_invalid_safari_configuration",
"values": [
{
"x": 1603843200000,
"y": 0
},
{
"x": 1603929600000,
"y": 0
}
]
},
{
"key": "error_invalid_subscription",
"values": [
{
"x": 1603843200000,
"y": 96
},
{
"x": 1603929600000,
"y": 80
}
]
},
{
"key": "error_invalid_vapid_keys",
"values": [
{
"x": 1603843200000,
"y": 0
},
{
"x": 1603929600000,
"y": 0
}
]
},
{
"key": "no_stories_found",
"values": [
{
"x": 1603843200000,
"y": 0
},
{
"x": 1603929600000,
"y": 0
}
]
},
{
"key": "push_sent",
"values": [
{
"x": 1603843200000,
"y": 12240
},
{
"x": 1603929600000,
"y": 12300
}
]
}
],
"totalsForSelectedTime": {
"error_invalid_safari_configuration": 0,
"error_invalid_subscription": 176,
"error_invalid_vapid_keys": 0,
"no_stories_found": 0,
"push_sent": 24540
}
},
"performance": {
"byDate": [
{
"key": "click",
"values": [
{
"x": 1603843200000,
"y": 69
},
{
"x": 1603929600000,
"y": 84
}
]
},
{
"key": "click_to_button_1",
"values": [
{
"x": 1603843200000,
"y": 7
},
{
"x": 1603929600000,
"y": 3
}
]
},
{
"key": "click_to_button_2",
"values": [
{
"x": 1603843200000,
"y": 0
},
{
"x": 1603929600000,
"y": 0
}
]
},
{
"key": "received",
"values": [
{
"x": 1603843200000,
"y": 2484
},
{
"x": 1603929600000,
"y": 2674
}
]
},
{
"key": "close",
"values": [
{
"x": 1603843200000,
"y": 1255
},
{
"x": 1603929600000,
"y": 1330
}
]
}
],
"totalsForSelectedTime": {
"click": 153,
"click_to_button_1": 10,
"click_to_button_2": 0,
"received": 5158,
"close": 2585
}
},
"performanceByDevice": {
...
"click": {
"byDate": [
{
"key": "mobile",
"values": [
...
{
"x": 1603929600000,
"y": 84
}
...
]
},
],
"totalsForSelectedTime": {
...
"mobile": 153,
...
}
},
...
},
"performanceByBrowser": {
...
"click": {
"byDate": [
{
"key": "chrome",
"values": [
...
{
"x": 1603929600000,
"y": 84
}
...
]
},
],
"totalsForSelectedTime": {
...
"chrome": 153,
...
}
},
...
},
"performanceByLocation": {
...
"click": {
"byDate": [
{
"key": "ua",
"values": [
...
{
"x": 1603929600000,
"y": 84
}
...
]
},
],
"totalsForSelectedTime": {
...
"ua": 153,
...
}
},
...
},
"performanceLocationByDevice": {
...
"mobile": {
...
"click": {
"byDate": [
{
"key": "ua",
"values": [
...
{
"x": 1603929600000,
"y": 84
}
...
]
},
],
"totalsForSelectedTime": {
...
"ua": 153,
...
}
},
...
}
...
}
}
Path Parameters:
|
- REQUIRED |
string a comma-separated list of Campaign IDs list (e.g.: 5,9,34) |
ID of campaign(s). Note: if you indicate several IDs you will receive aggregated statistics for all listed campaigns (not separately for every campaign) |
Query parameters:
|
- REQUIRED |
YYYY-MM-DD |
start date of a period |
|
- REQUIRED |
YYYY-MM-DD |
end date of a period |
|
- REQUIRED |
string |
API_KEY of publisher |
Full push campaign statistics by sendbucket
This endpoint allows you to get push campaign statistics by sendbucks.
If needed, the sendbucket ID can be retrieved from Piano Support.
HTTP [GET] to:
/stats/push/campaign//sb/?api_key=
Will return a response:
{
"deliverability": {
"byDate": [
{
"key": "error_invalid_safari_configuration",
"values": [
{
"x": 1603843200000,
"y": 0
},
{
"x": 1603929600000,
"y": 0
}
]
},
{
"key": "error_invalid_subscription",
"values": [
{
"x": 1603843200000,
"y": 96
},
{
"x": 1603929600000,
"y": 80
}
]
},
{
"key": "error_invalid_vapid_keys",
"values": [
{
"x": 1603843200000,
"y": 0
},
{
"x": 1603929600000,
"y": 0
}
]
},
{
"key": "no_stories_found",
"values": [
{
"x": 1603843200000,
"y": 0
},
{
"x": 1603929600000,
"y": 0
}
]
},
{
"key": "push_sent",
"values": [
{
"x": 1603843200000,
"y": 12240
},
{
"x": 1603929600000,
"y": 12300
}
]
}
],
"totalsForSelectedTime": {
"error_invalid_safari_configuration": 0,
"error_invalid_subscription": 176,
"error_invalid_vapid_keys": 0,
"no_stories_found": 0,
"push_sent": 24540
}
},
"performance": {
"byDate": [
{
"key": "click",
"values": [
{
"x": 1603843200000,
"y": 69
},
{
"x": 1603929600000,
"y": 84
}
]
},
{
"key": "click_to_button_1",
"values": [
{
"x": 1603843200000,
"y": 7
},
{
"x": 1603929600000,
"y": 3
}
]
},
{
"key": "click_to_button_2",
"values": [
{
"x": 1603843200000,
"y": 0
},
{
"x": 1603929600000,
"y": 0
}
]
},
{
"key": "received",
"values": [
{
"x": 1603843200000,
"y": 2484
},
{
"x": 1603929600000,
"y": 2674
}
]
},
{
"key": "close",
"values": [
{
"x": 1603843200000,
"y": 1255
},
{
"x": 1603929600000,
"y": 1330
}
]
}
],
"totalsForSelectedTime": {
"click": 153,
"click_to_button_1": 10,
"click_to_button_2": 0,
"received": 5158,
"close": 2585
}
},
"performanceByDevice": {
...
"click": {
"byDate": [
{
"key": "mobile",
"values": [
...
{
"x": 1603929600000,
"y": 84
}
...
]
},
],
"totalsForSelectedTime": {
...
"mobile": 153,
...
}
},
...
},
"performanceByBrowser": {
...
"click": {
"byDate": [
{
"key": "chrome",
"values": [
...
{
"x": 1603929600000,
"y": 84
}
...
]
},
],
"totalsForSelectedTime": {
...
"chrome": 153,
...
}
},
...
},
"performanceByLocation": {
...
"click": {
"byDate": [
{
"key": "ua",
"values": [
...
{
"x": 1603929600000,
"y": 84
}
...
]
},
],
"totalsForSelectedTime": {
...
"ua": 153,
...
}
},
...
},
"performanceLocationByDevice": {
...
"mobile": {
...
"click": {
"byDate": [
{
"key": "ua",
"values": [
...
{
"x": 1603929600000,
"y": 84
}
...
]
},
],
"totalsForSelectedTime": {
...
"ua": 153,
...
}
},
...
}
...
}
}
Path Parameters:
|
- REQUIRED |
number |
ID of a campaign. |
|
- REQUIRED |
string a comma-separated list of sendbucket IDs (e.g.: 100,101,102) |
IDs of sendbucket(s). Note: if you indicate several IDs you will receive aggregated statistics for all listed campaigns (not separately for every sendbucket) |
Query parameters:
|
- 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/?date_start=&date_end=&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:
|
- 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:
|
- REQUIRED |
YYYY-MM-DD |
start date of a period |
|
- REQUIRED |
YYYY-MM-DD |
end date of a period |
|
- REQUIRED |
string |
API_KEY of publisher |