User Tools

Site Tools


api

API Documentation

Introduction

Below you'll find reference materials that will teach you how to use Campaign Cog, and documentation for all the features available to the users of our API.

Note: To battle spam and keep Campaign Cog working without any issues, api access must be requested directly. Just contact hello@campaigncog.com to request this access. Production access to the API is only available to paying users, although a test key will be made available to any potential clients.

Authentication

You authenticate to the Campaign Cog API by providing your API key in the request. Your API keys carry many privileges, so be sure to keep them secret!

The class will look for an HTTP header with the API key on each request. An invalid or missing API key will result in an HTTP 403 Forbidden response.

All API requests must be made over HTTP. You must authenticate for all requests.

API Endpoint

API Methods

Campaigns

To get campaigns you will will make a Http GET Request, also if you want to add a new one you will have different required fields, but will be using the same endpoint while using a post request.

Note: When returning a campaign, to use the code you need to inject into an email, you will need to decode it from its base64 format. There is an example of this decoding in this github demo project.

GET

Since this is a rest interface a GET request would be used to retreive a filterable list of campaigns.

Method Calls:
/v1/campaigns/
/v1/campaigns/campaign_id/{CAMPAIGN_ID}

Example Calls:
http://api.campaigncog.com/v1/campaigns/key/{YOURAPIKEY}/
or alternatively
http://api.campaigncog.com/v1/campaigns?key={YOURAPIKEY}

POST

Since this is a rest interface a POST request would be used to create new campaigns.

Note: As of now if click tracking is enabled the response will include an item with the tags <html>. This will always be included in the callback for code if you have click tracking enabled.

Method Calls:
/v1/campaigns/
/v1/campaigns/campaign_id/{CAMPAIGN_ID}

Example Calls:
http://api.campaigncog.com/v1/campaigns/
key: This would be your API key.
name: The name that was chosen for the campaign.
no_subscriber: Number of subscribers that the campaign will be sent to.
start_date: The date that the campaign will be sent out.
subscriber_level_tag: This would be the merge tag that you want to provide for the software sending out the email. (optional)
click_tracking: This would be 1 if you want to enable click tracking otherwise leave it blank or set it to 0. (optional)
email_code: This would be the email that you want to enable the click tracking on links for, upon successful return it will comeback in the html response with the tag html. (optional)
google: This will enable google analytics tracking, of the email. 1 would enable this option. (optional)

DELETE

Since this is a rest interface a DELETE request would be used to delete the campaign specified by campaign_id.

Method Calls:
/v1/campaigns/campaign_id/{CAMPAIGN_ID}

Example Calls:
http://api.campaigncog.com/v1/campaigns/key/{YOURAPIKEY}/campaign_id/{CAMPAIGN_ID}/
or alternatively
http://api.campaigncog.com/v1/campaigns?key={YOURAPIKEY}&campaign_id={CAMPAIGN_ID}

Response Formats

Supported Formats for the responses are listed below. The default formate is xml, although to change the respons format just append the get parameters like in the examples below.

Example Calls:
http://api.campaigncog.com/v1/campaigns/key/{YOURAPIKEY}/jsonp/
or alternatively
http://api.campaigncog.com/v1/campaigns?key={YOURAPIKEY}&format=jsonp

Response Type Content Type
xml application/xml
json application/json
jsonp application/javascript
serialized application/vnd.php.serialized'
php text/plain
html text/html
csv application/csv

API changelog

2013-02-11

Added functionality to directly tie in the API for each user to create new campaigns. This should allow easier integration into existing email marketing systems.

2011-05-31

First iteration of Version 1 of the api has been released to developers that want to use Campaign Cog via an api instead of directly using our user dashboard for all functionality.

HTTP Status Code Summary

200 OK - Everything worked as expected.

400 Bad Request - Often missing a required parameter.

403 Forbidden - No valid API key provided.

402 Request Failed - Parameters were valid but request failed.

404 Not Found - The requested item doesn't exist.

500, 502, 503, 504 Server errors - something went wrong on Campaign Cogs's end.

api.txt · Last modified: 2013/07/04 16:16 (external edit)