Outkit

Introduction

The Outkit API is based on REST principles. It has predictable, resource-oriented URLs, and uses HTTP response codes to indicate API errors. We use HTTP verbs with predictable semantics. JSON is returned by all API responses, including errors, although some API libraries may convert responses to appropriate language-specific objects.

API endpoint

https://api.outkit.io/v1

Authentication

Authentication is done by including the key and passphrase from your API key in the headers Outkit-Access-Key and Outkit-Access-Passphrase. You can manage your API keys in the web UI. Your API keys carry many privileges, so be sure to keep them secure! Do not share your secret API keys in publicly accessible areas such GitHub, client-side code, and so forth.

All API requests must be made over HTTPS. Calls made over plain HTTP will fail. API requests without authentication will also fail.

All API requests must be signed unless you have explicitly opted out by setting the appropriate flag on your API key. Request signing ensures that API requests have not been tampered with in transit, and that the API key secret never has to be transmitted over the wire.

However, since request signing makes testing and debugging with curl and similar tools highly impractical, you may (as mentioned above) disable it. In these cases, you’ll also need to send an Outkit-Access-Secret header, containing your API key secret. Don’t send your secret when using signed requests.

Signing a request involves adding a few more headers:

Outkit-Access-Timestamp - a Unix timestamp (seconds since Epoch) like 1496837645
Outkit-Access-Signature - the actual signature

The signature is computed by first concatenating the following strings:

The exact same timestamp that was used in the timestamp header
HTTP verb (uppercased)
Request path, including any querystring parameters
The request body (which is a stringified version of the JSON payload), where applicable

The following is an example of how this might look with some actual data (where + represents strings concatenation):

 '1496837645' + 'POST' + '/v1/messages' + '{"message":{"type":"email",...}}'

Once you have this pre-signature string, you need to do the following to generate the actual signature:

Create an sha256 HMAC of the pre-signature string using the API key secret as the key.
Base64-encode the result of the previous operation

You now have the string that goes in the Outkit-Access-Signature header.

Here is an example of how to do this in a few languages:

const timestamp = Date.now() / 1000;
const payload = timestamp +  method.toUpperCase() + path + body;
const hmac = crypto.createHmac('sha256', apiKeySecret);
const signature = hmac.update(preSig).digest('base64');

$timestamp = time();
$payload = $timestamp . $method . $path . $body;
$hmac = hash_hmac('sha256', $payload, $apiKeySecret, true);
$signature = base64_encode($hmac);

timestamp = DateTime.utc_now |> DateTime.to_unix |> Integer.to_string
payload = timestamp <> method <> path <> body
hmac = :crypto.hmac(:sha256, api_key_secret, payload)
signature = Base.encode64(hmac)

Return values

The Outkit API always returns application/json, with the payload wrapped in a data key.

Example response

{
  "data": {
    "backend": "mailgun",
    "backend_id": "e40ec64d-ac2a-4294-a54f-c8a249ec319b",
    "backend_response": {},
    "data": {},
    "delivered_at": null,
    "done": true,
    "failed_at": null,
    "from": "support@outkit.io",
    "html_body": "...",
    "html_template_body": null,
    "id": "6dc5b9a6-863a-4be2-bd58-8540f2d9120a",
    "id_from_backend": null,
    "id_from_submitter": null,
    "project": "outkit",
    "project_id": "9c78ecef-d9cf-49af-8bfe-5b684ff6e0e3",
    "provider_id": "a5883e68-4f6f-48c8-b6e7-98da780e3dfb",
    "queued_for_delivery_at": null,
    "queued_for_rendering_at": null,
    "received_at": "2018-04-21T09:02:24.607840Z",
    "render_only": false,
    "rendered_at": "2018-04-21T09:02:24.646770Z",
    "status": "rendered",
    "status_message": null,
    "subject": "Welcome to Outkit",
    "sync": false,
    "template": "welcome",
    "template_id": "9d59ed16-d435-4631-8cd5-111aaa355468",
    "template_styles": null,
    "test": false,
    "text_body": "...",
    "text_template_body": null,
    "to": "some.email@example.com",
    "type": "email"
  }

Errors

Outkit uses conventional HTTP response codes to indicate the success or failure of an API request. In general: Codes in the 2xx range indicate success. Codes in the 4xx range indicate an error that failed given the information provided (e.g., a required parameter was omitted, a value was invalid/illegal, etc.). Codes in the 5xx range indicate an error on Outkit's end (should be rare).

Many errors include a JSON payload that offers more information.

HTTP status code summary

Status code	Description
20x - OK	Everything worked as expected.
401 - Unauthorized	No valid API key provided.
404 - Not Found	The requested resource doesn't exist.
422 - Unprocessable Entity	The request was unacceptable, often due to missing a required parameter.
429 - Too Many Requests	Too many requests hit the API too quickly.
50x - Server Errors	Something went wrong on Outkit end.

Error codes

Code	Description
`bad_data`	Something was wrong or invalid in the input data
`config_issue`	Your account is not correctly/fully configured

Client libraries

The easiest way to use our API is by using a client library. We currently offer official client libraries for the following libraries:

We also plan to release official libraries for the following languages in the next few months:

Message

The Message object represents a message to be rendered and/or delivered.

/messages/{id}

Retrieve message

gethttps://api.outkit.io/v1/messages/id

curl --request GET \
  --url https://api.outkit.io/v1/messages/id

var request = require("request");

var options = { method: 'GET',
  url: 'https://api.outkit.io/v1/messages/id' };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

require 'uri'
require 'net/http'

url = URI("https://api.outkit.io/v1/messages/id")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)

response = http.request(request)
puts response.read_body

var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("GET", "https://api.outkit.io/v1/messages/id");

xhr.send(data);

import requests

url = "https://api.outkit.io/v1/messages/id"

response = requests.request("GET", url)

print(response.text)

{{ results.statusCode[0] }} {{ results.statusCode[1] }}

Metadata

A binary file was returned

You couldn't be authenticated

Method

URL

Request Headers

{{ results.requestHeaders }}

Request Data

{{ results.data }}

Status

Response Headers

{{ results.responseHeaders }}

Try the API to see results

Path Params

string

required

Message ID

Response

Success

data	object A message to be rendered and/or delivered
data.type	string Message type
data.to	string Recipient address (format depends on backend)
data.text_template_body	string Inline template body for the plain text part
data.text_body	string Skip rendering, use this for the plain text part of the message body
data.test	boolean If true, use test semantics for this message
data.template_styles	string Inline styles to be applied to inline HTML template body
data.template_id	string Template to use, identified by ID
data.template	string Template to use, identified by identifier
data.sync	boolean If true, wait for rendering and delivery (unless render-only) to take place before returning
data.subject	string Message subject (if applicable)
data.render_only	boolean If true, skip delivery, just render the message
data.project_id	string Project ID - either this or 'project' is required
data.project	string Project identifier - either this or 'project_id' is required
data.id_from_submitter	string Optional ID from submitter for cross-reference purposes, not used by Outkit
data.html_template_body	string Inline template body for HTML part
data.html_body	string Skip rendering, use this for the HTML part of the message body
data.from	string From address (format depends on backend)
data.data	object Locals for templates
data.backend_id	string Backend to use, identified by ID
data.backend	string Backend to use, identified by identifier

error	object A typical the error response
error.message	string An error message with more details
error.code	string A text-based code that is common to a class of errors

/messages

Create message

posthttps://api.outkit.io/v1/messages

curl --request POST \
  --url https://api.outkit.io/v1/messages

var request = require("request");

var options = { method: 'POST', url: 'https://api.outkit.io/v1/messages' };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

require 'uri'
require 'net/http'

url = URI("https://api.outkit.io/v1/messages")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)

response = http.request(request)
puts response.read_body

var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("POST", "https://api.outkit.io/v1/messages");

xhr.send(data);

import requests

url = "https://api.outkit.io/v1/messages"

response = requests.request("POST", url)

print(response.text)

{{ results.statusCode[0] }} {{ results.statusCode[1] }}

Metadata

A binary file was returned

You couldn't be authenticated

Method

URL

Request Headers

{{ results.requestHeaders }}

Request Data

{{ results.data }}

Status

Response Headers

{{ results.responseHeaders }}

Try the API to see results

Body Params

message

object

A message to be rendered and/or delivered

message.type

string

required

Message type

message.to

string

required

Recipient address (format depends on backend)

message.text_template_body

string

Inline template body for the plain text part

message.text_body

string

Skip rendering, use this for the plain text part of the message body

message.test

boolean

If true, use test semantics for this message

message.template_styles

string

Inline styles to be applied to inline HTML template body

message.template_id

string

Template to use, identified by ID

message.template

string

Template to use, identified by identifier

message.sync

boolean

If true, wait for rendering and delivery (unless render-only) to take place before returning

message.subject

string

Message subject (if applicable)

message.render_only

boolean

If true, skip delivery, just render the message

message.project_id

string

Project ID - either this or 'project' is required

message.project

string

Project identifier - either this or 'project_id' is required

message.id_from_submitter

string

Optional ID from submitter for cross-reference purposes, not used by Outkit

message.html_template_body

string

Inline template body for HTML part

message.html_body

string

Skip rendering, use this for the HTML part of the message body

message.from

string

From address (format depends on backend)

message.data

object

Locals for templates

message.backend_id

string

Backend to use, identified by ID

message.backend

string

Backend to use, identified by identifier

Response

Success

data	object A message to be rendered and/or delivered
data.type	string Message type
data.to	string Recipient address (format depends on backend)
data.text_template_body	string Inline template body for the plain text part
data.text_body	string Skip rendering, use this for the plain text part of the message body
data.test	boolean If true, use test semantics for this message
data.template_styles	string Inline styles to be applied to inline HTML template body
data.template_id	string Template to use, identified by ID
data.template	string Template to use, identified by identifier
data.sync	boolean If true, wait for rendering and delivery (unless render-only) to take place before returning
data.subject	string Message subject (if applicable)
data.render_only	boolean If true, skip delivery, just render the message
data.project_id	string Project ID - either this or 'project' is required
data.project	string Project identifier - either this or 'project_id' is required
data.id_from_submitter	string Optional ID from submitter for cross-reference purposes, not used by Outkit
data.html_template_body	string Inline template body for HTML part
data.html_body	string Skip rendering, use this for the HTML part of the message body
data.from	string From address (format depends on backend)
data.data	object Locals for templates
data.backend_id	string Backend to use, identified by ID
data.backend	string Backend to use, identified by identifier

API endpoint

Example response

HTTP status code summary

Error codes

Path Params

200 404 Response

Body Params

200 422 Response

Response

Response