Introduction
- Table of Contents
- Formatting
- Versions
- Authentication
- Enumerated Values
This is the documentation for the SendSage Studio API. If you have additional questions about the API, or feel that you’ve encountered a bug, please don’t hesitate to contact us at our support address.
Interactions with this API are accomplished over HTTP. On POST and PUT requests, JSON is expected as the body of the request. All API calls reply with JSON.
Formatting
JSON Formatting
The JSON included as examples in this document has been nicely formatted for viewing. Neither the JSON expected as input into the API nor the JSON returned by it will be formatted this way.
Return Values
All API requests will return a JSON hash with the following keys:
success boolean |
The API call was successful or not. |
data array or hash |
The object returned by the particular API call, as defined in each section of this document. This will be null if the call failed. |
error_code string |
A simple error code to identify what went wrong. This will be null if the call was successful. |
error_message string |
A more descriptive message of what went wrong. This will be null if the call was successful. |
Error Response
Here’s an example of an error message returned by this API.
{
"data": null,
"error_code": "validation_failed",
"error_message": "name cannot be blank",
"success": false
}
Here are all of the error codes that Studio can return. See the error_message value for more information on the specific response.
validation_failed |
The client tried to create or update a record into an invalid state. |
invalid_request |
The request could not be processed. |
requested_too_many |
The client requested too many records at once. |
not_found |
The requested record could not be found. |
multiple_records_found |
The request found multiple records instead of one. |
internal_error |
The request caused an error within SendSage Studio. |
Dates and Times
-
Times are passed to the API in ISO 8601 date/time format:
YYYY-MM-DDThh:mm:ss-ZZ:ZZ
2013-03-27T10:41:15-05:00 -
A date (with no time) can be passed to the API, and is returned, in the following format:
YYYY-MM-DD
2010-03-30 -
Times are returned by the API as both an integer number of seconds since the UNIX epoch, and in ISO 8601 date/time format.
-
All fields that are interpreted as a time also have a corresponding
_epoch
field with the integer number of seconds since the UNIX epoch. For example, on a subscriber thecreated_at
field might have the value2013-03-27T10:41:15-05:00
, there will also be a fieldcreated_at_epoch
which contains the integer value1364398875
. -
The timezone of all times is the organization timezone.
Versions
During evolving the programmatic interface of API calls may change. To keep things backward compatible, Studio uses API versioning. Each request you send should explicitly specify the version of API you are targeting. There are two ways to achieve that:
-
You can specify version within request headers using the
X-Version
header.X-Version: 2
-
You can specify version within request path using the path component
v2
./ga/api/v2/campaigns
Important: for compatibility reasons you will be routed to version 1 if no version was specified!
Authentication
Every request to the SendSage Studio API must be authenticated. This is done via the Authorization
HTTP header in the request, as described below.
API Keys
Organization administrators may create API keys from their organization’s page. To find that page, hover over Admin
in the top navigation menu, then select My Organization
. See the API Keys
section on that screen. The Key
column contains the value needed for authentication. The key will initially be obscured behind a link; clicking reveal
will display the key.
Authorization Header
The Authorization
header must be included in every call to the SendSage Studio API.
Authorization: Basic <Data>
The <Data>
portion of this header should be the Key
value as shown after clicking reveal
on the Organization page.
Thus, for that example, our header would be the following.
Authorization: Basic MTowYTc0ZWQxM2ZjMTEyYTUwZTZkZjY3NDc5MDcyZjdiZDJiNDg1YzI1
Enumerated Values
Automatic Winner Selection Metrics
opens_unique |
The number of unique opens |
clicks_unique |
The number of unique clicks |
opens_total |
The total number of opens, unique and non-unique |
clicks_total |
The total number of clicks, unique and non-unique |
click_to_open_rate |
The ratio of unique clicks to unique opens |
Subscriber Statuses
active |
The subscriber is active for receiving email |
unsubscribed |
The subscriber has unsubscribed from this mailing list |
scomp |
SendSage Studio has received a spam complaint for this subscriber |
bounced |
SendSage Studio received a bounce event for this subscriber |
deactivated |
This subscriber was deactivated by a user of SendSage Studio |
Custom Field Types
text |
A single line text field |
text_multiline |
A multiline text field |
number |
An integer value |
date |
A specific day with month, day, and year |
day_of_year |
A month and day pairing, no year |
select_single_dropdown |
A dropdown list of options, one option can be selected at a time |
select_single_radio |
Radio boxes of options, one option can be selected at a time |
select_multiple_checkboxes |
A list of options as checkboxes, multiple options can be selected at a time |
boolean |
A value that can be |