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.
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.
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
.
There are three main ways to control what content gets sent to the recipient:
- Using an Outkit template (by specifying its ID or identifier in the API call)
- Supplying your own template data in the API call for rendering by us
- 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.
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.
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
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.
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.