Getting Started with our API


Authentication

The TouchBasePro API currently supports authentication via an API key.

API Key to authenticate

API key authentication is more accessible and easy to work with. It's a great option if you are looking to test whether a certain call or snippet of code will work as expected, or if you are a company just looking to build your own internal integration to work with.


Authenticating with an API key

You may also use an API key and HTTP Basic Authentication to authenticate API requests. You can get your API key from the Overview page when logged into your TouchBasePro account. When you make an API request you provide your API key as the username and the password portion can be blank or a dummy value, as it is not used for authentication.

Your browser should then display a dialog requesting that you enter a username and password. Enter your API key (e.g. "dklkmwlmkdy7qwd98y98y98y8d68d9") in the username field. You can leave the password field blank or enter a dummy value like 'x'. If your request is authenticated, you should then be delivered the JSON response.

You can also make API calls from the command line using a tool like cURL (which will also allow you to make requests which require the use of the POST, PUT, and DELETE verbs).

To get the basic details of a subscriber list with the id (a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1) in JSON format using cURL, you'd do the following:

curl -u "dklkmwlmkdy7qwd98y98y98y8d68d9:x" https://emailapi.touchbasepro.com/api/v3.1/lists/a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1.json 
Response You should receive a HTTP response similar to:

{
    "ConfirmedOptIn": false,
    "Title": "Website Subscribers",
    "UnsubscribePage": "http://www.example.com/unsubscribed.html",
    "UnsubscribeSetting": "AllClientLists",
    "ListID": "a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1",
    "ConfirmationSuccessPage": "http://www.example.com/joined.html"
}

Your List ID

You can find any list ID by heading into any list in your account and clicking the "change name/type" link below your list name.


Input & Output

Input and output are currently supported in XML and JSON. When making an API request, you must specify both the input data format in the body (only relevant to POST and PUT requests), and the output data format you expect in the response. The format is specified using either a .json or .xml portion in the route, as illustrated below.

Note: All /transactional endpoints are JSON only. The rest of the API will return XML by default so we recommend including Accept: application/json in your header, or append all requests with .json.

When providing input you must ensure that your XML is well-formed or your JSON complies with the syntax, paying particular attention to character and entity encoding with both formats. Any input provided in the query string of any request should be url-encoded. An example of where this is required is the request for getting a subscriber's details, which takes an email address as a query string parameter.


Providing Input

Example Updating a list

To create a list using XML as the input data format, you would make a HTTP PUT request:

PUThttps://emailapi.touchbasepro.com/api/v3.1/lists/{listid}.xml
<List>
    <ConfirmedOptIn>false</ConfirmedOptIn>
    <ConfirmationSuccessPage>http://www.example.com/joined.html</ConfirmationSuccessPage>
    <Title>Website Subscribers</Title>
    <UnsubscribePage>http://www.example.com/unsubscribed.html</UnsubscribePage>
    <UnsubscribeSetting>AllClientLists</UnsubscribeSetting>
    <AddUnsubscribesToSuppList>true</AddUnsubscribesToSuppList>
    <ScrubActiveWithSuppList>true</ScrubActiveWithSuppList>
</List>

To create a list using JSON as the input data format, you would make a HTTP PUT request:

PUThttps://emailapi.touchbasepro.com/api/v3.1/lists/{listid}.json
{
    "Title": "Website Subscribers",
    "UnsubscribePage": "http://www.example.com/unsubscribed.html",
    "UnsubscribeSetting": "AllClientLists",
    "ConfirmedOptIn": false,
    "ConfirmationSuccessPage": "http://www.example.com/joined.html",
    "AddUnsubscribesToSuppList": true,
    "ScrubActiveWithSuppList": true
}

Getting Output

Example Getting the basic details of a list

To get the details of the list in XML format, you would make a HTTP GET request using the xml extension. You'll receive a response in XML format similar to the following:

GEThttps://emailapi.touchbasepro.com/api/v3.1/lists/{listid}.xml

<?xml version="1.0" encoding="utf-8"?>
<List>
    <ConfirmationSuccessPage>http://www.example.com/joined.html</ConfirmationSuccessPage>
    <ConfirmedOptIn>false</ConfirmedOptIn>
    <ListID>a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1</ListID>
    <Title>Website Subscribers</Title>
    <UnsubscribePage>http://www.example.com/unsubscribed.html</UnsubscribePage>
    <UnsubscribeSetting>AllClientLists</UnsubscribeSetting>
</List>

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

To get the details of the list in JSON format, you would make a HTTP GET request using the json extension. You'll receive a response in JSON format similar to the following:

GEThttps://emailapi.touchbasepro.com/api/v3.1/lists/{listid}.json

{
    "ConfirmedOptIn": false,
    "Title": "Website Subscribers",
    "UnsubscribePage": "http://www.example.com/unsubscribed.html",
    "UnsubscribeSetting": "AllClientLists",
    "ListID": "a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1",
    "ConfirmationSuccessPage": "http://www.example.com/joined.html"
}

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


Response status codes

The responses returned by the API are accompanied by meaningful HTTP status codes which represent the status of the request. Here's the general approach we take when returning responses:

Success

GET requests will return a "200 OK" response if the resource is successfully retrieved.
POST requests which create a resource we will return a "201 Created" response if successful.
POST requests which perform some other action such as sending a campaign will return a "200 OK" response if successful.
PUT requests will return a "200 OK" response if the resource is successfully updated.
DELETE requests will return a "200 OK" response if the resource is successfully deleted.

Errors

If you attempt to authenticate with an invalid API key, you'll receive a "401 Unauthorized" response like this:

Example response body:401 Unauthorized JSON XML
{
	"Code": 100,
	"Message": "Invalid API Key"
}

And if you attempt to use an invalid ID for a resource, you'll also receive a "401 Unauthorized" response. For example, if you specified a client ID of a client which doesn't belong to you, you'd receive the following response:

Example response body:401 Unauthorized JSON XML
{
	"Code": 102,
	"Message": "Invalid ClientID"
}

If there is an error in your input, you'll receive a "400 Bad Request" response, with details of the error.

Example response body:400 Bad Request JSON XML
{
	"Code": 250,
	"Message": "List title must be unique within a client"
}

If you attempt to request a resource which doesn't exist, you'll receive a "404 Not Found" response.

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

If you attempt to use an agency resource as a non-agency customer, you'll receive a "403 Forbidden" response. For example, if you tried to create or delete a list from another clients, you'd receive the following response:

Response body:403 Forbidden JSON XML
{
	"Code": 403
}

If an unhandled error occurs on the API server for some reason, you'll receive a "500 Internal Server Error" response.

Response body:500 Internal Server Error JSON XML
{
	"Code": 500,
	"Message": "Sorry, we've run into a problem.
	Please try again or contact support"
}

Making things Pretty

You can add pretty=true to the query string of any request if you want the output to be indented in a nice human-readable format.

So, the following request without the pretty parameter:

https://emailapi.touchbasepro.com/api/v3.1/lists/a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1.json

would produce output similar to:

{"ConfirmedOptIn": false,"Title": "Website Subscribers","UnsubscribePage": "http://www.example.com/unsubscribed.html","UnsubscribeSetting": "AllClientLists","ListID": "a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1","ConfirmationSuccessPage": "http://www.example.com/joined.html"}

And, the following request including pretty=true:

https://emailapi.touchbasepro.com/api/v3.1/lists/a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1.json?pretty=true

would produce output similar to:

{
    "ConfirmedOptIn": false,
    "Title": "Website Subscribers",
    "UnsubscribePage": "http://www.example.com/unsubscribed.html",
    "UnsubscribeSetting": "AllClientLists",
    "ListID": "a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1",
    "ConfirmationSuccessPage": "http://www.example.com/joined.html"
}

Rate Limiting

All /transactional endpoints are subject to API rate limiting. As part of every response, the HTTP headers will show your current rate limit status.

Headers

  • X-RateLimit-Limit The maximum number of requests you can make per minute.
  • X-RateLimit-Remaining The number of requests remaining in the current rate limit window.
  • X-RateLimit-Reset The number of seconds before the rate limit is reset.
Response If you go over the rate limit you will receive an error response:
HTTP/1.1 429 Forbidden
Date: Tue, 20 Jan 2014 14:50:41 GMT
Status: 429 Forbidden
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 348
{
    "Code": 429,
    "Message": "Rate limit exceeded"
}

If you're continually exceeding your rate limit, please contact us to request a higher rate limit for your application.

Web accelerated by IISpeed - Page Speed optimization by Google for Microsoft IIS and ASP.NET