GreenArrow Email Software Documentation

Stats API

Overview

GreenArrow Engine provides an API for retrieving statistics in embeddable HTML format, or a JSON or PHP serialized array. Stats can be retrieved for campaigns or recipients. This allows you to directly embed GreenArrow Engine’s reports into your own application.

Authenticate your request using HTTP Basic authentication with the username and password that you use to access the GreenArrow Engine administration interface.

Index of Campaigns and ListIDs

This section describes how to make an API call which returns indexes of Campaigns and ListIDs similar to what’s seen when clicking on the Statistics tab within GreenArrow Engine’s web interface.

Using the API

Make an HTTP GET request to /greenarrowadmin/h/stats_sends_list.php on your server.

Add the following GET query parameters:

Key Value Required Description
api string Yes Format of the the report. The following options are available:

• json - raw data formatted as a JSON serialized array
• php - a serialized PHP array
• print_r - an array that’s been processed by PHP’s print_r function
listid string No The ListID that you wish to limit results to. If this parameter is excluded, the API will include all ListIDs in its results
_page_size integer No The maximum number of results to display. The default value is 100
_page integer No The page number to display in the results. Counting starts from 0, and by default, the first page is displayed.
injtime_first string Required if injtime_first_start and injtime_first_end are set The date range that you wish to display results for.This field should be set equal to custom if injtime_first__start and injtime_first__end are set. Otherwise it is optional. Value values are:

• all - All dates
• last_7 - Last 7 days
• last_14 - Last 14 days
• last_30 - Last 30 days. This is the default value
• last_60 - Last 60 days
• last_90 - Last 90 days
• custom - Custom range defined by injtime_first__start and injtime_first__end
__changeform integer Required if injtime_first_start and injtime_first_end are set This field should be set equal to 1 if the injtime_first__start and injtime_first__end values are set. Otherwise it should be excluded.
injtime_first__start string Required if injtime_first__end is set The start of the date range that you wish to display results for in mm/dd/yyyy format. For example, to use a start date of January 1, 2013, you would set this value to 01/01/2013, which would be URL encoded as 01%2F01%2F2013.
injtime_first__end string Required if injtime_first__start is set The end of the date range that you wish to display results for in mm/dd/yyyy format. For example, to use an end date of December 31, 2013, you would set this value to 12/31/2013, which would be URL encoded as 12%2F31%2F2013.

The date based parameters listed above (injtime_first, injtime_first__start, and injtime_first__end) all filter results in reference to the date that GreenArrow Engine received the first message in a campaign. For example, if a campaign started sending in January 1st, and completed on January 2nd, the date that GreenArrow Engine would use for that campaign in its filtering criteria would be January 1st.

Data Returned After a Successful API Call

Key Value Description
success integer 1 if success, 0 if failure
mailing_lists array An array containing one element for each mailing list for which there are stats available. Each element’s key is the list’s ListID. If GreenArrow Engine has a more user friendly description for the mailing list, such as the GreenArrow Studio mailing list name, that description goes into that element’s value. Otherwise the value contains the ListID again.
sends array Any array containing one element for each “Send”, or “Campaign” that GreenArrow Engine has stats for which meet the filtering criteria. This array is described in more detail in the next table.

The structure of the sends array that is included in API call results is described below:

Key Value Description
id integer The SendDBID of the campaign. This is not the same thing as the SendID. See this page’s “SendID and SendDBID” section for more details.
sendid string The SendID of the campaign.
injtime_first integer The time, in seconds since the UNIX epoch that GreenArrow Engine received the first message for this campaign.
injtime_last integer The time, in seconds since the UNIX epoch that GreenArrow Engine received the last message for this campaign.
total_messages integer The number of messages in this campaign
total_failure integer The number of bounces in this campaign
total_inqueue integer The number of messages still in queue for this campaign
lists_str string This field is not currently documented.

Data Returned After a Failed API Call

Key Value Description
success integer 1 if success, 0 if failure
error_text string Text message for this error.

Example

URL

The following URL corresponds to any API call that specifies that the results should be processed by PHP’s print_r function before being returned:

    http://mailer.example.com/greenarrowadmin/h/stats_sends_list.php?api=print_r

Result

Here are example results:

Array
(
    [success] => 1
    [mailing_lists] => Array
        (
            [47] => demo
            [t23] => t23
        )
    [sends] => Array
        (
            [0] => Array
                (
                    [id] => 991
                    [sendid] => 131
                    [injtime_first] => 1381967540
                    [injtime_last] => 1381967972
                    [total_messages] => 59704
                    [total_failure] => 541
                    [total_inqueue] => 0
                    [lists_str] => 47,59704
                )
            [1] => Array
                (
                    [id] => 990
                    [sendid] => 130
                    [injtime_first] => 1381967152
                    [injtime_last] => 1381967152
                    [total_messages] => 1
                    [total_failure] => 0
                    [total_inqueue] => 0
                    [lists_str] => t23,1
                )
        )
)

SendID and SendDBID

You may have noticed that when viewing the stats for a send in GreenArrow Engine, part of the URL contains a SendDBID. For example:

http://mailer.example.com/greenarrowadmin/h/stats_sends_view.php?senddbid=692

Even though SendDBID sounds a lot like SendID, it’s not the same thing. The SendID is what you’re working with when interacting with GreenArrow Engine. The SendDBID is value that GreenArrow Engine uses internally to uniquely identify sends. SendIDs are described in the GreenArrow Concepts page.

Campaign Stats

Using the API

Make a request to /greenarrowadmin/h/stats_sends_view.php on your server.

Add the following GET query parameters:

Key Value Description
sendid string The SendID that you want to get data for
api string Format of the the report

Normally the api key would be assigned a value of embed_html to retrieve embeddable HTML. There are additional options available though, if you prefer to work with raw data:

• embed_html - Return embeddable HTML. This is what is normally used.
• json - raw data formatted as a JSON serialized array
• php - a serialized PHP array
• print_r - an array that’s been processed by PHP’s print_r function

The remainder of this section assumes that the api key was assigned a value of embed_html.

The data returned is a JSON serialized array. The value of the head key in this array should be placed within the <head> tags of your web page. The value of the html key should be placed within the <body> tags of your web page.

We also recommend setting these styles, if your CSS does not already do this:

<style type="text/css">
body  { font-size: 12px; }
table { font-size: 12px; }
</style>

Example

The following example retrieves the Send Statistics for a campaign with a SendID of 4:

PHP Code

<?php

$url = "http://admin:PASSWORD@hostname/greenarrowadmin/h/stats_sends_view.php?sendid=4&api=embed_html";

$data = file_get_contents($url);

if ( substr($data, 0, 2) != '{"' )
    die("error");

$array = json_decode($data, true);

?>

<html>
<head>

<style type="text/css">
body  { font-size: 12px; }
table { font-size: 12px; }
</style>

<?php echo $array['head']; ?>

</head>
<body>

<div style="width: 870px; padding: 20px; ">

<?php echo $array['html']; ?>

</div>

</body>
</html>

Result

worddav0edb5ccb6c3b5a97b69335344f2d1a7c.png

Recipient Stats

Using the API

Make a request to /greenarrowadmin/h/stats_sends_view_logs.php on your server.

Add the following GET query parameters:

Key Value Description
sendid string The SendID that you want to get data for
api embed_recipient_status_html Retrieves embeddable HTML
email string Recipient email address that you want to get data for

The data returned is a JSON serialized array. The value of the head key in this array should be placed within the <head> tags of your web page. The value of the html key should be placed within the <body> tags of your web page.

We also recommend setting these styles, if your CSS does not already do this:

<style type="text/css">
body  { font-size: 12px; font-family: Arial, sans-serif; }
table { font-size: 12px; font-family: Arial, sans-serif; }
table.quick_data {
 border-collapse:collapse;
 border-spacing:0;
}
table.quick_data tr td {
 border: 1px solid;
 padding: 3px;
 text-align: left;
 vertical-align: top;
 margin: 0;
}
</style>

Example

The following example retrieves the Send Statistics for the [email protected] recipient for a campaign with a SendID of 4:

PHP Code

<?php

$url = "http://admin:[email protected]/greenarrowadmin/h/stats_sends_view_logs.php?sendid=4&api=embed_recipient_status_html&[email protected]";

$data = file_get_contents($url);

if ( substr($data, 0, 2) != '{"' )
    die("error");

$array = json_decode($data, true);

?>

<html>
<head>

<style type="text/css">
body  { font-size: 12px; font-family: Arial, sans-serif; }
table { font-size: 12px; font-family: Arial, sans-serif; }

table.quick_data {
 border-collapse:collapse;
 border-spacing:0;
}

table.quick_data tr td {
 border: 1px solid;
 padding: 3px;
 text-align: left;
 vertical-align: top;
 margin: 0;
}

</style>

<?php echo $array['head']; ?>

</head>
<body>

<div style="width: 870px; padding: 20px; ">

<?php echo $array['html']; ?>

</div>

</body>
</html>

Result

worddavd7352d53b61be1dee82a72517671ad63.png

 APIs
Send Status API 

Copyright © 2012–2024 GreenArrow Email