Tanay Karnik
640 words
3 minutes
Launch Your Email Newsletter with Kal in 15 Minutes: A Step-by-Step Guide

Kal is an open-source, self-hosted email marketing and newsletter app. It’s completely free and easy to set up. Plus, it’s serverless, so you don’t have to worry about servers and maintenance.

Ready to launch your email newsletter? Let’s get started.

Prerequisites#

Here’s what you’ll need:

  • AWS Account (free tier works fine; create one here)
  • An SMTP Server
  • The latest stable NodeJS (currently v20.15.0)
  • Git

You’ll need an SMTP server to actually send the emails. To get started quickly, you can also use your personal email account (like Gmail or Outlook) or choose from any of these free options.

Keep these SMTP server details ready:

  • Host
  • Port
  • Username
  • Password
  • Email (this will be your FROM email for the newsletter)

Installing Kal#

Configuring AWS CLI#

To deploy the backend to AWS, we need to set up access to your AWS account.

Generate your AWS credentials by following the instructions here. You should have an AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY.

Store the credentials in your $HOME directory at ~/.aws/credentials.

mkdir -p ~/.aws
touch ~/.aws/credentials

~/.aws/credentials:#

[default]
aws_access_key_id=XXXXXXXXXXXXXXXXXXXX
aws_secret_access_key=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

Now we can deploy the Kal backend to AWS.

Deploying the backend#

Clone the Kal GitHub repository and install the NodeJS dependencies.

git clone https://github.com/tanayvk/Kal.git
cd backend
npm i # or pnpm i

Kal uses SST Ion to deploy resources in the backend. SST Ion is currently one of the best frameworks for deploying full-stack serverless apps.

Install SST Ion with a simple command:

curl -fsSL https://ion.sst.dev/install | bash

Once SST Ion is installed, deploy the backend with:

AWS_REGION=us-west-2 sst deploy --stage prod

Feel free to use any AWS region and stage name. You can also deploy multiple independant instances of Kal using different stage names.

After the deploy finishes successfully, you should see an API endpoint created at the end. This is your backend API endpoint for managing the newsletter. We’ll need this when we configure the Kal CLI.

Screenshot of Kal API Endpoint

To start using the Kal CLI and connect it with a backend deployment, we’ll also need to generate a sender token.

First, come up with a secure string that you will use to generate sender tokens (this is your JWT secret). If you are not familiar with JWTs, think of this as your passphrase for creating sender user accounts on your deployment.

YOUR_SECRET_STRING="long randomly generated secret"
sst secret set JwtSecret $YOUR_SECRET_STRING

Now, generate the sender token by running the Node script and passing your secret string.

node create-sender.cjs $YOUR_SECRET_STRING

The script will output a sender token that you can use to configure the CLI. You can also create multiple senders by generating multiple tokens.

Make sure to store your secret string safely in case you need to create more senders later.

Installing the CLI#

Installing the Kal CLI is straightforward. Just download the latest binary release and add it to your $PATH. For example, on Linux:

cd /tmp
curl https://github.com/tanayvk/Kal/releases/download/v0.0.4/kal_Linux_x86_64.tar.gz
tar -xvzf kal_Linux_x86_64.tar.gz
sudo mv kal /usr/bin

In the future, there would be an easier way to install and update the Kal CLI.

Configuring the Kal CLI#

Navigate to a directory where you want to manage your newsletter from and run kal config. Kal will guide you through a step-by-step configuration process. Enter your Kal backend endpoint, sender token, and SMTP server details.

Screenshot for Kal config

Creating and Sending Emails#

To create a new email, run:

kal new your-email-title

This will open up your editor ($EDITOR) with a new markdown email:

---
Subject: Subject goes here
---

A fresh *new* markdown email.

[Unsubscribe]({{ unsubscribe_link }})

Write your email in markdown, and when you are ready, send it using:

kal send your-email-title

Screenshot of Kal Send

Subscribers#

Currently, Kal doesn’t have a frontend. To add subscribers, you’ll have to create your own subscription form or landing page and make POST requests to the Kal backend.

POST /sub

{
  "name": "Tanay Karnik",
  "email": "hi@tanay.xyz",
  "confirmed": false
}

Setting to confirmed to true bypasses double opt-in and skips sending the confirmation email to the subscriber.


And there you have it! You can now start sending emails with Kal.

Exciting new features are on the way:

  • Sequences and Automations
  • Analytics
  • Landing pages and subscription forms

Let me know what you’d like to see next. Also, don’t forget to star the GitHub repository.