Doppler Relay

Getting started

Since the API is based on REST principles, it's very easy to write and test applications. You can use your browser to access URLs, and you can use pretty much any HTTP client in any programming language to interact with the API.

Authentication

Getting an API Key

Most of the Relay API services require to call them on a behalf of a user, so it is required an API Key to be included in each request.

Using API Key

The API Key allows you to make requests to the API on a behalf of a user.

GET http://api.dopplerrelay.com?api_key=...

You can pass the API Key in the query params like shown above, but a cleaner (and safer) approach is to include it in the Authorization header.

GET http://api.dopplerrelay.com

Authorization: Bearer OAUTH-TOKEN

Basic usage

Asking for a resource

Suppose that your Relay account id is 5, your API Key is 22495B800297B754C6EF66FA2C5C1902 and you want to get the collection of templates that you have created.

So, you should prepare the follow HTTP request:

GET http://api.dopplerrelay.com/accounts/5/templates

Authorization: Bearer 22495B800297B754C6EF66FA2C5C1902

Relay API will return something like this:

Status Code: 200 OK
Content-Length: 2130
Content-Type: application/json; charset=utf-8; profile=http://api.dopplerrelay.com/schemas/template-collection-page.json
Date: Tue, 01 Sep 2015 15:16:47 GMT
{
  "items": [
    {
      "from_name": "user",
      "from_email": "test",
      "subject": "Hi!",
      "body": "<p>Hi</p>",
      "name": "Demo",
      "id": "caa9480f-8251-434e-b600-b9b68c346632",
      "last_updated": "2016-06-27T19:34:23+00:00",
      "created_at": "2016-06-27T19:34:23+00:00",
      "_links": [
        {
          "href": "/accounts/5/templates/caa9480f-8251-434e-b600-b9b68c346632",
          "description": "Specific template",
          "rel": "/docs/rels/get-template"
        },
        {
          "href": "/accounts/5/templates/caa9480f-8251-434e-b600-b9b68c346632/message",
          "description": "Create and send an email based on a template and a model to populate it",
          "rel": "/docs/rels/create-template-message"
        },
        {
          "href": "/accounts/5/templates/caa9480f-8251-434e-b600-b9b68c346632",
          "description": "Delete template",
          "rel": "/docs/rels/delete-template"
        },
        {
          "href": "/accounts/5/templates/caa9480f-8251-434e-b600-b9b68c346632",
          "description": "Edit template",
          "rel": "/docs/rels/edit-template"
        }
      ],
      "pageSize": 200,
      "itemsCount": 9,
      "currentPage": 1,
      "pagesCount": 1,
      "_links": [
      {
        "href": "/accounts/5/templates",
        "description": "Collection of templates",
        "rel": "/docs/rels/experimental /docs/rels/get-template-collection self"
      },
      {
        "href": "/accounts/5/templates",
        "description": "Create template",
        "rel": "/docs/rels/create-template"
      },
      {
        "href": "/accounts/5",
        "description": "Account home",
        "rel": "/docs/rels/get-account-home"
      },
      {
        "href": "/",
        "description": "API index",
        "rel": "/docs/rels/get-index"
      }
  ]
    },

This response represents a page with a maximum of 20 items, each of them representing a template with the id, name, status and links for possible actions on it, for example delete it (see rel=http://api.dopplerrelay.com/docs/rels/delete-template).

Also the page have links to related resources and actions, for example create a new one (see rel=http://api.dopplerrelay.com/docs/rels/create-template).

Creating a resource

We want to create a new template named "My Second Template", so we send the follow request:

POST http://api.dopplerrelay.com/accounts/5/templates

Authorization: Bearer 22495B800297B754C6EF66FA2C5C1902
Content-Type: application/json
{
  "body": "Hello, this is my first Template.",
  "subject": "Test Template",
  "from_email": "test@test.com",
  "name": "My Second Template"
}

Relay API will return something like this:

Status Code: 201 Created
Content-Length: 1559
Content-Type: application/json; charset=utf-8; profile=http://api.dopplerrelay.com/schemas/creation-result.json
Date: Tue, 01 Sep 2015 16:08:28 GMT
Location: http://api.dopplerrelay.com/accounts/5/templates/509719
{
  "createdResourceId": "509719",
  "message": "Template successfully created",
  "_links": [
    {
      "href": "/accounts/5/templates/6cfe366a-ba4c-448d-bd08-0442c20769ab",
      "description": "Specific template",
      "rel": "/docs/rels/get-template related"
    },
    {
      "href": "/accounts/5/templates",
      "description": "Create template",
      "rel": "/docs/rels/create-template self"
    },
    {
      "href": "/accounts/5/templates/6cfe366a-ba4c-448d-bd08-0442c20769ab",
      "description": "Delete template",
      "rel": "/docs/rels/delete-template"
    },
    {
      "href": "/accounts/5/templates/6cfe366a-ba4c-448d-bd08-0442c20769ab",
      "description": "Edit template",
      "rel": "/docs/rels/edit-template"
    },
    {
      "href": "/accounts/5/templates",
      "description": "Collection of templates",
      "rel": "/docs/rels/experimental /docs/rels/get-template-collection"
    },
    {
      "href": "/accounts/5/templates/6cfe366a-ba4c-448d-bd08-0442c20769ab/message",
      "description": "Create and send an email based on a template and a model to populate it",
      "rel": "/docs/rels/create-template-message"
    },
    {
      "href": "/accounts/5",
      "description": "Account home",
      "rel": "/docs/rels/get-account-home"
    },
    {
      "href": "/",
      "description": "API index",
      "rel": "/docs/rels/get-index"
    }
  ]
}

This response represents a resource creation (see Status Code), includes the link to the created template (see Location header and rel=related link) and the id (see createdResourceId property). And, of course, a large set of links of related actions.

Dealing with errors

Suppose that you create a new Template in your account without mandatory field from_email, Relay API will return you something like this:

{
  "title": "Validation error",
  "status": 400,
  "errorCode": 1,
  "detail": "Validation error validating `/schemas/template.json` for ``. See `errors` field for more details.",
  "errors": [
    {
      "key": "from_email",
      "detail": "The from_email field is required."
    }
  ],
  "type": "/docs/errors/400.1-validation-error",
  "_links": [
   {
     "href": "/accounts/{accountId:int}",
     "description": "Account home",
     "rel": "/docs/rels/get-account-home"
   }
  ]
}

Notice about type field, it refers to a page where you can get more information about the error and how to solve it. See the section Errors for the complete template of possible problem types.

Special data formats and dates

DateTime values

The follow is a Report Request representation, from a Relay API response:

{
  "user_id": 3,
  "name": "My First template",
  "processed": true,
  "start_date": "2015-09-01T15:16:32.75+00:00",
  "end_date": "2015-09-02T15:16:32.75+00:00",
  "filter": "test"
  ...

As you can see start_date and end_date fields represent DateTime values. To avoid ambiguities, Relay API exposes DateTime values using Coordinated Universal Time (UTC) and making offset explicit (+00:00).

Explicit timezone is required on inputs, for example these are accepted DateTime values: 2015-08-15T09:00+04:00, 2015-05-21T09:00:36-03:00, 2010-01-29T09:00:36.515+00:00 and 2015-01-29T09:00:36Z.

DateTime filtering

Requesting some collections, for example Deliveries Aggregations (for statistics), allows you to filter by a range of time giving the parameters from and to following the follow rules: