The templates provided by Postways are very powerful. You might be familiar with templates provided by other systems. However, usually when we talk about templates we refer to some sort of "HTML" template that contains a mixture of markup and variables. However, templates in Postways are a little bit different since they are not just HTML based. Templates in Postways define more then just the text you want to send.
Anatomy of a Template
Templates in Postways represent more than just HTML. In fact, templates in Postways allow you not only specify what is send as a message to a recipient, it also allows you to control over which channels those messages can be send on a template by template basis.
When you create a template in Postways you need to specify it's basic details, i.e. give it a name and an Id etc. A template in Postways covers the message for all channels that the template supports. E.g. you can edit the plain text email message and the HTML version but also the SMS text and or mobile push message text. This means that a template in Postways allows you to manage the message independed of how the message is eventually send.
All templates in Postways require some basic information. A template needs to have at least a Name and an Id. A template Name is simply used to be able to refer to the template within Postways. The Id on the other hand is purely used for the purpose of targeting the template when using the Postways API.
Make sure you give your template a meaningful name. E.g. if you create a template that's send out to new users who might sign up for your application, you might name your template something like "User New Signup". By starting the name of the template with "User" you give direct context to the scope in which this template is used.
Continuing the User New Signup example, following the same trend, you can give the template an Id such as
user-new-signup. Note how we're not using spaces in the Id but hyphens instead? Technically you are free to use what ever Id you find suitable but it is strongly recommended that you use the typical "system" style of naming when it comes to the template Id. Your developers will appreciate this. Once you have set the Id for a template, you usually don't want to change it since it will require you to make programmatic changes in your application.
You are free to give your template any description you like or otherwise leave it blank. However, it might be good to add a meaningful description since it will be easier to identify the purpose the template in the long term. E.g. someone who did not create the template might get some useful information in regards to the function of the template while browsing through the template overview page in Postways.
For new users, the template channels are probably the most confusing part of working with templates in Postways. In other transactional message services, if you want to send an email you specify an email address. In another service, if you want to send a mobile text, you specify a phone number, etc. In Postways it doesn't work that way. The idea behind this is that in most circumstances you don't want to specific channel selection logic as part of your application code. In your application logic you simply want to say; "send notification to recipient".
The approach Postways takes is that; simply send all information you have in regards to a specifc recipient (i.e. an email address, a phone number and/or a mobile push token), and Postways allows you to define in the template over what channels the message is to be send. By doing this, it means that the logic in your application becomes much simpler since your application doesn't have to know as much about over which channels a message is sent, other than the template Id and a list of recipients.
The Preferred Channels in the Channel settings of a template allow you to specifiy over which channels you prefer to send a message. E.g. you might want to send a message over mobile push since sending a mobile push is cheap and fast. However, you might not have a mobile push token for each recipient in which case the
push target is left empty (see Transmissions for more information on targets).
In the scenario that you don't have a mobile push token for a recipient you might want to fall back to sending an SMS instead. Sending an SMS is probably more expensive but its still a very fast way of sending a notification. However, it might also be the case that you don't have a recipients phone number, in which case you want to send an email.
Your preferred channels might be specified as:
- Mobile Push
- SMS / Text
In other words, the above means; send a mobile push if there is mobile push token, otherwise send an SMS if we have a phone number and if not, send an email if there is an email address specified. So, based on what target was specified only one of the above would be selected.
The Required Channels in the Channels settings of a template allow you to specific that you always want to send the message over these channels. In most circumstances you will only end up specifying one channel here but we can imagine scenarios where you might want to e.g. send both an SMS and an email.
Please keep in mind that for any of the required channels, the targets need to be defined in the recipient when calling the
/transmissions API endpoint. I.e. if no phone number is specified in a recipient then no SMS can be send regards if it was specified as a Required Channel.
When targets are left empty, Postways will simply ignore these and only send messages to valid targets and specified targets.
Under the Defaults settings of the template you specify the default title and body of a message. When you instruct Postways to send a message (by calling the
/transmissions API), Postways will create one or more messages for each recipient specified. Based on the specified targets of a recipient and the channels specified in the template, either an email, SMS or mobile push will be send. Each of these channels have their own characteristics but the default title and body serve as a fallback for each of the channels.
The Email settings in the template are used when an email is send to a recipient's email target. If you have filled out the default title and body then these are the values used for the email title of the plain text version of the email. If you wish to send the email also as HTML, you need to tick the HTML enabled? option and insert an HTML version of the message as well.
Beware of the Sender Name and the Sender Email. By default the Sender Name will be the same as the name of the Team the template belongs to. Usually this is correct. The Sender Email is important since this is the email address that the receiver of an email will see in their inbox. In the case of email, the Sender Name and Sender Email are combined to create the sender identity. E.g:
My Team <firstname.lastname@example.org>.
SMS / Text
An SMS text message usually has a much shorter body than an email and usually also doesn't have any line breaks. The SMS tab allows you to override the body specially for when an SMS version of the template is send. An SMS has no title but it does have a From. The From will by default fallback to the name of the Team, e.g. "My Team".
An mobile push notification usually has a much shorter body than an email. The Push tab allows you to override the body specially when a mobile push notification of the template is send. With Android push notications the title is used, with Apple it is not. Same as with SMS, you probably want to keep the body short.
The Callback channel is used to deliver messages to an HTTP endpoint. To be able to use the Callback channel it is required to set up a Callback Integration. The Callback Integration defines the default HTTP endpoint. However, this endpoint can be overridding through the Postways API.
All message fields can include variables, i.e. all title and body fields. For more information in regards to variables please see the Variables section.