Home > INinbox API

INinbox API

If you need to integrated our platform with your own application, blog, software or CMS then the
INinbox Open API opens up a world of possibilities.

There is nothing that you can't do or that can't be build around our application. If you find anything missing -
anything at all - please contact support right away and our technical team will solve it for you!

Interested in partnering with us? Click here to contact us!

Broadcast >

Broadcast functionality and reporting. More

Contacts >

Manage and update contacts. More

General >

Get details of General data. More

Samples & Wrappers >

We currently supply wrappers for PHP. More

Webhooks >

Manage Webhooks. More
 

List >

Add, remove and manage lists. More

Account >

Core information related to your account. More

Member >

Manage and update member's data. More

Easy INtegrations

    
Our prebuilt integrations More
 

Getting started with our API

Generate an API key

With the INinbox API you can use an API key and HTTP Basic Authentication to authenticate API requests. You can generate your API key from the Account Settings >> API page in your INinbox member account.
When you make an API request you enter your API key as the username and simply enter nothing as password or you can use a dummy value, as it is not needed for authentication.

To get an example of an authentication with an API key, you can make any GET request to the API directly in the adress portion of your web browser. Let's do one example together, assume you want to generate a list of all your contacts in JSON format, then you would enter the URL below into your address bar:

http://api.ininbox.com/v1/lists/list.json

A dialog requesting a username and password should show up. Enter your API key (e.g. "k9Cb7Lh0Cn0Bb9Vq7Aasa") as the username. Don't enter anything as password or enter a dummy value like 'IN'. The JSON response should should be returned if your request is succesfully authenticated.

Of course you can make API calls from the command line as well with a tool like cURL.

To generate a preview of your lists in JSON format using the cURL tool, the input would look like:

curl -u "e2Uq3Yk5Jk4Vf2Ov3Ma3:IN" http://api.ininbox.com/v1/lists/list.xml
 
  RESPONSE   You should receive a HTTP response similar to:
{ "TotalNumberOfRecords": "2", "RecordsOnThisPage": 2, "PageNumber": 1, "PageSize": 1, "ResultsOrderedBy": "date", "OrderDirection": "asc", "Results": [ { "ListID": 212, "Title": "List 70103", "ConfirmedOptIn": false, "CreatedDate": "2013-12-05 12:24:59", "Status": "Active" }, { "ListID": 211, "Title": "List 70202", "ConfirmedOptIn": true, "CreatedDate": "2013-12-05 12:21:52", "Status": "Active" } ] }
 
Your ListID

You can get your listID's through the "Getting Lists" method or by going into any list in your account. You will find your listID on top of the page with list settings.

 
Input & Output

Currently the INinbox API supports Input and output in XML and JSON. When making any request, a data format must be specified in the route. This data format is valid for the input (only POST and PUT requests) you provide in the body of the request and also represents the format in which you wish to get the output in the body of the response. Use either a .json or .xml portion in the route to specify a format, for examples see below

It is really important that you provide your XML in a well-formed format or that your JSON abides to the standard syntax rules with a strong focus on character and entity encoding. When you do a request ensure any input in the query is url-encoded.

Providing Input

Example Creating a list

Make a HTTP POST request, like this, to generate a list using XML as the input format,

 
  POST   http://api.ininbox.com/v1/lists/create.xml
<?xml version="1.0" encoding="utf-8"?> <List> <Title>Website Subscribers</Title> <ConfirmedOptIn>False</ConfirmedOptIn> <CompanyName>Company 1</CompanyName> <Address>111 ABC Park</Address> <City>City Point</City> <State>NJ</State> <Country>NL</Country> <Zip>9752PG</Zip> </List>
 

Make a HTTP POST request, like the one below, to generate a list using JSON as the input format,

 
  POST   http://api.ininbox.com/v1/lists/create.json
{ "Title":"Website Subscribers", "ConfirmedOptIn":"False", "CompanyName":"Company 2", "Address":"111 ABC Park", "City":"City Point", "State":"NJ", "Country":"NL", "Zip":"9752PG" }

Getting Output

Example Getting a list of contacts

If you would like to generate a list of your contacts in XML format, a HTTP GET request with the xml extension shoud be used. The expected response will be given to you in XML format, and will look like:

 
  GET   http://api.ininbox.com/v1/contacts/list.xml
<?xml version="1.0" encoding="utf-8"?> <PagedResult> <TotalNumberOfRecords>2</TotalNumberOfRecords> <RecordsOnThisPage>2</RecordsOnThisPage> <PageNumber>1</PageNumber> <PageSize>1</PageSize> <ResultsOrderedBy>date</ResultsOrderedBy> <OrderDirection>desc</OrderDirection> <Results> <Contact> <ContactID>36614</ContactID> <FirstName>APIF123</FirstName> <LastName>APIL123</LastName> <FullName>APIF123 APIL123</FullName> <Email>API123aaa@test.com</Email> </Contact> <Contact> <ContactID>36598</ContactID> <FirstName>APIF1</FirstName> <LastName>APIL2</LastName> <FullName>APIF1 APIL2</FullName> <Email>custom0078@fields.com</Email> </Contact> </Results> </PagedResult>
 

The Content-Type header of the response will be set to "application/xml; charset=utf-8".

If you would like to generate a list of your contacts in JSON format, a HTTP GET request with the JSON extension shoud be used. The expected response will be given to you in JSON format, and will look look like:

 
  GET   http://api.ininbox.com/v1/contacts/list.json
{ "TotalNumberOfRecords": 1094, "RecordsOnThisPage": 10, "PageNumber": 1, "PageSize": 110, "ResultsOrderedBy": "date", "OrderDirection": "desc", "Contact": [ { "ContactID": 36614, "FirstName": "APIF123", "LastName": "APIL123", "FullName": "APIF123 APIL123", "Email": "API123aaa@test.com" }, { "ContactID": 36598, "FirstName": "APIF1", "LastName": "APIL2", "FullName": "APIF1 APIL2", "Email": "custom0078@fields.com" } ] }
 
General response status codes

The following general HTTP status codes can be returned by the type of requests you make . If there are other specific status codes available you will be able find them with the matching api requests individually.

Succes status codes

GetWhen the data is successfully retrieved, your requests will return a "200 OK" response.
Post A "201 Created" response will be returned when a requests which creates for example a list is successful.
Post A "200 OK" response means another action is successful. Like making requests which performs sending or scheduling a broadcast.
Put If a resource is successfully updated, your put requests will return a "200 OK" response
Delete requests will return a "200 OK" response if the resource is successfully deleted.

Error status codes

Trying to authenticate while using an invalid API key, receives a "401 Unauthorized" response like this:

  Example response body   401 Unauthorized
{ "Code": 1000, "Message": "Invaid API key or API key not found", }

When you are trying to access an API call and your API access limit is exceed the maximum number of call limit in a day, receives a "403 Forbidden" response like this:

  Example response body   403 Forbidden
HTTP/1.1 403 Forbidden X-RateLimit-Limit: 60 X-RateLimit-Remaining: 0 X-RateLimit-Reset: 1377013 { "Code": 1014, "Message": "API rate limit exceeded.", }

The headers tell you everything you need to know about your current rate limit status:

  • X-RateLimit-Limit: The maximum number of requests that the member is permitted to make per day.
  • X-RateLimit-Remaining: The number of requests remaining in the current rate limit window.
  • X-RateLimit-Reset: The time at which the current rate limit window resets in UTC epoch seconds.

If you try to access a resource with an invalid ID, you'll also receive a "401 Unauthorized" response. Trying to access a contact with a contact ID that is owned by another INinbox member , would get you a response like:

  Example response body   401 Unauthorized
{ "Code": 3200, "Message": "Invalid ContactID", }

A "400 Bad Request" response will show If there is an error in your input. We wil also return the details of the error.

  Example response body   400 Bad Request
{ "Code": 2001, "Message": "Same list title can not be twice in your account", }

When a resource doesn't exist, but you still attempt to request it, you'll receive a "404 Not Found" response.

  Example response body   404 Not Found
{ "Code": 404, "Message": "We couldn't find the resource you're looking for. Please check the documentation and try again", }

A "405 Method Not Allowed" response . Usually this means you used the wrong HTTP method (GET when you should POST, etc)

  Example response body   405 Method Not Allowed
{ "Code": 405, "Message": "Invalid Request Method. Usually this means you used the wrong HTTP method (GET when you should POST, etc)", }

A "500 Internal Server Error" response is returned if an unhandled error occurs on the API server for some reason.

  Example response body   500 Internal Server Error
{ "Code": 500, "Message": "Sorry, we've run into an issue. Please try again or contact INspired support", }


© 2014 All Rights Reserved. INInbox - Professional Email Marketing Services ® Terms and Conditions - Privacy Policy - Anti-spam Policy - Email Marketing Pledge