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

Messages

All you ever wanted to know about Outkit Messages.

Messages are what Outkit is all about - sending messages, in particular. We currently support two message types (emails and SMS/Text Messages), but we may offer more types in the future.

The way Outkit works is that you submit messages using our API, which we then forward to your selected backend, which they then deliver to the recipient. Simple - right? Yes, using Outkit really is simple, but that’s because we have worked hard to hide the complexity behind such a seemingly simple message flow. We also support at lot of useful functionality that may not be obvious when following our Getting Started guide, and most of that functionality is unlocked by setting different properties on the message objects that you submit to us.

In this article, we’ll dig deep into everything you can do with a message.

The basics

Arguably, the most important parts of a message are what type it is, who it’s for, who it’s from and what it’s about - which correspond to the type property, the to property, the from property, and the subject property.

Here’s how you specify these in the JSON message object:

{
  "type": "email",
  "to": "some.email@example.com",
  "from": "support@yourapp.example",
  "subject": "John invited you to join the Acme team",
  ...
}

Type is easy - it’s either email or sms, at least for now. It’s required.

The subject can be omitted if you have set a default subject in the template. Same for the from address.

The to property is required. Note that you can include a name in the to and from properties, like so, to provide a nicer experience in their email client:

{
  "to": "John Doe <some.email@example.com>",
  "from": "Yourapp Support <support@yourapp.example>",
  ...
}

For an SMS message, the to and from properties will typically contain phone numbers:

{
  "to": "+1-555-111-2222",
  "from": "+1-555-333-4444",
  ...
}

The exact format of these may depend on which backend you use.

Some SMS providers (like Twilio) also support using an alphanumeric identifier (up to 11 characters long) as the from address:

{
  "from": "AcmeCorp",
  ...
}

You should always send some test messages to verify that your provider supports the to/from formats that you are trying to use.

Outkit-specific properties

Every message must specify a project, like so:

{
  "project": "my-project",
  ...
}

You can either use an identifier/label, like we did above, or specify a project_id.

Another somewhat Outkit-specific property that you may want to specify is backend. If the project you have specified does not have a default backend for the selected message type, you’ll need to specify a backend when submitting your message:

{
  "backend": "my-backend",
  ...
}

You can also use backend_id.

Using a template or supplying your own content

There are three main ways to control what content gets sent to the recipient:

  1. Using an Outkit template (by specifying its ID or identifier in the API call)
  2. Supplying your own template data in the API call for rendering by us
  3. Provide pre-rendered HTML/text directly in the API call, bypassing our rendering entirely

You can learn more about the exact syntax that can be used in templates in the article on templates.

Here’s how you use an Outkit template by providing an identifier/label in the template property:

{
  "template": "template-identifier",
  ...
}

You can also specify a template by putting its ID in the template_id property:

{
  "template_id": "6ac4a27e-d847-4f0b-9076-cff3f03bc55b",
  ...
}

If you prefer to keep your templates as part of the source code of your project, you can simply send in their contents in the html_template_body and text_template_body properties, like so:

{
  "html_template_body": "<body>...{{some_local}}...</body>",
  "text_template_body": "...{{some_local}}...",
  ...
}

In this call there is no CSS/styles specified, so this implies that any CSS/styles must already have been applied to the HTML.

If instead you want to keep your styles in a separate file, and avoid applying them yourself, you can provde them in the property template_styles, and we’ll apply them to the HTML to generate inline styles:

{
  "html_template_body": "<body>...{{some_local}}...</body>",
  "template_styles": "p { color: red; }",
  ...
}

The final way to specify what gets sent to the recipient is to provide us with the actual contents in the html_body and text_body properties:

{
  "html_body": "<body>...</body>",
  "text_body": "plain text",
  ...
}

This will simply skip the rendering step entirely and send the content along unmodified.

Data for your templates

If you decide to use templates, whether it’s Outkit templates or your own, you’ll probably want to send some locals or variables. These are pieces of data, with a name, that will be injected into the rendered version of your templates. So, for example, if you used Hello {{name}} in your template, you’d supply the value for name like this:

{
  "data": {
    "name": "John Doe",
    ...
  }
  ...
}

... which would then be rendered as Hello John Doe. There’s a lot more to learn about locals/variables (you can define default values on both the project and team, which can then be overridden per template, or per API call), but you should go to the article on templates for that.

Synchronous processing

By default, submitted messages are queued for rendering and delivery. In some cases you need to get the full message (including the rendered result, delivery status etc.) back from the API call instead of just the waiting-to-be-queued version, which contains not much more than you submitted, except the ID.

The way to achieve synchronous processing is by setting the sync flag to true, like so:

{
  "sync": true,
  ...
}

That’s all there is to it from a technical perspective, but there are some additional things to be aware of:

  • Synchronous processing is severely limited for accounts without a payment method
  • There is currently a limit of 100.000 sync messages per month for accounts with a payment method
  • Synchronous processing incurs additional charges - see our pricing page

Render-only

Some users prefer to handle message delivery themselves, but could use a simple, hosted way to render their templates. Outkit works well for that use-case too. Simply pass "render_only": true when submitting your message, and we’ll simply render it without trying to deliver it somewhere. Like so:

{
  "render_only": true,
  ...
}

This works equally well if you’re using Outkit templates or feeding us your own.

It is common to use "sync": true in conjunction with this flag, to avoid having to set up webhooks with a corresponding listener just to be notified when your template is done rendering.

Misc. properties

You can set "test": true to trigger test behaviour - meaning that the message is not delivered to the address in the to property, but to the test recipient that has been defined on the project or team.

If you want to match Outkit messages against some database in your own app/project, you can set id_from_submitter to a string value of your choosing. Just note that it needs to be unique for your team.


What's Next

Now that you understand messages, you should read up on templates.

Templates