Simple setup of transactional emails for self-hosting with mailgun

I had always imagined that email would be hard work. Many VPS providers block outgoing email to help prevent spam, and I was never inclined to setup a gmail for smtp. Instead, I wanted a dedicated email domain that would act like a bot that links up various services and helps me stay on top of notifications. Turns out, it was pretty straightforward, and one day in, seems to be functioning as intended.

Step 1: Buying a domain

You could definitely use a domain that you already own, or use a subdomain off the domain you use for email (something like mg.example.com) but I didn’t want any chance that these transactional emails would affect the reputation of my main email domain for delivery purposes. Since the emails are only going to be received by me, there wasn’t a huge requirement to have the domain look nice. I chose to pickup a cheap dot com domain that I would use just for this purpose. You could go even cheaper and get a domain under the xyz tld. It shouldn’t make a difference unless your email hosting provider treats tld’s differently, and even then you should be able to override the spam filter for the domain and keep it allowlisted.

Step 2: Link the domain up with mailgun

Mailgun has a free plan which allows for 100 email sends a day, more than enough for a bot that will just be doing transactional emails. When starting out, mailgun wanted me to complete at least one email through the sandbox domain that they provide. This was probably setup to be both a hello-world example, and an additional barrier to prevent people from sending spam. After completing that email transaction (going through all the steps below but with the sandbox credentials), I could add the custom domain.

Similar to setting up a custom domain for services like SimpleLogin, the webpage walks you through all of the records that you should add, and then offers a button to check that you have set them up successfully. Note that when it lists the hostname, it includes the full domain name (mg.example.com), but in the domain records, you should just put the subdomain in the host field (mg). The verification tool is your friend, I wouldn’t advise proceeding until you see green checkmarks across the board.

The final record on the page is a CNAME record, which mailgun states will be used to track opens and deliveries. While at first this may seem off-putting (who wants to track people as they open email, not me!), the bot will just be going to your email. For this reason, I deemed it helpful to setup so that I can monitor for failed transactions.

Step 3: Integrate the SMTP details into an application

A super easy application to experiment with is rallly. This application is an alternative to whentomeetup and doodle, and crucially it uses magic links as part of the login flow, and can be setup in pikapods for $1 USD. When creating the pod, you will have the option to specify environment variables, and this is where all of the smtp information will go.

Note: In the table above, set [email protected] to use your new bot domain. Full documentation on the environment variables can be found in the rallly docs.

I have chosen to create a separate user for each service. You can create smtp users through mailgun by clicking the “Add new SMTP user” button under Send -> Sending -> Domain Settings -> SMTP credentials

Step 4: Testing it out

After setting the environment variables, click “add pod” and pikapods will begin spinning up the server. After about 30 seconds, you should be able to access the pod at the subdomain provided by pikapods (these are usually-.pikapods.com). The email you set as ALLOWED_EMAIL is the only one that will work for account registration, so make sure to use that when registering for the first time. If you have a use case for rallly long-term, you can setup your own domain for the server instead through a simple CNAME.

If all goes well, you will receive an email from the bot domain through mailgun with the magic link to sign in. Voila, you have just confirmed that everything works as intended!

If you don’t get the email, check the logs of the pod for more information on what went wrong. The logs are accessible by clicking on “more” and then “show logs”. Having port 465 specified is important for the TLS to work.

Conclusion

Now you have a working smtp system that can be used in other applications! I have chosen to also hook it into other systems and will definitely be adding more.