REST - Send Campaign

Introduction to Carma Jobs REST API.

Rev A. (CAMPAIGN)

 

About this document

This is a compliment to the Carma Rest API document that describes the Jobs resource in more detail. Readers are assumed to have some familiarity with Carma’s graphical interface and experience with the REST API.

 

Workflow

In order to start a job you will need to prepare a couple of things in Carma.

    • A campaign, trigger or auto-send must be created. It’s recommended to send this delivery to a test list manually to verify deliverability before any Jobs are started.
    • A list of type Normal must be created.

 

You must also prepare you recipient data. Please read the List import section in the main REST API documentation and familiarize yourself with how Imports are handled by Carma.

To start a new Job a POST request with details specifying the Jobs delivery and list is sent.

POST <server>/rest/<customerId>/jobs/generation/fixed

{

“type”: “CAMPAIGN”,

“id”: 336858,

“listId”: 22265

}

 

Valid type values are:

  • CAMPAIGN

 

The Id the JSON object will be interpreted as one of the delivery types above.

 

Carma will process your request and respond with a confirmation that a new Job have been created. The response will look something like this.

{

“id”:7202,

“campaignId”:336858,

“listId”:22265,

“contentUploaded”:false,

“feedback”:[

{

“feedback”:”WAITING_FOR_CONTENT”,

“severity”:”SEVERITY_INFO”,

“timestamp”:1441374310577

}]

}

Now it’s time to upload you recipient data. To construct the URL for this request you will need the Id value from the previous response.

 

POST <server>/rest/<customerId>/jobs/generation/fixed/<id>/recipients/automapping

email      originalid lastname
pm@compost.se         1          pm
lh@compost.se         2          lh
th@compost.se         3          th

 

The request must be sent with recipient specified as text/csv, tab separated with the first row containingcolumn headers.  It is highly recommended that before any data is sent to Carma that mappings are prepared and reviewed in the Recipient attributes part of the Carma web interface.

 

After this request is completed generation of messages is automatically started. Progress of the job is shown in the feedback part in the response. To help you keep track of a Jobs progress requests can made to the following recourse. It will respond with a collection of feedback entries in the same manner as previous requests.

 

GET <server>/rest/<customerId>/jobs/generation/fixed/<id>

 

Raw HTTP examples

 

Request 1

POST http://test.carmamail.com/rest/487/jobs/generation/fixed HTTP/1.1

Host: test.carmamail.com

Content-Length: 59

Authorization: Basic XXXX

Accept: application/json

 

{

“type”: “CAMPAIGN”,

“id”: 336858,

“listId”: 22265

}

 

Response 1

HTTP/1.1 200 OK

Content-Type: application/json

Server: Microsoft-IIS/7.5

X-Powered-By: ARR/2.5

X-Powered-By: ASP.NET

Date: Fri, 04 Sep 2015 13:45:10 GMT

Content-Length: 171

 

{“id”:7202,”campaignId”:336858,”listId”:22265,”contentUploaded”:false,”feedback”:[{“feedback”:”WAITING_FOR_CONTENT”,”severity”:”SEVERITY_INFO”,”timestamp”:1441374310577}]}

 

Request2

POST http://test.carmamail.com/rest/487/jobs/generation/fixed/7202/recipients HTTP/1.1

Host: test.carmamail.com

Authorization: Basic XXX

Content-Type: text/csv;charset=UTF-8

Content-Length: 103

 

email    originalid         lastname

paul@compost.se    1        pm

lh@compost.se      2        lh

th@compost.se      3        th

 

Response2

HTTP/1.1 200 OK

Content-Type: application/json

Server: Microsoft-IIS/7.5

X-Powered-By: ARR/2.5

X-Powered-By: ASP.NET

Date: Fri, 04 Sep 2015 13:57:47 GMT

Content-Length: 1124
{“id”:7202,”campaignId”:336858,”listId”:22265,”contentUploaded”:false,”feedback”:[{“feedback”:”WAITING_FOR_CONTENT”,”severity”:”SEVERITY_INFO”,”timestamp”:1441374310577},{“feedback”:”UPLOADING_CONTENT”,”severity”:”SEVERITY_INFO”,”timestamp”:1441375034573},{“feedback”:”UPLOADED_CONTENT”,”severity”:”SEVERITY_INFO”,”timestamp”:1441375034620},{“feedback”:”STARTED_IMPORT”,”severity”:”SEVERITY_INFO”,”timestamp”:1441375067147}]}