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 https://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 https://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 https://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=https://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=https://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=https://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 https://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": "[email protected]",
"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=https://api.dopplerrelay.com/schemas/creation-result.json
Date: Tue, 01 Sep 2015 16:08:28 GMT
Location: https://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:
-
DateTime values should be explicit about timezone offset.
- Valid:
...?from=2015-05-21T09:00:36-03:00&to=2015-01-29T09:00:36Z
. - Invalid:
...?from=2015-05-21T09:00:36&to=2015-01-29T09:00:36
.
- Valid:
-
If parameter is missing, the filter is not applied.
...?from=2015-05-21T09:00:36-03:00&to=2015-01-29T09:00:36Z
means between2015-05-21T09:00:36-03:00
and2015-01-29T09:00:36Z
....?from=2015-05-21T09:00:36-03:00
means after2015-05-21T09:00:36-03:00
....?to=2015-01-29T09:00:36Z
means before2015-01-29T09:00:36Z
.
-
from
filter is not strict (inclusive)...?from=2010-01-29T09:00:36.515+00:00
includes events occurred exactly at that time and after.
-
to
filter is strict (exclusive)...?to=2010-01-29T09:00:36.515+00:00
does not include events occurred exactly at that time, only events occurred before.