GetResponse REST Web Service Interface

GetResponse API gives you basically the same functionality as in our web panels - you can perform the same set of actions: manage campaigns, newsletters, gather statistics and more (and yes we have segments in here!).

API Endpoint

Api endpoint (or base url) is always the same for all retail users and looks like follows:

https://api.getresponse.com/v3

The only thing to remember is that the last part of it (v3 in this case) is the version number of our API. If in the future we introduce some backward incompatible changes we will increment our API version to give you time to migrate from v3 to (let's say) v4. But don't worry we will keep stable version for a long time and most of future updates will be backward compatible.

GetResponse MAX platform

For GetResponse MAX platform users endpoint looks different. There are two different url's and any GetResponse MAX user who wants to connect to our api should contact his account manager and which one he should use.

  • https://api3.getresponse360.pl/v3
  • https://api3.getresponse360.com/v3

Authentication

All request you want to send to our API must contain authentication information. For example, if your api-key is: 84fsne83yrths947r6sfgg7w4he8, then the custom authentication header should look like:

X-Auth-Token: api-key 84fsne83yrths947r6sfgg7w4he8

For security reasons, unused API keys expire after 90 days. When that happens, you’ll need to generate a new key to use our API.

For more detailed information, mobile authentication and GetResponse MAX platform authentication please, go to our authentication page

Basics

This is REST API, all request follows REST rules in terms of resource naming convention, use of HTTP method as action description and use of custom headers to convey additional infomration.

In order to correctly configure your app you need to remember couple of things.

Methods (HTTPS)

We accept 3 methods GET, POST and DELETE. Every POST request MUST HAVE Content-Type header. Currently we accept only 'application/json' content-type

GET if to obtain information. There should not be any "body" data sent with that request. This will not trigger error, but we just simply don't look there in GET request. Only query string parameters ale allowed. This request will never change anything, you can call it as many times as you want. It is called that GET is IDEMPOTENT request.

POST is to add new or modify existing information. If request url doesn't contain resource ID then we will treat that as new data that must be inserted. If you want to modify existing data you need to specify an ID in the Rrequest URL (like POST /contacts/hg5fF). POST is NOT IDEMPOTENT, you need to be carefull to not send the same request twice...

DELETE is only to remove infomration. As a general rule we do not allow to add any "body" data to that type of request nor we allow any query string. This should be just simply DELETE /contacts/hg5fF.

Resources and Representations

We present data as JSON strings. Those information are named "representation" of a "resource". Each url in our API represents an "resource".

Each representation has it's ow unique ID - naming convention is very easy: ID of a newsletters is called newsletterId :). We stick to json camelCase for field names in json data. When you call GET /newsletters/V we will return json data which represents a resource called "newsletter" where it's ID is equal to 'V'. 

When you call GET /newsletters we will return an Collection of resources. This is simply an list of resources representations presented as an json array. You need to remember that in a collection we could ommit some of the fileds that are there in single resource. You should treat collection as a brief information of a resource not a full package :).

When you call POST /newsletters you need to send to us the same structure of json-encoded representation of a newsletter resource. This is very important! If you change name of a field, add some new fields of ommit some of the mandatory fields we will return 400 response with special "error" resource which will contain all validation errors that we discovered in your request. Sometimes you can ommit the field (if it isn't mandatory), but if you set some field with empty value we will treat this as normal and simply set this value to empty string or null. If you don't want to modify some field just don't include it in json representation.