Setup Email in a Mendix app in 10 Minutes or Less

Email functionality in an application is often a necessity, and setting it up can be cumbersome. Whether it is developing this functionality for a production application or rolling it out for a quick proof of concept, the following set-up guide aims to streamline the process. Utilizing the speed of the Mendix platform and its resources, this functionality can be rolled out within minutes rather than hours.

Initial Setup

The first step to setting up email functionality is to download the module from the Appstore. Mendix makes this process easy by allowing you to connect to the Appstore directly in your modeler. If you look for the shopping cart icon at the top right of your modeler, you can pull up the Appstore and start searching for modules or widgets.

The module that you are going to be searching for is called “email module with templates,” and once you find it, click the download button to import it into your project. Once the module is imported, you will notice that there are a few errors in the console. This is due to the email module having dependencies on other Appstore modules, and to fix those errors we need to import those as well. The additional modules you are looking for are called “Mx Model Reflection” and “encryption,” when they are imported the errors will be resolved.

Model Reflection Module

The reflection module is used for the template feature of the Email Template module. This allows you to create tokens to include in your template and will be replaced by data from your database before the email is sent.

Encryption Module

The encryption module is used to encrypt your SMTP password. The password will only be decrypted right before your email is sent.

Setting up Pages and Microflows

The first thing I like to do is create a module called “EmailCustom” that will extend the email module. Once the EmailCustom module is created you can create a page called “EmailAdministration” and include the “Administration” snippet, then add this to your navigation. This will give you access to all of the administration screens for email functionalities.

The next thing I like to do is add an entity in the domain model. Call this “EmailInfo” and add a string attribute to the table. This will be used when we create our first template and add a token to it.

Next, you will need to create a microflow that will be used when sending an email. There is a good example that is included in the Email template module called “CreateAndSendEmail”. Duplicate and include this microflow and drag it to your Email Custom Module. Then replace the parameter that called Order with the entity type “EmailInfo,” and the parameter called Customer with a string called “EmailAddress.” Once you do that you will get an error in the change activity in this microflow. Open the change activity and change the “To” attribute value to your email address parameter.

The final thing that you you will need to do is create a microflow that retrieves an email template and then calls Create and Send Email. Create a new microflow called “RetrieveTemplateAndSendEmail.” Add three parameters to this microflow, one will be of type EmailInfo, the other two will be strings called “EmailAddress” and “TemplateName.” The first activity that you want to use is the retrieve activity to retrieve your Email Template. Add this to your microflow and retrieve the template from database with this constraint “[TemplateName = $TemplateName]” (also make sure to set the range to first and the entity to EmailTemplate.” The next activity will be a microflow call where you can call Create and Send Email. Pass the email template, email address, and email info object to this microflow.

If you are interested in downloading the module that I described above you can dowload it here, and then import it into your project.

That’s not all!

Next, you will need to setup the Model Reflection module and the Encryption module. Add the Model Reflection administration page to your navigation; the page is called “MxObjects_Overview.” Then expand the encryption module and set a value for the constant called “EncryptionKey;” this value needs to be a sixteen-character string.

(Helpful Hint: Press CTRL + G to search for pages, microflows, or resources)

Run your Project

Now you can run your project. You can choose to run locally or to deploy to your sandbox. Once the project has compiled, click “View” to have it open in a browser.

When you open your project, the screen you land on is your home page. The first thing you should do is navigate to your Model Reflection administration page and press the “Click to Refresh” button, (make sure to check the EmailCustom module).

Next, navigate to the email administration page and perform the first-time setup. I like to use a Gmail address to send emails with, but you can use any smtp settings.

The settings for a gmail account are:

·         Gmail SMTP server address: smtp.gmail.com

·         Gmail SMTP username: Your full Gmail address (e.g. yourusername@gmail.com)

·         Gmail SMTP password: Your Gmail password

·         Gmail SMTP port (TLS): 587

·         Gmail SMTP port (SSL): 465

Once you have entered your credentials, you can click the “next” button and proceed with sending a test email.

Most of the time Gmail will block your Mendix app until you turn on the “Allow Less Secure Apps” setting. If you run into this issue, the error that will be returned will be that your password is incorrect. To allow less secure apps check out this Google article. 

If your email went through, congrats! You have just setup email functionality in your Mendix app. Now to take this a step further, let’s setup a template with a token, and then send an email from a microflow.

Templates

The first thing you should do is open the “My First Template” example. Then scroll to the bottom and find the ‘tokens” section. Here is where you can link an entity and its attributes from your database to your email templates. For this example, we will use the “EmailInfo” table in the EmailCustom module.

The select object would be “emailinfo” and then you can press “new” to create a token for each attribute in your selected object. In our case, there will only be one attribute in the email info table that we can create a token with.

The “token” field would be the name of your token, the “type” would be attribute, and the “attribute” field is where you would select “info.” When that is created you can add your token to the body of the email. To call your token you need curly braces and a percent sign around the name of your token. In this example our token would be “{%TestToken%}".

Now that your template is created, you can use it in a microflow to send an email. In the EmailCustom module that I created, there is a microflow called “Example_SendEmail.” Right click this microflow to include it into your project, and then put an email address in the email address variable. Or create your own microflow from this example.

Once that is done you can add this button to a page anywhere in your app to conduct the test.

Next run your application and then press the button that you just added. There will be a popup message if your email was successful, and you should receive an email in your inbox.

If you received the email then congrats! You just sent your first test email!