Docs. API

An overview of Sendicate’s API.

API Intro

Base url

All URLs referenced in this documentation begin with the following url: https://api.sendicate.net/

Required HTTP header fields

The Content-Type and Accept header fields must have a value of application/json

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

Authentication

Sendicate uses tokens for API authentication. Your API token can be found by logging into your Sendicate account and going to Manage, then Account, then scrolling down to API Access.

You should provide an API token on each request using either the HTTP authorization header field or the token query string parameter.

HTTP authorization header field

Authorization: token YOUR_API_TOKEN

Token query string parameter

curl https://api.sendicate.net/v1/lists?token=YOUR_API_TOKEN

Clients

Sendicate has official support for the following clients:

Response Status Codes

The following status codes are returned by API requests:

codetypedescription
200SuccessRequest was fulfilled
201SuccessA new resource was created
400ErrorThe request cannot be fulfilled
404ErrorResource not found
422ErrorValidation failure
500ErrorAn internal server error occurred

Success Codes

Success codes have the following codes:

methoddescription
GETRequests will return a “200 OK” response upon success.
POSTRequests to create a resource we will return a “201 Created” upon success.
POSTRequests which do not create a resource will return a “200 OK” upon success.
PUTRequests to update a resource will return a “200 OK” response upon success.
DELETERequests to delete a resource will return a “200 OK” response upon success.

Error Codes

If you make a request with an invalid API key you will receive a 401.

If you make a request with invalid parameters, you will receive a 400 with errors.

{
  "title": ["can"t be blank"]
}

If you try to request a resource that does not exist, you will receive a 404.

API Endpoints

This section outlines the following API endpoints:

Lists

Manage subscriber lists.

Create a list

Creates a new subscribers list.

POST https://api.sendicate.net/v1/lists

Expected request
Accept: application/json
Authorization: token YOUR_API_TOKEN
Content-Type: application/json

{
  "title": "Newsletter"
}
Expected response
HTTP/1.1 201 Created
Content-Type: application/json; charset=utf-8

{
  "id": "asdf"
  "title": "Newsletter",
  "subscribers_count": 0
}

Show all lists

Returns a list of all your subscriber lists. :turtle:s all the way down.

GET https://api.sendicate.net/v1/lists

Expected response
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

[
  {
    "id": "asdf",
    "title": "Newsletter",
    "subscribers_count": 1000
  },
  {
    "id": "qwerty",
    "title": "Beta",
    "subscribers_count": 100
  }
]

Show a list

Returns the attributes of the requested list.

GET https://api.sendicate.net/v1/lists/:list_id

Parameters

:list_id The ID of the requested list.

Expected response
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
  "id": "asdf",
  "title": "Newsletter",
  "subscribers_count": 1000
}

Update a list

Updates attributes of the requested list.

PUT https://api.sendicate.net/v1/lists/:list_id

Parameters

:list_id The ID of the requested list.

Expected request
Accept: application/json
Authorization: token YOUR_API_TOKEN
Content-Type: application/json

{
  "title": "Old Newsletter"
}
Expected response
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
  "id": "asdf",
  "title": "Old Newsletter",
  "subscribers_count": 1000
}

Delete a list

Deletes the requested list.

DELETE https://api.sendicate.net/v1/lists/:list_id

Parameters

:list_id The ID of the requested list.

Expected response
HTTP/1.1 200 OK

List subscribers

Manage subscribers in a list.

Show all list subscribers

Returns all subscribers in the requested list.

GET https://api.sendicate.net/v1/lists/:list_id/subscribers?page=:page

Parameters

:list_id The ID of the requested list.

:page The page of results to return. Default page: 1, default page size: 50)

Expected response
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

[
  {
    "email": "vanhalen@example.com",
    "name": "van halen",
    "status": "Subscribed",
    "unsubscribed_at": null,
    "delivered_count": 100,
    "opened_count": 100,
    "clicked_count": 100,
    "joined_at": "2013-03-11 01:00:00 UTC",
    "subscribed": true,
    "age": "<18" // This is an example of a custom field.
  },
  {
    "email": "foo@example.com",
    "name": "foo bar",
    "status": "Subscribed",
    "unsubscribed_at": null,
    "delivered_count": 100,
    "opened_count": 100,
    "clicked_count": 100,
    "joined_at": "2013-03-11 01:00:00 UTC"
    "subscribed": true
  }
]

Create or update list subscribers

Creates or updates many subscribers and adds them to the requested list. Only invalid email addresses will cause an import to fail. Errors on other fields will be reported and ignored, but will not cause an import to fail. Existing subscribers will be updated.

POST https://api.sendicate.net/v1/lists/:list_id/subscribers

Parameters

:list_id The ID of the requested list.

Expected request for one subscriber
Accept: application/json
Authorization: token YOUR_API_TOKEN
Content-Type: application/json

{
  "email": "vanhalen@example.com",
  "name": "van halen",
  "age": "18-34" // This is an example of a valid custom field
}
Expected request for many subscribers
Accept: application/json
Authorization: token YOUR_API_TOKEN
Content-Type: application/json

[
  {
    "email": "vanhalen@example.com",
    "name": "van halen",
    "age": "18-34" // This is an example of a valid custom field
  },
  {
    "email": "foo@example.com",
    "name": "foo bar",
    "color": "blue" // This is an example of an invalid field that does not exist
  }
]
Expected response with errors
HTTP/1.1 200 Ok
Content-Type: application/json; charset=utf-8

{
  "imported": 2,
  "updated": 0,
  "failed": 0,
  "errors": [
    {
      "data": {
        "email": "foo@example.com",
        "name": "foo bar",
        "color": "blue"
      },
      "errors": [
        {
          "field": "color",
          "code": "invalid",
          "message": "color is not a valid field"
        }
      ],
      "status": "imported"
    }
  ]  
}
Expected response with failure
HTTP/1.1 422 Unprocessable entity
Content-Type: application/json; charset=utf-8

{
  "imported": 1,
  "updated": 0,
  "failed": 1,
  "errors": [
    {
      "data": {
        "email": "foo",
        "name": "foo bar"
      },
      "errors": [
        {
          "field": "email",
          "code": "invalid",
          "message": "Invalid email address"
        }
      ],
      "status": "imported"
    }
  ]
}

Delete a list subscriber

Remove the requested subscriber from the list.

DELETE https://api.sendicate.net/v1/lists/:list_id/subscribers/:subscriber_email

Parameters

:list_id The ID of the requested list.

:subscriber_email The email address of the requested list subscriber.

Expected response
HTTP/1.1 200 OK

Subscribers

Manage individual subscribers.

Show a subscriber

Returns the attributes of the requested subscriber.

GET https://api.sendicate.net/v1/subscribers/:subscriber_email

Parameters

:subscriber_email The email address of the requested subscriber.

Expected response
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
  "email": "vanhalen@example.com",
  "name": "van halen",
  "status": "Subscribed",
  "unsubscribed_at": null,
  "delivered_count": 0,
  "opened_count": 0,
  "clicked_count": 0,
  "joined_at": "2013-03-11 01:00:00 UTC",
  "subscribed": true,
  "list_ids":["123abc"],
  "age": "18-34" // This is an example of a custom field
}

Update a subscriber

Updates attributes of the requested subscriber.

PUT https://api.sendicate.net/v1/subscribers/:subscriber_email

Parameters

:subscriber_email The email address of the requested list subscriber.

Expected request
Accept: application/json
Authorization: token YOUR_API_TOKEN
Content-Type: application/json

{
  "name": "foo bar",
  "age": "18-34" // This is an example of a custom field
}
Expected response
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
  "email": "vanhalen@example.com",
  "name": "foo bar",
  "status": "Subscribed",
  "unsubscribed_at": null,
  "delivered_count": 0,
  "opened_count": 0,
  "clicked_count": 0,
  "joined_at": "2013-03-11 01:00:00 UTC",
  "subscribed": true,
  "list_ids":["123abc"],
  "age": "18-34" // This is an example of a custom field
}

Unsubscribe a subscriber

To unsubscribe a subscriber, submit a request to update the subscriber with a subscribed attribute value of false.

PUT https://api.sendicate.net/v1/subscribers/:subscriber_email

Parameters

:subscriber_email The email address of the requested list subscriber.

Expected request
Accept: application/json
Authorization: token YOUR_API_TOKEN
Content-Type: application/json

{
  "subscribed": false
}

Fields

Show all fields

Returns all default fields (email and name) and custom fields. Custom fields are useful for storing extra subscriber data, segmentation, etc.

GET https://api.sendicate.net/v1/fields

Expected response
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

[
  {
    "name": "email",
    "options": [],
    "type": "text"
  },
  {
    "name": "name",
    "options: [],
    "type": text"
  },
  {
    "name": "Age",
    "options": ["<18","18-34","34+"],
    "type":"list"
  }
]