Description
This API fetches sending analytics (max 100 records) for a campaign or a message or a date range. You may specify at least 1 or a combination of these 3 inputs.
Specifying a message ID of an email / SMS will retrieve the analytics of its sendings carried out – each list it was sent to, each time it was sent. getCampaignAnalytics() provides consolidated and detailed sending analytics of the message.
Specifying a campaign will return sending analytics of sent messages (email/SMS) belonging to the specified campaign. Any unsent messages belonging to the campaign will not be listed in the response.
Specifying a date range with start and end dates in YYYY-MM-DD HH:MM:SS format (HH:MM:SS is optional) will return sending analytics of messages (email/SMS) sent within the specified dates (inclusive).
You must specify at least one input amongst the campaign name, message ID and date range. If all three inputs are specified, the API will consider the message ID within the date range (campaign name will be ignored) for retrieving the sending analytics.
The analytics is returned in a JSON format in the API’s response. Please refer to the “Return Values” section below for the details of the analytics that will be retrieved.
getCampaignAnalytics() API is limited for retrieving analytics of 100 sendings. One sending means a message sent to one or more lists at one time.
This API needs to be called using an HTTP Post method with data in JSON format as shown below.
URL: https://api2.juvlon.com/v4/getCampaignAnalytics
Json Parameter –
'{
"apiKey":"$apiKey",
“messageType”:”$messageType”,
"messageID":"$messageID",
"campaignName":"$campaignName",
“startDate”:”$startDate”,
“endDate”:”$endDate”
}';
Arguments
| Name | Type | Description | Default |
| apiKey | String | Mandatory. The apiKey that gives you access to our HTTP APIs. The apiKey authenticates you and helps us to identify your Juvlon account. | |
| messageType | String | Type of the messages “email” OR “sms”. If not specified, messageType will default to “email” | |
| messageID | Int | The ID of an email / SMS message whose sending analytics are to be retrieved. | |
| campaignName | String | The name of a campaign whose sending analytics are to be retrieved. | |
| startDate | String | Start date in “YYYY-MM-DD HH:MM:SS” format (time input HH:MM:SS is optional) specifies the starting date-time from which the sending analytics are to be retrieved. Start time 00:00:00 is considered as default, if start time input is not specified. Date and time are relative to the time zone setting in your Juvlon accounty. | |
| endDate | String | End date in “YYYY-MM-DD HH:MM:SS” format (time input HH:MM:SS is optional) specifies the date-time up to which the analytics are to be retrieved. End time 23:59:59 is considered as default, if end time input is not specified. If startDate is specified and endDate is not, the endDate is considered as today’s date. Date and time are relative to the time zone setting in your Juvlon account. |
Return values
| Name | Type | Description |
| code | String | The Success or Error response code as returned by the API. Please refer to the section “Possible-Response-Codes” for more details. |
| status | String | Description of the error code returned. |
| transactionID | String | A number generated by the API to uniquely identify the current call. Also known as the API_Call_ID. |
| campaignName | String | The name of the campaign to which the message(s) whose analytics are being retrieved belong. |
| campaignID | Int | The ID of the campaign to which the message(s) whose analytics are being retrieved belong. |
| campaignCreationDate | String | The date of creation of the campaign to which the message(s) whose analytics are being retrieved belong. |
| showingAnalyticsFor | String | A string specifying the number of records out of the total available records in the database for which analytics are being retrieved belong (One record equates to analytics of a message sent to one or more lists at one time). As an example, the return value for this field can be “47/47 sendings” (ie showing 47 out of 47 records) or “100/350 sendings” (showing 100 out of 350 records) which means you may need to alter your input parameters to fetch the remaining records. |
| messages[ ] | – | A list / array of all messages as per the campaign / message specified in the API request, and their analytics. Each item in this list will be a key-value pair:
|
| The following values are returned for each message in the messages[ ] list: | ||
| messageID | Int | The ID of the message whose analytics are being retrieved. |
| messageType | String | The type of this message – email / SMS |
| subject | String | The subject of this message. |
| creationDate | String | The date of creation of this message. |
| sender | String | The sender of this message.. |
| isTransactional | String | “Yes” – if the message is a transactional email / sms “No” – if the message is not a transactional email / sms |
| linkTracking | String | “Yes” – if the links in this message are tracked. “No” – if the links in this message are not tracked. |
| overallAnalytics[] | – | Totals of all sendings of this message (details). |
| sendings[ ] | – | A list / array of all sendings of this message. A message may be sent multiple times at different dates/times, and via different methods (using the Juvlon UI or using an API). Each of these is called a separate “sending”. |
| The following values are returned for a sent message in the sendings[ ] list: | ||
| sentOn | String | The date and time when this specific sending was carried out. |
| lists[ ] | – | An array of all lists that this message was sent-to during this sending. Each item in this array will be a key-value pair:
|
| The following values are returned for each list that this message was sent-to during this sending: | ||
| listName | String | The name of a list to which this message was sent. |
| listID | Int | The ID of a list to which this message was sent. |
| overAllAnalytics[ ] The following values are returned for the Total Analytics of each message | ||
| sent | Int | The number of recipients to which the email/SMS was sent in this sending. |
| opens | Int | The count of all opens received in this sending. * Provided for emails only |
| uniqueOpens | Int | TheThe count of all unique opens (no. of recipients who opened) in this sending. * Provided for emails only |
| bounces | Int | The count of hard bounces received in the current/overall sending. * Provided for emails only |
| optOuts | Int | The count of opt-outs (recipients who unsubscribed) received in the current/overall sending. * Provided for emails only |
| complaints | Int | The count of spam complaints received in the cThe count of spam complaints received in the current/overall sending. * Provided for emails only |
| usage | Int | The count of actual SMS messages sent in the current/overall sending. This is different from the count of recipients when the size of an SMS message is larger and each message is sent out as 2 or more actual SMS. Thus if a big message (that needs to be sent out in 2 SMS each) is sent to 100 recipients, then the “sent” count will be 100, but the “usage” will be 200. * Provided for SMS messages only |
| delivered | Int | The count of recipients to who the SMS message was delivered in the current/overall sending. * Provided for SMS messages only |
| nonDelivered | Int | The count of recipients to who the SMS message was not delivered in the current/overall sending. * Provided for SMS messages only |
| DND | Int | The count of recipients to who the SMS message could not be delivered because they were registered for the “Do not disturb” service at the time. * Provided for SMS messages only |
| clicks | Int | The count of clicks received in the current/overall sending. * Provided for Emails and SMS messages |
| clickedLinks[ ] | – | A list / array of the links that were clicked A list / array of the links that were clicked in the current/overall sending. |
| clickedLinks[ ] returns these values for each link that was clicked: | ||
| link | String | The url of the link that was clicked. |
| linkID | Int | The ID of the link that was clicked. |
| clicks | Int | The count of clicks received for the current link |
Usage / Example(s)
PHP Example Code for Integration
$url = 'https://api2.juvlon.com/v4/getCampaignAnalytics';
$data = '{"apiKey":"KEY",
“messageType”:”email”,
"messageID":"1",
"campaignName":"ABC",
“startDate”:”2022-08-01”,
“endDate”:”2022-08-31”
}';
$ch = curl_init($url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, $data);
$res1 = curl_exec($ch);
curl_close($ch);
Success-Response
HTTP/1.1
{
"code":"200",
"status":"Success",
"transactionID":"13228",
"campaignName": "Promotions",
"campaignID": "2",
"campaignCreationDate": "2022-08-13 09:10:56",
"showingAnalyticsFor": "2/2 sendings",
"messages": {
"1850": {
"messageID": "1850",
"messageType": "email",
"subject": "My First email",
"creationDate": "2022-08-23 09:15:45",
"sender": "john@abc.com",
"isTransactional": "yes",
"linkTracking": "yes",
"overallAnalytics": {
"sent": "1100",
"opens": "100",
"uniqueOpens": "70",
"clicks": "50",
"clickedLinks": [{
"link": "url1",
"linkID": "21",
"clicks": "20"
},
{
"link": "url2",
"linkID": "22",
"clicks": "30"
}
],
"bounces": "1",
"optOuts": "0",
"complaints": "0"
},
"sendings": [{
"sentOn": "2022-08-23 09:30:45",
"lists": {
"ListA": {
"listName": "ListA",
"listID": "123",
"sent": "509",
"opens": "322",
"uniqueOpens": "212",
"clicks": "135",
"clickedLinks": [{
"link": "url1",
"linkID": "21",
"clicks": "101"
},
{
"link": "url2",
"linkID": "22",
"clicks": "34"
}
],
"bounces": "1",
"optOuts": "0",
"complaints": "0"
},
"ListB": {
"listName": "ListB",
"listID": "124",
"sent": "456",
"opens": "185",
"uniqueOpens": "93",
"clicks": "92",
"clickedLinks": [{
"link": "url1",
"linkID": "21",
"clicks": "36"
},
{
"link": "url2",
"linkID": "22",
"clicks": "56"
}
],
"bounces": "0",
"optOuts": "0",
"complaints": "0"
}
},
{
"sentOn": "2022-08-22 09:30:45",
"lists": {.....}
},
{
"sentOn": "2022-08-20 09:30:45",
"lists": {.....}
}
]
},
"1851": {
"messageID": "1851",
"messageType": "SMS",
"subject": "Thanks for signing up…",
"creationDate": "2022-08-15 09:15:45",
"sender": "SYGBKI",
"isTransactional": "yes",
"linkTracking": "yes",
"overallAnalytics": {...},
"sendings": [{
"sentOn": "2022-08-23 09:30:45",
"lists": {
"ListA": {
"listName": "ListA",
"listID": "123",
"sent": "509",
"usage": "1018",
"delivered": "322",
"clicks": "135",
"clickedLinks": [{
"link": "url1",
"linkID": "21",
"clicks": "101"
},
{
"link": "url2",
"linkID": "22",
"clicks": "34"
}
],
"nonDelivered": "1",
"DND": "0"
},
"ListB": {}
},
{
"sentOn": "2022-08-23 09:30:45",
"lists": {...}
}
]}
}
}
}
Possible-Response-Codes
200 Success: API Request Accepted
401 Error: Invalid Method
402 Error: Unauthorized/Empty Key
403 Error: Unauthorized/Invalid Key
404 Error: Account Sending Blocked
405 Error: Your Juvlon account is expired
448 Error: Your Juvlon account is Deactivated
482 Error: Invalid Message ID
483 Error: Campaign name does not exist in your Juvlon Account
485 Error: No campaign / message / sentID specified
486 Error: Message not sent
501 Error: Severe server error. Try later
631 Error: Invalid date format for the startDate
632 Error: Invalid date format for the endDate
633 Error: Invalid range for the startDate and endDate
634 Error: Invalid messageType