This is the documentation for the InboxFirst 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.


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:

Key Meaning Example Type
success The API call was successful or not. true or false Boolean
data The object returned by the particular API call, as defined in each section of this document. This will be null if the call failed. Array or Hash
error_code A simple error code to identify what went wrong. This will be null if the call was successful. not_authorized String
error_message A more descriptive message of what went wrong. This will be null if the call was successful. please specify a valid auth_id or auth_key String

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.

error_code Explanation
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 InboxFirst.

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 the created_at field might have the value 2013-03-27T10:41:15-05:00, there will also be a field created_at_epoch which contains the integer value 1364398875.

  • The timezone of all times is the organization timezone.


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.


Important: for compatibility reasons you will be routed to version 1 if no version was specified!


Every request to the InboxFirst 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 InboxFirst 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

Value Description
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

Value Description
active The subscriber is active for receiving email
unsubscribed The subscriber has unsubscribed from this mailing list
scomp InboxFirst has received a spam complaint for this subscriber
bounced InboxFirst received a bounce event for this subscriber
deactivated This subscriber was deactivated by a user of InboxFirst

Custom Field Types

Value Description
text A single line text field
text_multiline A multiline text field
number date An integer value
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 yes or no