Sending nicely formatted emails using Mailgun and templates

In this article we will demonstrate how to use our favorite outbound mail provider with Flow XO to easily send personalized, nicely formatted e-mails using Mailgun's templates feature and the Flow XO Mailgun integration.

To accomplish this, we will need to take the following steps:

1. Sign up for a Mailgun account, if you don't already have one. Mailgun is robust and affordable outbound email provider that focuses on high deliverability and high throughput. If you don't already have an account you can get started for free for the first three months, and then pay a very low fee per thousand messages after that. 
2. Connect Flow XO to Mailgun and send a test message
3. Create and customize an email template in the Mailgun template UI and add some variables for later customization
4. Use the Flow XO Mailgun integration to fill in the customizable variables and deliver the template message
5. Modify the flow to use dynamic data to customize the message
6. Review next steps

1. Sign up for a Mailgun Account

You can do that here. Note that although the sign up page asks for a credit card number, you don't need one to get started, just uncheck the "Add payment info now" checkbox:

API Key

One you're signed up, you'll need to take note of your api key and your domain. Your API key is easy. When you first sign up, it is displayed in the welcome page:

You can also find it inside your account once you have confirmed your e-mail address:

Domain

You're domain in Mailgun determines the e-mail address that you will be sending FROM. Eventually you will need to set up your own custom domain for your company, like mycompany.com or mailer.mycompany.com. To get started though, you can use what Mailgun calls the 'sandbox domain' This domain restricts you from sending e-mail to up to 5 verified e-mail addresses, but works perfectly well for testing. To set this up, go to Sending -> Domains, and click on the "Sandbox" domain to enter it's configuration screen:

Once you have added and verified at least one test e-mail, you're ready to set up and test the integration in Flow XO.

2. Connecting Mailgin to Flow XO

Now it's time to sign in to your Flow XO account, or create a free account if you don't already have one. Navigate to the Flows page and create a new flow. We'll give it a name like 'Send Mailgun Email'. Give it a New Message trigger with a simple phrase like 'send mailgun message'. When you're done, your flow will look something like this:

Now we need to add a Mailgun task. Click the plus button to add a new action, then click Other Services and search for Mailgun. Once you add the Mailgun action, choose the 'Send Message' method.

Click Next. We now need to copy in the API key and Domain (please see where to get these from the sceenshots above) into the appropriate boxes on the Mailgun Integration configuration:

Click 'Test Connection' and then 'Next'. Now we need fill in the fields required to send our test e-mail.

You can put whatever values you want in these fields, but it is important, if you are using the Mailgun sandbox, to choose in the To field an e-mail address you already verified as a sandbox recipient in the Mailgun UI. See the section above on settting up Mailgun if you need help doing that.

Next, we'll add a simple Send Message after the e-mail is sent that writes out the ID of the email that we just sent, so we know it was successful:

Now it's time to test your connection. Open the test console and type 'send mailgun message' - you should receive a confirmation code in the chat, and in a few moments the e-mail should show up in your inbox. NOTE: When using the Mailgun Sandbox account there is a high likelihood that your e-mail will end up in your spam folder. Check there before deciding it didn't work!

Now that we have successfully configured and tested Mailgun with Flow XO, we can turn our attention to sending a good looking e-mail template. Mailgun comes with a handful of well designed e-mail templates that you can customize, or you can of course create your own. Feel free to read their documentation on their template system for a full overview.

For now, let's head back over to Mailgun, and click 'Sending', 'Templates' and 'New Template': 

3. Create and customize a Mailgun template

From the list of available templates, choose the 'Alert Template':

You will now be presented with the template editor. First, give your template a name. This is how you will identify the template later. Also give it a meaningful description. In our case, we're just calling the template 'my-alert' and giving it a generic description. To see what the e-mail will look like, you can click on the Preview tab. To see any variables you have inserted (we'll go over this momentarily) you can click the 'Test_data' tab

We could send this e-mail template exactly as is, but it wouldn't be very useful. We need to add some variables to the template so that we can pass in data that customizes the e-mail for each user. For our example we'll just add one variable to this template to control the number of "free reports" remaining, but in practice you will probably want to include more variables so that you can address your users by name, etc.

In the template editor, find the text 'You have' - this is where we'll customize the template to add a variable to send how many reports are remaining. Scroll to where the template says '1 report remaining' and replace '1' with {{REPORT_COUNT}}.

In the Mailgun template system, all variables are enclosed in double curly braces {{like_this}}. You can insert as many variables as you want using this syntax and when you send the template you will provide the values for these data which will get replace in the body of the e-mail when it is sent.

Click on the 'Preview' tab to see that the '1' was replaced with some test data. If you click on the Test_data tab, you can see a list of all your variables along with the test data that is inserted into the preview by Mailgun.

Click 'Create' to save your template

We are now ready to send this template via Flow XO.

4. Send the template from Flow XO

To send the Mailgun template using Flow XO, we will use another method on the Mailgun integration called 'Send Template'. Remove the 'Send Email' action you added earlier, and replace it with 'Send Template':

Because you have already set up a connection to your Mailgun account, there is no need to bother with the API key and domain again, just click 'Next' to use your already established connection. All the fields can be filled in identically to when we sent a normal e-mail (including ensuring the "To" field is a verified user from your Mailgun sandbox). The only difference will be the 'Template Name' and 'Template Variables' fields. Under the 'Template Name' field, find your template (my-alert) in the dropdown and select it. Next, we need to fill in the variables we want to send to the template. If you recall from the steps above, we added a single variable name REPORT_COUNT. So we'll add that to the report variables and give it a value. For now, we'll just type in a value, but later we'll pull the value from an attribute in Flow XO.

Click 'Next' and 'Save'. Before we test, we need to fix our 'Send a Message' action, because it was referring to data from the Send Email action that we deleted. We'll do that now:

Finally, let's test and see if it works?

Hurray! It worked! We can now send beautiful template messages from Flow XO with only a little bit of configuration. Our last step will be to modify our flow to get the data for the e-mail from a user attribute.

5. Sending dynamic data to your Mailgun template

In the previous step, we sent the number "5" as a variable to our template to indicate that the user had 5 reports remaining. However, in practice, this wouldn't be very useful. We need to send different information for each different user, and even for a particular user the data may change from time to time. So we're going to modify the flow to use an Ask a Question task to ask the user how many reports are left, and then send the answer to the template. In your real flows you might be getting your data from User Attributes stored in other flows, Google Sheets, an API call to a custom service, or from any number of other places. Please see the following resources for more on those topics: https://support.flowxo.com/article/141-attributes, https://support.flowxo.com/article/35-google-sheets, https://support.flowxo.com/article/22-webhooks

6. Next Steps

So you can now send nicely formatted e-mails using dynamic data to your users using a Mailgun account. If you completed this tutorial using the Mailgun sandbox account you got it working, but you can't quite use it in your business yet. That is because your sandbox account only lets you send to 5 verified addresses. To send to your audience, you need to configure and validate a domain. This will require you our your web developer to make a few DNS entries, but Mailgun is pretty good at walking you through that process. Once you have your new domain set up, you will need to create a new connection to Mailgun inside of Flow XO using your that new domain.

Please see Mailgun's documentation on setting up your domain: https://help.mailgun.com/hc/en-us/articles/360026833053-Domain-Verification-Walkthrough

One thing to note, if you have your top level domain (mybusiness.com) already tied to an e-mail provider, like GMail, Office 365, etc, then you will need to choose a "subdomain" for Mailgun to work with. This will most likely be something like "mailer.mycompany.com" or "mail.mycompany.com". This is how we have it set up at Flow XO. One thing to be aware of, though, is that if you use a subdomain like this if you try to send an e-mail from your top level domain, i.e. set the from address to me@mycompany.com instead of me@mail.mycompany.com, then the e-mail will be flagged as being send "on behalf of" and might have worse deliverability (more likely to end up in spam). It will look like this in your e-mail client, which also isn't ideal:

To eliminate the 'on behalf of' and have your e-mails appear like they normally would with a clean 'from' address, you need to put the subdomain in the 'From' field, meaning this:

me@mail.mycompany.com

instead of this

me@mycompany.com

If you want to control the display name, you can format the from and to fields like this:

My Name <myname@mail.mycompany.com>

This introduces another problem though, because when the user clicks 'Reply' they will be replying to myname@mail.mycompany.com and the e-mail probably won't be delivered as you expect. Therefore, you will want to make sure to fill in the Reply-To field of the integration with your actual e-mail address. The final result should look like this:

This way, when the user hits 'Reply' they address that will be pre-loaded will be your actual e-mail address, and you can have the best of both worlds.

That's it! We hope you've enjoyed this tutorial. Please don't hesitate to reach out to use at support@flowxo.com with any questions or feedback you may have. Happy flowing!