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

Getting Started

This page will help you get started with Outkit. You'll be up and running in just a few minutes!

In this guide, we’ll take you through the steps required to send a message using Outkit. In the process, we’ll get your Outkit account ready to be used in your project/product/script/whatever. We’ll focus on emails in this guide, but you can also use Outkit to send SMS messages. Here’s a quick overview of the steps we’ll cover:

  • Create a template
  • Set up a backend
  • Create an API token
  • Submit a message

Let’s get started!

Creating a template

There are several ways to use Outkit without using our template system, but it offers quite a few benefits that most templating solutions don’t, so in this guide we’ll set up and use a template. We recommend that you use our template system if you don’t have a good reason not to.

Log in to your account, click Templates, then New Template near the top right corner.

In the first screen, you choose the template type - Email or SMS. Choose Email.

Next, you are presented with our template picker. This lets you base your new template on one of our pre-defined master templates, saving you potentially days of work. This time, we’ll choose the Welcome template.

The next screen lets us give our new template a name and an identifier. You’ll use the identifier later in the API call.

But there’s something else going on in this screen as well, something that’s key to how Outkit templates work. A template can, if you choose, inherit headers, footers and data from its project and team. They wrap the template, so to speak. Like so:

team header
    project header
        template body
    project footer
team footer

You can read more about how this works in our article on templates, so for now we’ll just choose Combined Template. This gives us the full master template without risking overwriting anything.

Great, we have created our template! You’d normally adapt it to your needs and align it with your visual profile at this point, but to keep this guide short, we’ll just leave it untouched and move on.

Setting up a backend

Outkit sits between you and certain supported providers (like Twilio and Mailgun).

you  ⟶  outkit  ⟶  provider  ⟶  recipient

The providers are experts at low-level message delivery. An instance of a provider, combined with your customer-specific configuration and credentials, is called a backend in Outkit parlance. You can have many different backends, even multiple ones for the same provider (with different configurations).

In this guide we’ll configure a backend of your choosing, so we can’t really say which provider to choose and what configuration to specify. You’ll need to have an account or sign up for an account with at least one of our supported email providers to follow along with this guide (and to use Outkit), so if you don’t already have such an account, please create one now - we’ll wait.

All done? Great. In your Outkit account, click Backends, then New Backend. Select the name of the email provider in the dropdown. You’ll notice that a new section appears, called "Provider-specific configuration".

This is where you type in the configuration from your provider, whatever it may be. You may have to create an API token, generate SMTP settings, or something similar in your provider’s account first. Type in a description and an identifier, and you should be good to go.

Creating an API token

We’re almost ready for the fun stuff, but you’ll need an API token first. Click on your profile picture in the top right corner of your Outkit account, then select API Access, then New API Token.

There are several options here that you can explore later, but for now just click Create.

When the API token has been created, it’s important that you copy all three parts of the credentials: The key, the secret and the passphrase. The last two cannot be retrieved later, so be sure to note them down (securely) before moving on.

That’s it, we’re ready!

Submitting a message

In this final step we’ll use Node.js to submit a message. That may or may not be your language of choice, but you’ll be able to apply this same technique to whatever language you prefer. If you don’t have Node.js installed, you can either install it now or just read along for this part.

Create a new directory on your local machine, call it whatever you want. Then, cd into it.

Run the following commands:

npm install @outkit/outkit
touch index.js

Then open index.js in your favourite text editor and type in the following:

const Outkit = require('@outkit/outkit');

// Instantiate an Outkit client
const client = new Outkit.Client({
  key: '',           // Fill in your API key
  secret: '',        // Fill in your API secret
  passphrase: '',    // Fill in your API passphrase (not your personal password)
});

// Construct a message record
const messageRecord = {
  type: 'email',                   // Could also be 'sms'
  project: 'my-project',           // Project identifier - you can find it in the web UI
  template: 'my-welcome',          // Template identifier from the earlier step
  backend: 'my-backend',           // Backend identifier from the earlier step
  subject: 'Welcome, Jane!',       // Email subject
  to: 'some.name@example.com',     // Recipient address
  from: 'other.name@example.com',  // Sender address
  data: {                          // Named variables for the template
    name: 'John Doe',
  },
};

// Then, submit the message (you could also do this using async/await or Promises)
client.createMessage(messageRecord, (err, message) => {
  if (err) {
    console.error('ERROR:', err);
  } else {
    console.log('MESSAGE:', message);
});

Save the file, then run it:

node ./index.js

Congratulations - if you didn’t receive an error, you have just submitted your first Outkit message! Chances are it has already been delivered and completed, but you could have followed its progress live in the Messages tab of the web UI. You might want to submit another message and quickly switch to your web browser to see it in action.

Although there are quite a few lines of text in the code snippet above, you’ll just need to instantiate the client once in your app and share it somehow. And when you are done customizing your project and templates, you can skip every property that is set on the project or template. A typical message submission in a real app, without all the fluff, will look more like this:

const message = await client.createMessage({
  type: 'email',
  project: 'my-project',
  template: 'my-welcome',
  to: 'some.name@example.com',
  data: {
    name: 'John Doe',
  },
});

We’re biased, of course, but we think that’s a pretty nice way to be able to reliably send several types of messages using one API, with the ability to switch easily between multiple backends!.


What's Next

Now that you know the basics, it’s time to delve a little deeper. There’s a lot of great functionality waiting to be discovered. Here are some other pages worth exploring.

Messages
Templates
Projects
Backends
Webhooks