SendSage Monitor API

SendSage Monitor API

How to Make API Requests using serialized PHP or JSON

You can make API requests for SendSage 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 SendSage Monitor username.
password string Your SendSage 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 DRH 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 news@example.com 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

[
  {
    "campaign_id":1234,
    "date":"2012-01-07 T 12:02:41-0600",
    "date_unix":1339773180,
    "from_address":"news@example.com",
    "from_name":"Newsletter",
    "from_domain":"example.com",
    "subject":"This Week's News",
    "campaign_id":"abc123"
  }, {
    "campaign_id":1235,
    "date":"2011-12-04 T 12:02:41-0600",
    "date_unix":1339773180,
    "from_address":"weather@example.com",
    "from_name":"Newsletter",
    "from_domain":"example.com",
    "subject":"Your Daily Weather Forecast",
    "campaign_id":"abc456"
  }, {
    "campaign_id":1235,
    "date":"2011-12-04 T 12:02:47-0600",
    "date_unix":1339773180,
    "from_address":"news@example.com",
    "from_name":"Newsletter",
    "from_domain":"example.com",
    "subject":"Some New News",
    "campaign_id":"abc123"
  }
]

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 newsletter@example.com 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 SendSage 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

{
  "success":1,
  "from_address":"customerservice@example.com",
  "from_domain":"example.com",
  "from_name":"Newsletter",
  "subject":"Daily News",
  "customer_defined_campaign_id":"my-newsletter-1",
  "pct_inbox":92.1,
  "pct_bulk":7.9,
  "pct_missing":0,
  "isp_stats": [
    {
      "domain":"aol.com",
      "name":"AOL",
      "category":"Global",
      "count_inbox":"10",
      "count_bulk":"0",
      "count_missing":"0",
      "count_duplicate":"0",
      "count_total":"10",
      "pct_inbox":100,
      "pct_bulk":0,
      "pct_missing":0
    }, {
      "domain":"aol.com",
      "name":"AOL 2",
      "category":"Global",
      "count_inbox":"10",
      "count_bulk":"0",
      "count_missing":"0",
      "count_duplicate":"0",
      "count_total":"10",
      "pct_inbox":100,
      "pct_bulk":0,
      "pct_missing":0
    }, {
      "domain":"att.net",
      "name":"ATT",
      "category":"US",
      "count_inbox":"9",
      "count_bulk":"0",
      "count_missing":"0",
      "count_duplicate":"0",
      "count_total":"9",
      "pct_inbox":100,
      "pct_bulk":0,
      "pct_missing":0
    }
  ],
  "spamassassin":
    {
      "message_id":2739462,
      "time_processed":1341504526,
      "result":"No",
      "score":"-2.5",
      "required":"5.0",
      "version":"SpamAssassin 3.3.2 (2011-06-06) on calvin.drh.net",
      "rules_matched":[
        {
          "area":"RBL: ",
          "rule":"RCVD_IN_RP_CERTIFIED",
          "score":"-3.0",
          "description":"Sender is in Return Path Certified (trusted relay)"
        }, {
          "area":"RBL: ",
          "rule":"RCVD_IN_RP_SAFE",
          "score":"-2.0",
          "description":"Sender is in Return Path Safe (trusted relay)"
        }
      ],
      "_status":"done"
    }
}

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 test_account_123@yahoo.com 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 newsletter@example.com The address this message was sent from.
time_collected string 2011-09-05 T 00:01:29 The time at which SendSage 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

[
  {
    "isp":"AOL",
    "address":"asdf123@aol.com",
    "username":"asdf123",
    "domain":"aol.com",
    "from_address":"support@example.com",
    "time_collected":"2011-09-05 T 00:01:29-0600",
    "time_collected_unix":1339773180,
    "subject":"Your Daily News",
    "duplicate":false
  }, {
    "isp":"Yahoo",
    "address":"asdf123@yahoo.com",
    "username":"asdf123",
    "domain":"yahoo.com",
    "from_address":"support@example.com",
    "time_collected":"2011-09-05 T 00:02:29-0600",
    "time_collected_unix":1339773180,
    "subject":"Your Daily News",
    "duplicate":false
  }, {
    "isp":"Comcast",
    "address":"qwer123@comcast.com",
    "username":"qwer123",
    "domain":"comcast.com",
    "from_address":"support@example.com",
    "time_collected":"2011-09-05 T 00:03:29-0600",
    "time_collected_unix":1339773180,
    "subject":"Your Daily News",
    "duplicate":false
  }
]

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 news@example.com 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

{
  "campaign_id":716,
  "message_id":143422950,
  "seed_id":39432,
  "location":"inbox",
  "duplicate":false,
  "time_collected":"2011-12-31 T 19:33:31-0600",
  "time_collected_unix":1339773180,
  "from_address":"news@example.com",
  "from_name":"Newsletter",
  "subject":"Your Daily News",
  "content":"X-Apparently-To: saasdfasdf@yahoo.com via 98.168.85.137; Mon, 05 Sep 2011 00:01:26 -0700\nX-YahooFilteredBulk: 14.17.34.24\nReceived-SPF: pass (domain of example.com designates 14.17.34.24 as permitted sender)\nX-Originating-IP: [14.17.34.24]\nAuthentication-Results: mta1067.mail.sk1.yahoo.com  from=example.com; domainkeys=pass (ok);  from=example.com; dkim=pass (ok)\nReceived: from 127.0.0.1  (HELO smtp1-1.example.com) (14.17.34.24)\n  by mta1067.mail.sk1.yahoo.com with SMTP; Mon, 05 Sep 2011 00:01:26 -0700\nReceived: (qmail 8253 invoked by uid 48); 5 Sep 2011 07:01:26 -0000\nDKIM-Signature: v=1; a=rsa-sha1; c=relaxed\/relaxed;\n\td=example.com; s=default; h=Comment:DomainKey-Signature:\n\tDate:Message-ID:To:Subject:From:Reply-To:MIME-Version:\n\tContent-Type:Content-Transfer-Encoding; bh=asdf123; b=1234123412341234\nComment: DomainKeys? See http://antispam.yahoo.com\/domainkeys\nDomainKey-Signature: a=rsa-sha1; q=dns; c=nofws;\n  s=default; d=example.com;\n  b=1234asdfgasdfgasdfasdfasdfzxcvzxcv  ;\nDate: 5 Sep 2011 07:01:26 -0000\nMessage-ID: <12345.qmail@example.com>\nTo: sagepawnasdf@yahoo.com\nSubject: Your Daily News\nFrom: \"Daily News\" <news@example.com>\nReply-To: news@example.com\nMIME-Version: 1.0\nX-Mailer-LID: 17\nX-Mailer-SID: 12726\nX-Mailer-Sent-By: 1\nX-Mailer-Info: asdfasdf123\nX-Mailer-Seed: oaijsdfoaisjdf019283\nContent-Type: text\/plain; charset=\"UTF-8\"\nContent-Transfer-Encoding: quoted-printable\n\nHello there,\nHere's your daily headlines!\n\n\n\n"
}

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&amp;output=json&amp;username=testaccount&amp;password=mypass

The response to delivery_seedlist_get will be an array with the following keys.

Key Value Example Description
seeds array "aaa@yahoo.com","zzz@hotmail.com" An array of email addresses to use for SendSage Monitor’s deliverability monitoring.

Example JSON Response

{
  "seeds":[
    "aaaaaa@aaaaaa.reference.drh.net",
    "aaaaaa-reference2@aaaaaa.reference.drh.net",
    "zzzzzz-reference3@zzzzzz.reference.drh.net",
    "zzzzzz-reference4@zzzzzz.reference.drh.net"
  ]
}

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&amp;output=json&amp;username=testman&amp;password=secret123&amp;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 news@example.com 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_id":65,
    "date":"2012-03-27 T 09:59:13-0600",
    "date_unix":1332856753,
    "from_address":"newsletter@example.com",
    "from_domain":"example.com",
    "from_name":"Newsletter",
    "subject":"demo"
  }, {
    "preview_id":62,
    "date":"2012-02-03 T 05:05:29-0600",
    "date_unix":1328306729,
    "from_address":"newsletter@example.com",
    "from_domain":"example.com",
    "from_name":"Newsletter",
    "subject":"My Newsletter"
  }
]

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&amp;output=json&amp;username=testman&amp;password=secret123&amp;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

{
  "applications": {
    "ol2000": {
      "platform":"Desktop",
       "name":"2Outlook 2000",
       "thumbnail": {
         "url": null,
         "status":"not available"
       },
       "images_on": {
         "url":"http://monitor.drh.net\/preview_images\/65.4a5f27ce6438123123123.ol2000.images_on.png",
         "status":"done"
       },
       "images_off": {
         "url":null,
         "status":"not available"
       },
       "preview_images_on": {
         "url":"http://monitor.drh.net\/preview_images\/65.123cb12391e82f9b.ol2000.preview_images_on.png",
         "status":"done"
       },
       "preview_images_off": {
         "url":null,
         "status":"not available"
       }
     },
     "ol2002": {
       "platform":"Desktop",
       "name":"2Outlook 2002\/XP",
       "thumbnail": {
         "url":null,
         "status":"not available"
       },
       "images_on": {
         "url":"http://monitor.drh.net\/preview_images\/65.4a5f244212341072f9b.ol2002.images_on.png",
         "status":"done"
       },
       "images_off": {
         "url":null,
         "status":"not available"
       },
       "preview_images_on": {
         "url":"http://monitor.drh.net\/preview_images\/65.4a5f25431234924072f9b.ol2002.preview_images_on.png",
         "status":"done"
       },
       "preview_images_off": {
         "url":null,
         "status":"not available"
       }
     }
  }
}

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&amp;output=json&amp;username=testman&amp;password=secret123&amp;customerid=1234

The response to campaignGetStats will be an array with the following keys.

Key Value Example Description
from_address string newsletter@example.com 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 SendSage 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

{
  "success":1,
  "from_address":"customerservice@example.com",
  "from_domain":"example.com",
  "from_name":"Newsletter",
  "subject":"Daily News",
  "customer_defined_campaign_id":"my-newsletter-1",
  "pct_inbox":92.1,
  "pct_bulk":7.9,
  "pct_missing":0,
  "isp_stats": [
    {
      "domain":"aol.com",
      "name":"AOL",
      "category":"Global",
      "count_inbox":"10",
      "count_bulk":"0",
      "count_missing":"0",
      "count_duplicate":"0",
      "count_total":"10",
      "pct_inbox":100,
      "pct_bulk":0,
      "pct_missing":0
    }, {
      "domain":"aol.com",
      "name":"AOL 2",
      "category":"Global",
      "count_inbox":"10",
      "count_bulk":"0",
      "count_missing":"0",
      "count_duplicate":"0",
      "count_total":"10",
      "pct_inbox":100,
      "pct_bulk":0,
      "pct_missing":0
    }, {
      "domain":"att.net",
      "name":"ATT",
      "category":"US",
      "count_inbox":"9",
      "count_bulk":"0",
      "count_missing":"0",
      "count_duplicate":"0",
      "count_total":"9",
      "pct_inbox":100,
      "pct_bulk":0,
      "pct_missing":0
    }
  ],
  "spamassassin":
    {
      "message_id":2739462,
      "time_processed":1341504526,
      "result":"No",
      "score":"-2.5",
      "required":"5.0",
      "version":"SpamAssassin 3.3.2 (2011-06-06) on calvin.drh.net",
      "rules_matched":[
        {
          "area":"RBL: ",
          "rule":"RCVD_IN_RP_CERTIFIED",
          "score":"-3.0",
          "description":"Sender is in Return Path Certified (trusted relay)"
        }, {
          "area":"RBL: ",
          "rule":"RCVD_IN_RP_SAFE",
          "score":"-2.0",
          "description":"Sender is in Return Path Safe (trusted relay)"
        }
      ],
      "_status":"done"
    }
}
 "Best Practices"
"Identifying Campaigns"