Need SMTP? A Tutorial.

Ok, maybe I'm a little slow on the uptake here. You'd think with all the things I've fiddled with over the years that I'd be a lot more familiar with the workings of email than I am. But I do tend to sometimes go through periods of inebriation where I forget many of the things I previously learned. So, maybe we chalk it up to that.

I just spent a couple days here and there, attempting to get the new Calckey docker instance (from the previous tutorial) to send a test email. I initially thought I would setup Postfix on my VPS and use that. And after going through installing and configuring that several times, I found I was just not getting it to work from within Calckey, even though I was able to send a test email from the CLI on the host. I learned that Calckey uses Nodemailer to send emails, and Nodemailer requires a public facing SMTP server. So I think my issue with it not working in Calckey was that I was trying to use localhost and I also probably didn't have SMTP credentials setup properly. Both things I probably could have continued working on and sorting out... but.

At the recommendation of many others to utilize a service like Mailjet or Mailgun, instead of using Postfix on my VPS, I decided to uninstall Postfix. I wound up going with Mailjet as they didn't require a credit card for their free plan, which is nice. I then floundered around a good bit longer trying to figure out how to get Mailjet setup correctly for what I needed. I'm not sure what I had done wrong initially, but after getting some guidance from a friend that I was going about it the right way, I redid it all a second time and lo and behold, it worked.

So that's the backstory. For my own future reference, and for whoever else may need some simple guidance, I'm going to document what I setup here. Cheers.

In this example, we're setting up an SMTP server using Mailjet in order to allow a webapp (Calckey in this particular instance) to send emails of the administrative type. This would most likely be useful and applicable for really any application where you have a need to use an SMTP server to send emails. If you have something asking you for SMTP information in order for it to send emails, you can probably follow along with this tutorial.

For example, here is what the Calckey email configuration settings look like. We will be walking through the steps to create an account with Mailjet and set it up so we have the right information to input here to allow Calckey - or whichever other app you may be using - to send emails.

Screenshot of Calckey Email Config

Bear in mind that what I'm walking through here is what I did and what worked for me. There are certainly some things that can probably be done differently in some cases, depending on your needs and what you do and don't have access to.

A little more about my particular configuration just to give you an idea of the complete setup. I have a domain registered ( This domain is set to forward all HTTP traffic to my VPS, where I host all of my various self-hosted apps and this blog. I also have DNS entries added for this domain to allow me to create domain email addresses from within ProtonMail. What I needed was an SMTP server that would allow me to send emails from my VPS and various webapps. If your setup isn't quite the same as mine, you may need to sort out some individual differences from what I've detailed below.

So the first thing you'll have to do is create your account on Mailjet. Typical signup process here, nothing out of the ordinary. From my understanding, most of these services are very similar, so you don't have to use Mailjet of course. I only chose Mailjet after looking at a couple because their free plan didn't require a credit card.

Next step is to authorize your domain so Mailjet can send emails on behalf of your domain. You can set this up for individual email addresses, but in most cases I think it would be easier and better to just authorize your whole domain. Then you can use this SMTP server to send emails from any domain email address you may create.

You'll want to navigate to the Account --> Sender Domains & Addresses page. Then click on the Add Domain button. Put your root domain in, in my case, and save it.

Mailjet provides two methods for validating your domain. You can add a text file to the root directory of your web host, or put a text DNS entry in. I initially attempted the text file, but it didn't seem to work for some reason. The DNS validation worked perfectly. The instructions for both of these methods are detailed on the Mailjet site and I think easy enough to follow. Once it shows that your domain is validated, you can move on to the next step.

Now you'll want to navigate to Account and then click on SMTP and SEND API Settings. Note the details listed under the Configuration (SMTP Only) box, these are the details (along with your API Key values we'll get to in a second) that you will need to input into your application settings. These are always here and you can refer back to them at any time.

For now, click on the Retrieve Your API Credentials button. The free Mailjet account only allows one primary API key pair, and one sub-account API key pair. For now, I would just recommend setting up your primary and using that. Follow the instructions on the page to generate your API key pair, and make sure to save your secret value somewhere secure (like an encrypted secure note or something in the password manager you should be using).

This should be it now. You should now have everything you need to input into your SMTP settings of Calckey in order to send a test email. Your API keys are your user and password. The SMTP server and port are shown under your SMTP and SEND API Settings page. Make sure that the sender email you are using is for the domain you validated. In the screenshot above, you can see that I'm using the email address as the sender email, because the only domain I have validated to send from is I cannot use this server and credentials to send emails from any other domain.

Note, I was not having any luck sending an email when I enabled the Use implicit SSL/TLS for SMTP connections shown in the screenshot above. Leaving that off, everything works fine though. Maybe I'll learn a little more about what exactly that is and if it's actually needed or not. But for now, I'm just glad it's working.

  1. Previous Post
    Calckey Installation Tutorial
    Mon, Dec 12, 2022
    Tutorials Calckey Docker
    A basic tutorial for setting up a Calckey instance using Docker.
  2. Next Post
    Contributing. A Git Tutorial.
    Mon, Dec 19, 2022
    Tutorials Git
    A tutorial to help get started using git to contribute to an open source project.