The Outkit Support and Developer Hub

Welcome to the Outkit support and developer hub. Here you'll find comprehensive guides and documentation to help you start working with Outkit as quickly as possible, as well as support if you get stuck. Let's jump right in!

Get Started    Guides

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)
A binary file was returned

You couldn't be authenticated

Try the API to see results

Path Params

id
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

Not found

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)
A binary file was returned

You couldn't be authenticated

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

Unprocessable entity

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