How to Disable MJML and HTML Code Sanitisation

Product Support Mautic 6 Install/Upgrade Support
1

Hello,

Over the past week I have been attempting to code some new emails templates by cloning an existing template and then making code modifications to the twig files etc. I then create a segment email, open the custom theme and see what it looks like in the grapesjs wysiwyg builder. Once the email looks ok in the builder I go on to actually send the email to various email clients to see what they look like after being delivered.

Is there is an easier way of developing themes then I would love to hear your technique ?

Now the templates are coded in mjml which is simple enough however if you try and do anything more basic than adding or removing sections, columns and text etc then the likelyhood is that the builder sanitises or strips away much of any added advanced code. After a few days of head scratching why changes were not working I compared the code in the builder mjml and html windows and some of the customisation were no were to be seen in the html. A eureka moment.

And when you go on to actually send an email I think there is more sanitisation goes on in the background before the email is sent so adding just html code is not the answer either.

I understand that Mautic may do this sanitisation for security reasons however there is no clear indication that this sanitisation is occurring behind the scenes unknown to a new Mautic developer like me And I have to say its been a frustrating few days. No one would use a c compiler that removed code from the executable without giving some sort of fatal warning etc. Code sanitisation without a clear warning is ridiculous in my view.

I would please ask the developers for two things. Firstly issue a warning when you open the builder stating code can be sanitized and secondly a switch in the Mautic configuration so that we can turn this sanitisation feature completely off in an upgrade safe way. In the meantime I’m going to find a way to turn it off in the code. Any help would be welcome

Thanks.

1 Like
2

Hello,

A follow up to my original post.

I have also noticed that when you modify a theme twig file, Mautic does not always reload the file when you create a new segment email. Mautic must be using a cached or a database copy of the custom theme. Clearing the cache using the console command does not appear to clear this twig file or database cache.

Also the grapesjs build renders code inconsistently. If you make a small code change and then reverse the change the renders look different with regards to images. They view differently with different viewports. It weird.

Can a developer please assist with the following:

What mjml and html code sanitisation is being done on theme code and share how to completely disable this code sanatisation functionality in both grapesjs and mautic ?

Explain how mautic loads theme twig files and if they are cached by any means define how these caches can be cleared. I cant find any detail on it in the development documentation.

Explain how the mautic cache can be permanently disabled to speed up theme development.

Thanks.

3

firstly Maurtic is definetly using caching which is stored in /var/www/mautic/var/cache and can be cleared with an rm -rf on this diorectoryh or running the console command cache:clear.

Besides that Mautic holds both the MJML and HTML is different tables in the DB,

check out these two tables;
bundle_grapesjsbuilder
emails

4

Hello @mikew,

Thank you for defining the relevant tables I will take a look. I’m assuming that you mean you can modify email designs at the database level ? That’s a hard way to develop code.

I’ve tried clearing the cache however it made little difference in my case. Again how can you put Mautic 6.0.0 into developer mode and turn caching off while I develop some themes ?

If you base a custom theme on Brienz v2.0 and attempt the following customisations the code is sanitised - why ?

The theme has the following inline style. If you attempt to customise it by adding extra classes to the theme the code is sanitised and is not found in the html. Only the original is found i.e.

p, li {margin:0; padding:0;}

Any mso conditional code you add to the custom theme is sanitised and is not found in the html. However the converted html has mso conditional statements for other purposes. Why sanitise ?

The mj-hero tag does not display the full image correctly, it always displays a viewport unless you put a section underneath with the same image then the hero and the section underneath both displays the correct image. That mean the hero is being limited by the containing html. Without the ability to add classes to override then you cant fix the problem ? What are extra inline classes being sanitised ?

And more importantly how to turn this sanitisation off in mautic 6.0.0 ?

Another observation. When you create a new segment email you can choose the base theme and then you can click the builder and then view the code, you get two windows, mjml and html code, neither of which you can modify. Why can you not make any code changes to the mjml window at that point which is saveable and see the relevant changes in the html code in real time ? Why is editing being restricted at that stage ? I don’t understand why email design and custom coding is so restrictive ?

From my limited testing, Mautic 6.0.0 does well in delivering and tracking emails etc. However the inbuilt tools to edit and create the email in mjml and html are very restrictive. The wysiwyg/code designer needs a little attention in the next release to make it far easier to use ?

I would appreciate any help from those experiencing code designers and I would love to hear about your workarounds so I can generate some useful custom themes quickly using the example themes as the base. I dont need to reinvest the wheel with custom html

Thanks.

5

Hey @andrew_c3 I wish i could help more but this would be something for my dev team which is pretty backed up with plugin development at the moment.

The builder is using GrapesJS, maybe you can check out their github and see if you can get more details there

6

Hello @andrew_c3

GrapeJS can indeed be tricky to work with. I know it quite well, as I build a lot of email templates and have faced similar issues to those you’re describing.

Are you editing the email template directly inside the Mautic installation directory? That’s not the recommended way. There are articles explaining that you need to remove and reinstall the email theme properly for changes to take effect.

Yes, the editing mode is quite different from the final rendering. Always use the Preview to check how the email will look, not the GrapeJS builder itself. GrapeJS often adds margins and paddings to elements like mj-text that shouldn’t have them. A common trick is to apply a custom CSS class to reset the margin to 0px, for example.

Also, inside mj-text, you should wrap content in a <p> tag, even though it’s not strictly necessary—because it helps preserve line-height. Again, define a specific CSS class to set your desired line-height. These are just a few of many small workarounds you’ll learn over time.

MJML is built to be responsive, so it’s normal that the email looks different on mobile and desktop viewports.

Yes, some MJML components are not fully supported in the GrapeJS visual builder. They might appear broken in edit mode but render correctly in preview. Also, you don’t necessarily need mj-hero you can replicate the same effect using mj-section, mj-text, and mj-button. Just be mindful that background images can cause rendering issues in older versions of Outlook, so it’s good practice to always check compatibility.

MJML is a responsive framework that simplifies the creation of HTML emails. A single mj-button tag, for example, gets converted into a complex structure of table, tr, and td elements with client-specific attributes. The “Export MJML” button shows you this comparison between MJML and the rendered HTML.

If you want to edit the HTML directly, use the pencil icon (Edit Code). That opens the editable code view.

That’s a fair point. GrapeJS has been updated recently, and the Mautic team has added more features. Still, we don’t yet have a perfect solution that supports both MJML (for emails) and raw HTML (for landing pages) in the same builder. It’s a compromise.

Some of the issues you’re describing aren’t actual bugs, they’re simply limitations of the builder or a lack of knowledge around how GrapeJS and MJML work. It takes time and a lot of testing to get used to them. It’s definitely not something you master in five minutes.

You can check how I’ve built my Mautic email templates, study the CSS classes, and reuse them in your own templates, it might be a good starting point.

Alternatively, you might consider using a third-party builder like Stripo. You can design and code there, export the HTML, and then paste it into Mautic using the Code Mode editor. I’ve seen clients use that workflow successfully.

Hope this helps.
Best regards,
Ricardo

1 Like
7

Hello @ricfreire

Thank you for your wonderful reply. It has help a great deal. You should consider making a youtube video on theme development as it would have saved me many hours of work if it had existed before I started. Or may be even a blog post would be great too.

I installed my experimental theme by copying the theme folder structure into the themes directory and Mautic does detect the new theme and allows its use. Source ChatGPT.

I am developing the themes on windows using vscode and the mjml extensions which provides a good approximation of rendered output. Once I’m happy with that I copy the html.twig file into the theme html folder and Mautic does indeed use the amended file for a while and then completely stops after a few cycles. Removing the folder structure and puting it back on resets things for a while. I will use the install / uninstall from now on.

Installing and uninstall a theme zip for each development wash, rinse and repeat is a little cumbersome and time consuming. What about implementing a simple refresh function where you choose to refresh all or a specific theme. All the code must be there already, just needs a button on the menu. Maybe something the developers could consider for the next release ?

I have now found and read the articles about how themes work. It would have saved me a lot of work however with your detailed explanation of how it all works has helped a great deal.

Yes I will gladly take a look at your sample themes on github and learn your coding techniques. I’m sure it will save me lots more time. Thanks for the contribution.

Thanks.

1 Like
8

Hi again @andrew_c3,

I’m glad I was able to help and give you a broader perspective on the topic!

If you are considering making a feature request, which is absolutely valid, I would recommend creating a new post under the Feature Request category. This allows other users to upvote your idea, which increases the chances of it being implemented (but its not guaranteed).

Keep in mind that even good suggestions might not be prioritised right away, as there are often limited resources: both in terms of funding and people. Usually, bugs and improvements that directly impact the platform performance take precedence.

Your idea of writing an article that explains in more depth how to create a theme sounds very helpful, and I would definitely consider it! I’ve written a few other articles on my blog that might also be useful to you, feel free to check them out :slight_smile:

Best regards,
Ricardo

9

Hello @ricfreire,

I’ve had a quick look at your tech geek theme - looks great.

The code in html.twig and mjml.twig appears to be the same. Should both files be identical ? The Mautic Brienz theme only has html.twig and no html.twig.

Would you kindly explain ?

Thanks.