20 Nov 2018 • BLOG - News
How to Set up Template Error Management and Why We Need It
20 Nov 2018
Testing your email templates is tough. Who wants to be checking thousands of code lines for 50 different templates?
That’s why choosing a bug reporting process is necessary. At Mailjet, we are trying to make it as easy as possible for you to do this with our Template Error Management options. Read on and we’ll tell you what error reporting is and why you’ll love it.
What is error reporting?
Good error reporting is essential when building and debugging email templates. No one wants to look at a template for hours, just to see that one small comma is missing… You know the feeling when you want to break your screen with your keyboard? We do and we know how unpleasant it is.
As you can imagine, filling out manually a big bug report can take a while. If you need to report dozens of bugs during a testing session, it could take you several hours for one template… This would be painful.
There are many different elements you can include in your bug report. However, using a bug tracker is probably the best way for your organization to move bugs from reported to fixed and help you stay focused. As powerful as bug tracking tools are, the big problem is that you need every person working on the templates to use them and to know how to manage them. But how do you explain to a marketer what “node” means?
Mailjet’s error reporting is super easy to use for developers, because it gives you a headstart and shows you what to fix and where. For non-developers, it helps to provide more details to you instead of having to rely on insufficient information like say “I got blank / white page”. We all know how no one touched anything, but still something is not working…
Template error management at Mailjet
Our goal at Mailjet is to make our products as easy to use as possible. You already know that using our template language is a piece of cake, but it is possible that you missed one curly bracket or a variable was not written correctly and this is breaking everything.
Or you sent the template to the design team to put all the appropriate colors for your brand and someone removed something that seemed strange to them. In fact, it was the most important part of the amazing loop you created.
We don’t want you to waste your time digging into what went wrong, and so we built a solution for you – Template Error Management! We are offering two options:
- Template Error Reporting
- Template Error Deliver
Template error reporting
Have you ever sent an email but it was not delivered? This could be because our system detected an error with your template and aborted the sending. The main purpose of our template error reporting option is to send you an email to let you know that there is something wrong and provide a detailed explanation of the issue. Here is how it works:
- You create a beautiful email template
- You compose your API call and declare all of your variables in it
- The email is sent by you to our system
- Our system checks the template and replaces all the variables with their corresponding values
- Our system finds an error
- The sending is stopped unless you chose otherwise
- Mailjet sends you an email with the error details
So, the first two steps are something that you usually do just perfectly, but this time there was one small mistake in your template. If you have one big template full with loops and conditions, checking everything manually could take forever. This is why we are offering our template error reporting.
To activate it you only need to add this piece of code in your API call:
"TemplateErrorReporting": { "Email": "youremail@yourdomain.com", "Name": "Your name" }
It is important to write the correct email address, because our system will send the report to this address.
These reports should not be an issue for you because the errors are pretty self-explanatory, but we’ve provided some examples of the most common errors below:
unexpected end of template:unfinished end of node ## near ## {{var:url – One of the variables are not closed correctly. In our example above, the variable is missing two closed brackets (i.e. }}) at the end and because of this our template language engine is not recognizing it and cannot compile the template correctly.
not valid template – the template you chose is not the correct one. Most likely the ID does not correspond to the right one. Our system is not detecting the variables you declared in our API call in the template, so you should first check if the template’s ID is correct.
unknown node ## near ## – There is a syntax error in the template. You should check if you have declared all the loops in template language sections.
“var:firstname” is not an array value – This error is generally returned when you try to loop on a non-array value. If you set up a loop as this {% for fn in var:firstname %}, you should declare something like this in your API call: {“firstname”:[“Jane”,”Joe”]}. If this is not declared, our system cannot compile the variables.
No value for “var:items” – you haven’t set up the variable in your API call. If a variable is not declared, our system is not able to replace it in the template with the corresponding value. We don’t want to send a template with {{var:items}} in it, because the recipient wouldn’t know what this should be.
expression parsing error ## Unknown identifier: var:day ## near ## {{var:day ## – This error indicates that the “day” variable is not defined in your Vars. It can be fixed by adding the default value for the variable or making sure that you pass all the variables required by the template.
expression parsing error ## Unknown identifier: day ## near ## {{day ## – This error is similar to the previous one, except for the absence of namespace (var or data). It can indicate that you forgot to specify whether you want to use a Send API variable var:day or a contact property data:day. It can also indicate that you are trying to use a template variable that is not defined in a set function nor a loop statement.
not valid template ## near ## y}} ## – This error occurs when the statement is not finished – missing {% endif %}
What should you do when you receive ## Unknown identifier: var:day ## near ## {{var:day ##, but you don’t see such variable in your template?Well… did you update the plain text version of the template? If the plain text version of the template is not updated, it still contains all the old variables and our system is still trying to compile them. This is why it is better to use our template error reporting. It is much easier for you to manage your templates and to fix some small errors that happened for any given reason.
Template error deliver
This second option determines if the message should – or should not – be delivered to the recipient in case of an error while processing the message’s template language. If the below line is not added in your API call, our system will assume this option is not enabled by default:
"TemplateErrorDeliver": true
What does it mean? If you don’t have this small code in your API call, in case there is any error in your template, the email won’t send. Our system will detect the error, it will send you an email with the error report (if you have switched on the Template Error Reporting option of course), and it will not proceed with the sending of the template to your recipients.
However, if you are still in the testing phase, it might be helpful to have this activated. If there is an error in your template, you will receive the error reporting, but you will also receive the uncompiled template itself. Our system will detect the error and will send you the error report email. However, our system will also see that the Template Error Deliver is active and it will send the emails anyways, just as they are.
So the recipient will see all the loops and variables without them being replaced with the data you set up in your API call. Yes, the template won’t look as pretty as it should (and as you and your great design team created it), but it will give you some general idea on how the template will look.
If you want to avoid any errors once your templates are in production, it would be better to remove “TemplateErrorDeliver”: true from your API call. You won’t risk having your template delivered, which will avoid any confusion from your contacts.
It is still helpful, though, to keep the Template Error Reporting element active so you can receive an email if there is something wrong with your template.
Template Error Management helps you resolve all issues with the template language in your email templates without losing a lot of time and nerves. Our dedicated API support is always here to help you resolve your issues, if you need any additional help identifying the problem or understanding the error you received via email.
If you want to be the first to get the next useful tips we are going to publish, follow us on Twitter and Facebook. Make sure not to miss a thing!