GreenArrow Monitor API
- Table of Contents
- How to Make API Requests using serialized PHP or JSON
- Date Formats
- Delivery (Inbox) Monitoring Methods
- Preview (Rendering) Methods
- Legacy Delivery (Inbox) Monitoring Method
How to Make API Requests using serialized PHP or JSON
You can make API requests for GreenArrow Monitor data using HTTP GET or POST requests. Results are returned in serialized PHP or JSON. The following parameters are required for every request to the API. Each command will have its own additional parameter options.
Key | Value | Description |
---|---|---|
username |
string | Your GreenArrow Monitor username. |
password |
string | Your GreenArrow Monitor password. |
output |
string | The format that you’d like to receive output in. php - serialized PHP json - serialized JSON |
For both PHP and JSON output, a document will be returned containing a serialized array or hash.
If you have any questions about how to interpret this data, please contact GreenArrow technical support.
Date Formats
A date can be passed to the API as either an integer number of seconds since the UNIX epoch, or a string in ISO 8601 date format.
ISO 8601 formatted dates have the date, time and time zone in them, as shown below.
YYYY-MM-DD T hh:mm:sszzz:zz
2012-06-01 T 12:45:40-06:00
UNIX Epoch Timestamps are simple integers representing the date and time. The following integer represents 2012/03/27 06:59:13 am PDT
.
1332856753
Dates are returned by the API as both an integer number of seconds since the UNIX epoch, and in ISO 8601 date format, as shown above.
Delivery (Inbox) Monitoring Methods
delivery_test_list
Returns a list of recent delivery monitoring tests (campaigns).
Parameters
Key | Value | Example | Description | Required |
---|---|---|---|---|
days |
integer | 5 |
The number of days of history to retrieve. | No (default: 14)
|
Example Request URL
https://monitor.drh.net/api.php?method=delivery_test_list&output=json&username=testman&password=secret123&days=5
The response to delivery_test_list
will be an array containing the following keys:
Key | Value | Example | Description |
---|---|---|---|
campaign_id |
integer | 1234 |
The internal identifier for the campaign. |
date |
string | 2012-01-17 T 12:42:00-0600 |
The date this campaign was executed. |
date_unix |
integer | 1339773180 |
A UNIX timestamp representing date . |
from_address |
string | [email protected] |
The address this campaign was sent from. |
from_name |
string | Newsletter |
The name component of the From header. |
from_domain |
string | example.com |
The domain component of from_address . |
subject |
string | Your Daily News |
The Subject of the email. |
customer_defined_campaign_id |
string | campaign-100 |
Your campaign identifier as sent in the X-CampaignID header. |
Example JSON Response
delivery_test_get_info
Returns the raw data for a delivery test (campaign).
Parameters
Key | Value | Example | Description | Required |
---|---|---|---|---|
campaign_id |
integer | 1234 |
The internal campaign_id of the campaign, as returned by delivery_test_list . |
See below. |
customer_defined_campaign_id |
string | campaign-100 |
Your campaign identifier as sent in the X-CampaignID header. |
See below. |
date |
integer or string | 1341964800 |
The date that the campaign was sent. Used to differentiate between multiple campaigns with the same customer_defined_campaign_id . See this document’s “Date Formats” section for details on formatting. |
No |
This request include either the customer_defined_campaign_id
or the campaign_id
of the campaign you are polling on. The date
field will only be used when specifying by customer_defined_campaign_id
.
If there are multiple campaigns with the same customer_defined_campaign_id
, then the one that is closer to the date
given is returned. This is helpful because the customer_defined_campaign_id
is not guaranteed to be unique. If the date
parameter is not supplied, then the most recent campaign with a matching customer_defined_campaign_id
is returned.
Example Request URL
https://monitor.drh.net/api.php?method=delivery_test_get_info&output=json&username=testman&password=secret123&customer_defined_campaign_id=1234
The response to delivery_test_get_info
will be an array containing the following keys.
Key | Value | Example | Description |
---|---|---|---|
from_address |
string | [email protected] |
The address this message was sent from. |
from_domain |
string | yahoo.com |
The domain component of from_address . |
from_name |
string | Newsletter |
The name component of the From header. |
subject |
string | Your Daily News |
The Subject of this campaign. |
customer_defined_campaign_id |
string | campaign-100 |
Your campaign identifier as sent in the X-CampaignID header. |
pct_inbox |
decimal | 92.1 |
The percentage of this campaign that was received in the inbox. |
pct_bulk |
decimal | 7.9 |
The percentage of this campaign that was received in the bulk folder. |
pct_missing |
decimal | 0 |
The percentage of this campaign that was never received. |
isp_stats |
array | See the example JSON response below | An array containing results from ISPs as defined below. |
spamassassin |
array | See the example JSON response below | An array containing SpamAssassin’s results as defined below. |
The isp_stat
array has the following keys:
Key | Value | Example | Description |
---|---|---|---|
domain |
string | aol.com |
The domain of the test account. |
name |
string | AOL |
The name of the application which hosts the test account. |
category |
string | Global |
The category that GreenArrow Monitor puts this ISP into. |
count_inbox |
integer | 10 |
The number of emails that reached the inbox of the test account. |
count_bulk |
integer | 0 |
The number of emails that reached the bulk folder of the test account. |
count_missing |
integer | 0 |
The number of emails that never reached the test account. |
count_duplicate |
integer | 0 |
The number of emails that were received twice or more. |
count_total |
integer | 10 |
The total number of emails that were sent for this test. |
pct_inbox |
decimal | 100 |
The percentage of emails that reached the inbox. |
pct_bulk |
decimal | 0 |
The percentage of emails that reached the bulk folder. |
pct_missing |
decimal | 0 |
The percentage of emails that were missing. |
The spamassassin
array has the following keys:
Key | Value | Example | Description |
---|---|---|---|
message_id |
integer | 2739462 |
The internal identifier for this message. Not the same as the Message-ID header’s value. |
time_processed |
integer | 1339773195 |
The time that SpamAssassin received this message. Expressed as the number of seconds since the UNIX epoch. |
result |
string | No |
Whether the message was identified as spam. Valid values are Yes , and No . |
score |
string | -2.5 |
The SpamAssassin score. Lower scores are more likely to be sent to the inbox. |
required |
string | 5.0 |
Message scoring below this threshold are sent to the inbox. Message scoring at or above this threshold are sent to the bulk folder. Different SpamAssassin installations use different required values. |
version |
string | SpamAssassin 3.3.2 (2011-06-06) on calvin.drh.net |
The version of SpamAssassin that was used to scan this message. |
rules_matched |
array | See the example JSON response below | An array containing details on how SpamAssassin arrived at its final score. |
_status |
string | done |
Normally done to indicate that testing is complete |
Example JSON Response
delivery_test_get_email_list
Returns a full list of email addresses tested by a campaign, and the results for each email address.
Parameters
Key | Value | Example | Description | Required |
---|---|---|---|---|
campaign_id |
integer | 1234 |
The internal campaign_id of the campaign, as returned by delivery_test_list . |
See below. |
customer_defined_campaign_id |
string | campaign-100 |
Your campaign identifier as sent in the X-CampaignID header. |
See below. |
date |
integer or string | 1341964800 |
The date that the campaign was sent. Used to differentiate between multiple campaigns with the same customer_defined_campaign_id . See this document’s “Date Formats” section for details on formatting. |
No |
This request must be given either the customer_defined_campaign_id
or the campaign_id
of the campaign you are polling on. The date
field will only be used when specifying by customer_defined_campaign_id
.
If there are multiple campaigns with the same customer_defined_campaign_id
, then the one that is closer to the date given is returned. This is helpful because the customer_defined_campaign_id
is not guaranteed to be unique. If the date
parameter is not supplied, then the most recent campaign with a matching customer_defined_campaign_id
is returned.
Example Request URL
https://monitor.drh.net/api.php?method=delivery_test_get_email_list&output=json&username=testman&password=secret123&campaign_id=1234
The response to delivery_test_get_email_list
will be an array with the following keys.
Key | Value | Example | Description |
---|---|---|---|
message_id |
integer | 1234 |
The internal identifier for this message. Not the same as the Message-ID header’s value. |
isp |
string | AOL |
The ISP that hosts this destination. |
address |
string | [email protected] |
The email address of this destination. |
username |
string | test_account_123 |
The username component of the email address. |
domain |
string | yahoo.com |
The domain component of the email address. |
from_address |
string | [email protected] |
The address this message was sent from. |
time_collected |
string | 2011-09-05 T 00:01:29 |
The time at which GreenArrow Monitor retrieved this message from the ISP. |
time_collected_unix |
string | 1339773180 |
A UNIX timestamp representing time_collected . |
subject |
string | Your Daily News |
The subject of this message. |
location |
string | inbox |
The location of the message at the destination, can be: inbox, bulk, missing. |
duplicate |
boolean | false |
A true /false value to tell if this message is a duplicate. |
Example JSON Response
delivery_message_get
Returns data for a specific message, including its content.
Parameters
Key | Value | Example | Description | Required |
---|---|---|---|---|
message_id |
integer | 1422950 |
The id of the message, as returned by delivery_test_get_email_list . |
yes |
Example Request URL
https://monitor.drh.net/api.php?method=delivery_message_get&output=json&username=testman&password=foo123&message_id=1422950
The response to delivery_message_get
will be an array with the following keys.
Key | Value | Example | Description |
---|---|---|---|
campaign_id |
integer | 1234 |
The internal identifier for the campaign. |
message_id |
integer | 456 |
The internal identifier for this message. Not the same as the Message-ID header’s value. |
location |
string | inbox |
The location of the message at the destination, can be: inbox , bulk , missing . |
duplicate |
boolean | false |
A true /false value to tell if this message is a duplicate. |
from_address |
string | [email protected] |
The address this campaign was sent from. |
from_name |
string | Newsletter |
The name component of the From header. |
subject |
string | Your Daily News |
The Subject of this message. |
content |
string | X-Apparently-To: saasd... |
The content of the message, including email headers and body. Lines are separated by the ASCII newline 0x0A . |
Example JSON Response
delivery_seedlist_get
Returns your current deliverability monitoring seedlist.
**Parameters
There are no additional parameters.
Example Request URL
https://monitor.drh.net/api.php?method=delivery_seedlist_get&output=json&username=testaccount&password=mypass
The response to delivery_seedlist_get
will be an array with the following keys.
Key | Value | Example | Description |
---|---|---|---|
seeds |
array | "[email protected]","[email protected]" |
An array of email addresses to use for GreenArrow Monitor’s deliverability monitoring. |
Example JSON Response
Preview (Rendering) Methods
preview_list
Returns a list of recent rendering tests (campaigns).
Parameters
Key | Value | Example | Description | Required |
---|---|---|---|---|
days |
integer | 5 |
The number of days of history to retrieve. | No (default: 14 ) |
Example Request URL
https://monitor.drh.net/api.php?method=preview_list&output=json&username=testman&password=secret123&days=5
The response to preview_list
will be an array with the following keys.
Key | Value | Example | Description |
---|---|---|---|
preview_id |
integer | 1234 |
The internal identifier for the preview. |
date |
string | 2012-01-17 T 12:24:00-0600 |
The date this preview was requested. |
date_unix |
integer | 1339773180 |
A UNIX timestamp representing date . |
from_address |
string | [email protected] |
The address this preview request was sent from. |
from_name |
string | Newsletter |
The name component of the From header. |
from_domain |
string | example.com |
The domain component of from_address . |
subject |
string | Your Daily News |
The Subject of the email. |
Example JSON Response
preview_get_info
Returns the raw data for a rendering test (campaign).
Parameters
Key | Value | Example | Description | Required |
---|---|---|---|---|
preview_id |
integer | 1234 |
The identifier of the preview as returned by the preview_list method. |
yes |
Example Request URL
https://monitor.drh.net/api.php?method=preview_get_info&output=json&username=testman&password=secret123&preview_id=1234
The response to preview_get_info
will be an array with the following keys.
Key | Value | Example | Description |
---|---|---|---|
applications |
array | See the example JSON response below. | A array of applications for this preview, detailed below. |
The applications
array has keys equal to an identifier for each application (e.g. ffyahoo
for Yahoo! Mail in Firefox). Each application’s key value is an array with the following keys.
Key | Value | Example | Description |
---|---|---|---|
platform |
string | Desktop |
A description of the platform this browser runs on. Can be Desktop , Web-based or Mobile devices . |
name |
string | Outlook 2000 |
A long name for this application. |
thumbnail |
array | See the example JSON response below. | An array containing information about the thumbnail image, and whether it was generated. |
images_on |
array | See the example JSON response below. | An array containing information about the Images On view, and whether it was generated. |
images_off |
array | See the example JSON response below. | An array containing information about the Images Off view, and whether it was generated. |
preview_images_on |
array | See the example JSON response below. | An array containing information about the Preview view, and whether it was generated. |
preview_images_off |
array | See the example JSON response below. | An array containing information about the Preview Images Off view, and whether it was generated. |
The thumbnail
, images_on
, images_off
, preview_images_on
and preview_images_off
arrays each contain the following keys:
Key | Value | Example | Description |
---|---|---|---|
url |
string | http://monitor.drh.net/preview_images/65.4a5f27ce6438191e84072f9b.ol2000.images_on.png |
The URL of the image, if it’s been generated. |
status |
string | done |
The current status of the image. Valid values include done and not available . |
Example JSON Response
Legacy Delivery (Inbox) Monitoring Method
campaignGetStats
Returns the raw data for a delivery test (campaign).
We recommend replacing calls to the campaignGetStats
with calls to the delivery_test_get_info
method. campaignGetStats
has been retained for backwards compatibility.
Parameters
Key | Value | Example | Description | Required |
---|---|---|---|---|
customerid |
string | campaign-100 |
Your campaign identifier as sent in the X-CampaignID header. |
yes |
date |
integer or string | 1341964800 |
The date that the campaign was sent. Used to differentiate between multile campaigns with the same customerid . See this document’s “Date Formats” section for details on formatting. |
No |
Example Request URL
https://monitor.drh.net/api.php?method=campaignGetStats&output=json&username=testman&password=secret123&customerid=1234
The response to campaignGetStats
will be an array with the following keys.
Key | Value | Example | Description |
---|---|---|---|
from_address |
string | [email protected] |
The address this message was sent from. |
from_domain |
string | yahoo.com |
The domain component of from_address . |
from_name |
string | Newsletter |
The name component of the From header. |
subject |
string | Your Daily News |
The Subject of this campaign. |
customerid |
string | campaign-100 |
Your campaign identifier as sent in the X-CampaignID header. |
pct_inbox |
decimal | 92.1 |
The percentage of this campaign that was received in the inbox. |
pct_bulk |
decimal | 7.9 |
The percentage of this campaign that was received in the bulk folder. |
pct_missing |
decimal | 0 |
The percentage of this campaign that was never received. |
isp_stats |
array | See the example JSON response below | An array containing results from ISPs as defined below. |
spamassassin |
array | See the example JSON response below | An array containing SpamAssassin’s results as defined below. |
The isp_stat
array has the following keys:
Key | Value | Example | Description |
---|---|---|---|
domain |
string | aol.com |
The domain of the test account. |
name |
string | AOL |
The name of the application which hosts the test account. |
category |
string | Global |
The category that GreenArrow Monitor puts this ISP into. |
count_inbox |
integer | 10 |
The number of emails that reached the inbox of the test account. |
count_bulk |
integer | 0 |
The number of emails that reached the bulk folder of the test account. |
count_missing |
integer | 0 |
The number of emails that never reached the test account. |
count_duplicate |
integer | 0 |
The number of emails that were received twice or more. |
count_total |
integer | 10 |
The total number of emails that were sent for this test. |
pct_inbox |
decimal | 100 |
The percentage of emails that reached the inbox. |
pct_bulk |
decimal | 0 |
The percentage of emails that reached the bulk folder. |
pct_missing |
decimal | 0 |
The percentage of emails that were missing. |
The spamassassin
array has the following keys:
Key | Value | Example | Description |
---|---|---|---|
message_id |
integer | 2739462 |
The internal identifier for this message. Not the same as the Message-ID header’s value. |
time_processed |
integer | 1339773195 |
The time that SpamAssassin received this message. Expressed as the number of seconds since the UNIX epoch. |
result |
string | No |
Whether the message was identified as spam. Valid values are Yes , and No . |
score |
string | -2.5 |
The SpamAssassin score. Lower scores are more likely to be sent to the inbox. |
required |
string | 5.0 |
Message scoring below this threshold are sent to the inbox. Message scoring at or above this threshold are sent to the bulk folder. Different SpamAssassin installations use different required values. |
version |
string | SpamAssassin 3.3.2 (2011-06-06) on calvin.drh.net |
The version of SpamAssassin that was used to scan this message. |
rules_matched |
array | See the example JSON response below | An array containing details on how SpamAssassin arrived at its final score. |
_status |
string | done |
Normally done to indicate that testing is complete. |
Example JSON Response