How to send HTML emails using the MxModel reflection and Email modules
Everyday I receive over 100 emails. Some of them are important emails for work, some of them are adverts for websites I buy things from, a good portion of them go to a burner email address which I use for signing up to sites I don’t trust. And yet, in all these endless emails there are always a few which stand out. Visually gripping, well formatted emails are a definite must if you want your app’s emails to stand out above the rest.
So how do you make it happen? I find the best way is to use the Mendix Email module with templates in conjunction with the MxModel reflection module.
Why this way?
Last time I checked, there was more than 10 results for email modules in the Market Place.
So why would I choose this route above the others? The answer is simple : it’s quick, it’s easy, it’s reliable, and it comes with a built in overview to easily configure and style emails. This module also removes the need for any complex string handling in order to build up your email. Simply insert your tokens into the email template, and then using Model Reflection you can then replace the tokens with attributes from your domain model, all done with preconfigured examples available once you download the module.
Setting up the dependencies
After you download the email module into your desired Mendix app, you will notice some errors in your console. This is because the module has some dependencies on both MxModel Reflection and the encryption module. To resolve these errors, simply download both of these modules and configure them. All that is required is to include the snippets for the MxModel reflection in a page accessible to the app administrator. You will also need to set the encryption key constant, which can be found in the Encryption module. The key needs to be 16 characters in length, but otherwise thats it.
Running MxModel reflection
Once your app administrator can reach this functionality, they can navigate to it and they will see a screen which looks something like this
Here you can inspect all the modules inside your project. Select the module which has the data you wish to include in the email template, select it and click the synchronise button at the top of the page
It isn’t necessary to check every module, only the modules you need. Selecting them all will mean this action takes longer to complete, and it also fills your database with un-needed data.
Setting up your SMTP server
“An SMTP server is the machine that takes care of the whole email delivery process: that’s why to send your messages with an email client or software you need first of all to configure the correct SMTP settings “
As explained above, without configuring this step, no emails will be sent, so do this carefully, as typos in a password or username will cause this to fail every time.
I find the easiest way to test this bit is to use GMAIL as your server. Some people don’t know about this, but every single gmail account comes with an inbuilt SMTP server. And you can make use of this by enabling “Less secure apps” access to this, if you don’t allow this, gmail will block any requests to send emails from this app as it doesn’t trust it.
Once this is enabled you can enter the SMTP server settings in your email overview page as follows:
The settings for a gmail account are:
· SMTP server address: smtp.gmail.com
· SMTP username: Your full Gmail address (e.g. yourusername@gmail.com)
· SMTP password: Your Gmail password
· SMTP port (TLS): 587
· SMTP port (SSL): 465
After you have entered all required details, you can test your config by clicking the test button at the bottom of the page.
This opens a pop up which enables you to send a test email in order to check if its working.
If you got anything wrong, you will see something like this
If you got it right you will see a message like this
Setting up the templates
Now that you’re sending mails, it’s time to work on the look and feel of them. Impactful emails in my opinion are a combination of 2 things, data and design. Navigate to the email overview again, and go to the Templates tab. Click create new, give it a unique name and configure the from address, CC’s and BCC’s if needed. Fill in a subject line and then we can focus on the email body.
I tend to opt for using HTML emails, as you can add styles and buttons with clickable links attached to them, but you can use plain text if you want.
Fill in your email body, and the final step is to add any data you desire into your email, with the use of placeholders.
In order to include data, you will need to create some tokens or placeholders. Go to the place holder tab and click new, Here you can build up your placeholder by setting a token and description.
For type you can choose between attribute or reference, I chose attribute here, but this may differ in your implementation.
Next select your object and attribute by using the reference selectors to set this data.
The rest of the settings are optional, and you can skip these unless you have reason to.
Mine looks like this once finished:
The final step
Now that everything is configured, we can actually create a microflow to send these to users. The module comes with an example included called “CreateAndSendEmail”. I duplicated this and moved it into my NativeMobile module to avoid making any breaking changes.
The example uses $order and $customer as parameters for this, so I changed them to my $EmailInfo entity and $RecipientAccount entities.
I also removed the email template as a parameter, and retrieved it in this flow, you can skip this and pass the template as a parameter if you want. In order to retrieve the Template I perform an XPath retrieve and get the first template which satisfies this condition:
[TemplateName = ‘MyTemplateName’]
You don’t need to change anything else here, but I would recommend checking the ‘ReplaceEmailTemplateTokens’ Java action here, as your parameters may have changed.
You can now call this microflow where ever you want!
Read more
From the Publisher -
If you enjoyed this article you can find more like it at our Medium page or at our own Community blog site.
For the makers looking to get started, you can sign up for a free account, and get instant access to learning with our Academy.
Interested in getting more involved with our community? You can join us in our Slack community channel or for those who want to be more involved, look into joining one of our Meet ups.
