This document describes the Carma public API and how to get started trying it out. Readers are assumed to have some familiarity with Carma’s graphical interface.

The API uses the REST methodology. A brief overview of RESTful web services can be found here:

http://net.tutsplus.com/tutorials/other/a-beginners-introduction-to-http-and-rest/

About the API

Documentation

Carma uses a third-party library called Swagger to document the REST API. This documentation is built based on the actual code and this should ensure that the documentation will always be up to date. There will be no printed version of the API; the version that is accessible via the link is the latest and current version.

Online Resources

You will find the online version of the API at:

http://www<server>.carmamail.com/mail/swagger

If you have user credentials for Carma you can actually access and update your data using the methods described on the swagger page.

In order to do this you must use the swagger page on the server your account is on, I.e. if you normally log on to Carma using the URL: http://www2.carmamail.com/carma you can access your data from the URL http://www2.carmamail.com/mail/swagger.

Please note that this is your live data so any updates you make will alter settings for other users of your account so use POST/PUT and DELETE with care.

Evolution of the API

We will strive to keep the API backward compatible. This applies to all API calls that are not explicitly marked as draft or FOR INTERNAL USE ONLY in the Swagger documentation. This means that:

Resource URIs not will not change
Names of data fields in message body requests and responses will not change
Data fields in message body requests and responses will not be removed
New optional fields in message body requests and responses may be added in the future. Integrating systems should take this account, particularly when consuming responses from the REST API.
New resources will be added as new functionality is made publicly available
If incompatible changes are required in existing resources, the old ones will still be left available, unless the conditions under 7 apply.
In some very unusual cases, internal changes in the system may render existing resources obsolete or insufficient for the task they were originally intended. In these cases the original resource will be left in place, but will be modified to return the HTTP response code 410 (Gone), with a response body including information on the reason.

Customer Id

You must always include your customerId when calling a Carma resource .Your customer id can be found in the header when you log in to Carma if you are using Carma 6. On the account below the id is 5004.

If you use Carma 7 you can find your customerid in the botom of the lefthand menu, in this case 11115:

Syntax

For most resources there are 5 methods you can call; get all, get one, create one, update one and delete one The syntax is mostly the same for all resources so you should be able to pick up the general idea pretty quick.

The URI structure generally looks like this:

<server>/rest/{customerid}/<resource>/[{id}]

server: https://www<x>.carmamail.com where X is the number of your server

customerId

Media Type

All data supplied to and received from the REST API uses the application/json media type. To ensure full compatibility, please make sure that:

All GET requests include the header

Accept: application/json

All PUT and POST request include the following headers:

Accept: application/json
Content-Type: application/json

All data sent to the API is expected to be in the standard application/json charset UTF-8, unless explicitly stated otherwise as a charset parameter in the Content-Type header. All data sent as responses from the API will be in the UTF-8 charset.

Types of Requests

Get All

To get all data you issue a GET reqest without id, e.g.

GET https://www<server>.carmamail.com/rest/<customerId>/projects

Accept: application/json

Get One

To get one data you issue a GET reqest with an id, e.g.

GET https://www<server>.carmamail.com/rest/<customerId>/projects/<projId>

Accept: application/json

Create One

To create a new data you will issue a POST request without id. Usually creation of a new entity will require data for the entity to be included in the message body, e.g.:

POST https://www<server>.carmamail.com/rest/<customerId>/projects

Accept: application/json

Content-Type: application/json

Content-Length: …

Update One

To update one data you issue a PUT request with id and the data required to be used for updating the entity:

PUT https://www<server>.carmamail.com/rest/<customerId>/projects/<projId>

Accept: application/json

Content-Type: application/json

Content-Length: …

Delete one

To delete you issue a DELETE request with an id, i.e.

DELETE https://www<server>.carmamail.com/rest/<customerId>/projects/<projId>

Testing Requests

You can test a request directly in the Swagger interface by entering your credentials, customer id and other data needed for the method.

Credentials

For testing you can use the same credentials that you use to log into Carma. For security reasons we recommend not using your own credentials in production. The recommendation for production is to get a special API user for your account and use these credentials. You can request an API user by sending an email to support@compost.se

GET Requests

GET requests are used to retrieve data from the system.

If you, for instance, want to retrieve all your projects you will first need to expand the projects:

You then click on the last entry to expand it, it will show you the following view:

If you enter your customer id and click on “try it out” you will be asked for you credentials. Enter them and click ok, and you will get back a JSON formatted response with the information about your projects.

POST Requests

POST requests are used to create data in the system.

When issuing a POST you often have to supply a JSON formatted message body containing the data for the entity you are creating. You can see the syntax of the model that will be returned by clicking Model Schema for the POST method.

To issue a POST you can get the input schema by clicking Model schema for the resource.

Copy the schema to the input field, by clicking on the text under the yellow box and fill in the required information.

Note! You should not include the “id”, “dateCreated”or “dateModified” fields as they are created automatically by the server. You can safely remove fields that you do not have data for, e.g. if you do not have data for Contact.MiddleName, that field can be removed from the input Json struct. You will get a validation error if you remove amandatory field.

PUT Requests

PUT requests are used for updating data in the database. The message body should include data required for updating the entity. For some resources you only need to specify the fields that you are changing, but usually you should make sure to include all fields as received from a previous GET request (once again, the id, dateCreated and dateModified fields are not required. The Id field this is specified in the URI and the other are created/updated automatically).

DELETE Requests

To delete an entry you supply the customer id and the id of the data to be deleted.

Domain description

All methods in carma are a part of a domain, below the domains are listed with a brief description of the methods and a link ti the swagger dokumentation of the domain. The link points out server 3, but you can easily replace the first part of the domain name in order to get to your server.

AbandonedCart

http://www3.carmamail.com/mail/swagger#!/clients

Methods for manipulation abandoned cart functions.

Apps

http://www3.carmamail.com/mail/swagger#!/apps

Methods used for sending Push messages and related administrative tasks.

Authentication

http://www3.carmamail.com/mail/swagger#!/authentication

Methods for authentication a user in Carma

Auto

http://www3.carmamail.com/mail/swagger#!/autos

Methods for manipulation of autosends

Batches

http://www3.carmamail.com/mail/swagger#!/batches

Methods used for starting generation of messages and various exports. Also contains methods for keeping track of progress and retrieving results.

Campaigns

http://www3.carmamail.com/mail/swagger#!/campaigns

Methods used for administration of Campaigns.

Emailclients

http://www3.carmamail.com/mail/swagger#!/emailclients

Methods for retrieving email client statistics for lists and deliveries.

Features

For internal use only.

Forms

http://www3.carmamail.com/mail/swagger#!/forms

methods for manipulating carma forms.

Filters

http://www3.carmamail.com/mail/swagger#!/filters

Methods used for administration of Filters

FtpAccounts

For internal use only.

Integration

http://www3.carmamail.com/mail/swagger#!/integration

Methods used by theird party vendors to integrate with carma

Jobs

http://www3.carmamail.com/mail/swagger#!/jobs

Methods used to start fixed generation jobs and retrieve information regarding jobs.

Lists

http://www3.carmamail.com/mail/swagger#!/lists

Methods used for administration of Lists

Messages

http://www3.carmamail.com/mail/swagger#!/messages

Methods used for retrieval of information regarding a specific message.

Microsites

http://www3.carmamail.com/mail/swagger#!/microsites

Methods used for retrieval of information regarding a microsites

Pe

http://www3.carmamail.com/mail/swagger#!/pe

Methods for ProspectEye

Placeholders

http://www3.carmamail.com/mail/swagger#!/placeholders

Method used to manipilate Attribute tags, also called placeholders associated with an account.

Ping

For internal use only

Projects

http://www3.carmamail.com/mail/swagger#!/projects

Methods used for administration of Projects.

Properties

http://www3.carmamail.com/mail/swagger#!/properties

Methods used for administration of Properties

Purchasehistory

http://www3.carmamail.com/mail/swagger#!/purchasehistory

Methods used for administration of purchase history data.

Reports

http://www3.carmamail.com/mail/swagger#!/reports

Methods used for retrieval of Reports for campaigns, autos and triggers.

Retention

For internal use only.

Scheduled

http://www3.carmamail.com/mail/swagger#!/scheduled

Methids used to setup scheduled import jobs

Sms

http://www3.carmamail.com/mail/swagger#!/sms

Methods used for administration of incoming SMS

Systemfeedback

For internal use only.

Systeminfo

For internal use only.

Systemusers

For internal use only.

Systemmessages

For internal use only.

Token

http://www3.carmamail.com/mail/swagger#!/token

Tracking

http://www3.carmamail.com/mail/swagger#!/tracking

Methods for Roi tracking.

Triggers

http://www3.carmamail.com/mail/swagger#!/triggers

Methods used for administration of transactional emails/SMS

Webhooks

http://www3.carmamail.com/mail/swagger#!/webhooks

Methods used for administration of webhooks

Maintenance

For internal use only.

Ping

For internal use only.

List Import

Introduction

Many customers have the need to import contacts and miscellaneous data into Carma. In order to get started basic knowledge of Carma’s list and contact management is required. Readers are assumed to have some familiarity with Carma’s graphical interface.

General workflow

In order to start an import you will need to prepare a file. Carma uses plain text^[1] as input. If your recipients are saved in an Excel document you must save the data as txt. The information in the file must be stored in tabular format delimited by comma, tab or any other appropriate character. In Carma under Account Settings > Profile Attributes you can manage how the fields in the file are mapped to your contacts properties.

After the file has been prepared it’s time to make the first request to the API. You will need four things four this request:

The ID of the list in Carma where you want to save your contacts,
The ASCII value of the delimiter used in the file,
The encoding of the file the
The type of import you want to run.

There are three types of imports:

Add, adds all the contacts in you file to the existing list
Replace, replaces all contacts in the list with the ones in you file
Unsubscribe, set all contacts that have matching rows in the file to unsubscribed

After all of this information have been gathered it’s time to make the request. The response, if everything went well, will contain a unique id that will be used later.

To start the import a POST request with metadata describing the import is sent:

POST <server>/rest/<customerId>/lists/<listId>/imports

{

“delimiter”: “9”,

“encoding”: “UTF8”,

“type”: “REPLACE”

}

Example response body
{
“id”: “bd48b5cc-b118-4062-8d06-09efa765592b”

}

There is a special feature that can be activated in the step described above. This feature is called Identity Column and it will let you specify how the fields in you file are mapped to the contacts identity in Carma. Normally you will have to provide a column with a unique identifier (called originalId in Carma). This could be a row number, primary key, customer number or something else that uniquely identifies this contact. If you can’t provide a column of this sort you can use email address, mobile number or any other column in you file as identifier. Here is an example using this feature:

POST <server>/rest/<customerId>/lists/<listId>/imports
{

“delimiter”: “9”,

“encoding”: “UTF8”,

“type”: “REPLACE”,

“identityColumn”: “emailaddress”

}

After the initial request have been made and an ID have been returned it’s time to upload your data. Use the id obtained in the response of the first request to upload your data: POST <server>/rest/<customerId>/lists/<listId>/recipients/<id>

CONTENT-TYPE: text/csv

Example response body
{
“batchId”: “101111”

}

When the file has successfully been uploaded you can query the API to trace the imports progress. Use the batchId from the previous request. You can keep polling the method until you receive a response with the status set to “FINISHED”. Do not poll too often as that will put unnecessary strain on the system. Polling once every 30 seconds or every minute is normally sufficient.

GET <server>/rest/<customerId>/batches/<batchId>

Response body

{

“id”: 101111,

“type”: “IMPORT”,

“customerId”: 0,

“startTime”: 1394636797030,

“endTime”: 1394636799710,

“affected”: 500,

“processed”: 500,

“total”: 501,

“status”: “ PENDING|IN_PROGRESS|FINISHED“

}

Statistics export

Introduction

Many customers have the need to export contacts and miscellaneous data from Carma.

A brief overview of RESTful web services can be found here:

http://net.tutsplus.com/tutorials/other/a-beginners-introduction-to-http-and-rest/

General workflow

In order to start an export you must decide which data you want and for how long timeperiod you want it. As the data is on a per message basis the file can get big if you you choose to big a timespan. The recommended way is to export data once a day.

Possible timeperiod values are:

TODAY,
LAST_DAY
LAST_3_DAYS
LAST_WEEK,
LAST_2_WEEKS.

Possible export values are:

LISTS
CAMPAIGNS
MESSAGES
OPENS
SENT
CLICKS
PROJECTS
HARD_BOUNCES
SOFT_BOUNCES
OPTOUTS

The two values should be put into a json struct that will be sent with the POST request.

After all of this information have been gathered it’s time to make the request. The response, if everything went well, will contain a unique id that will be used later.To start the export a POST request with metadata describing the import is sent:
POST <server>/rest/<customerId>/batches/exports/statistics

{

“exportType”: “OPENED”,

“period”: “LAST_2_WEEKS”

}

Example response body
{
“batchId”: “101111”

}

You can query the API to trace the export progress. Use the batchId from the previous request:

GET <server>/rest/<customerId>/batches/<batchId>

Response body

{

“id”: 101111,

“type”: “ STAT_EXPORT”,

“customerId”: 0,

“startTime”: 1394636797030,

“endTime”: 1394636799710,

“affected”: 500,

“processed”: 500,

“total”: 501,

“status”: “ PENDING|IN_PROGRESS|FINISHED”

}

When you get a status=FINISHED the file is available for retrieval.

GET <server>/rest/<customerId>/batches/<batchId>/result/url

This will result in an URL that you can use to retrieve the exported file. The url will look something like this:

https://carma-filetransfer.s3-eu-west-1.amazonaws.com/result/5004/3232465_result.json?Expires=1403187484&AWSAccessKeyId=AKIAJNJRZJQCQ3W66YIQ&Signature=FWZp8noVyxcOflH27k2W7MuNcmM%3D

NOTE! The return data is in text/plain, so make sure you do not use application/json as the Accept header for the call.

You can also use the following URL to get redirected to the result stored on amazon s3.

GET <server>/rest/<customerId>/batches/<batchId>/result

[1] UTF8, UTF16, ISO-8859-1, ANSI are also supported.