How to send automated email sequences using Node.js and Candymail

The Candymail NPM package allows you to send marketing email sequences directly from your Node.js server from a single JSON file. Think of it as a docker.yaml but for email marketing.

How to send automated email sequences using Node.js and Candymail

Automated email sequences are an incredible marketing tool for any startup. An email inbox is one of the few 1:1 marketing channels at your disposal. Use it well.

The Candymail NPM package allows you to send marketing email sequences directly from your Node.js server from a single JSON file. Think of it as a docker.yaml but for email marketing.

Let's say we are building a brand new video editor for the web and looking to delight our new users. We can set up an Onboarding email sequence that welcomes our users and slowly introduces them to the platform.

Let’s get started.

Define the Onboarding Email Sequence

Here are 3 emails I would add to my sequence to onboard a new user:

  1. Welcome the user immediately when they sign up
Subject: Welcome to VideoMaker+

Thanks for joining! You're officially a part of the VideoMaker+ family! Join 100s of passionate film makers like you making a difference in everyday life by making the most wonderful content

2. 1 day later - Show the user the most basic way to get started with the platform

Subject: How to edit your first video?

Ready to get started? Here's how you can add subtitles to your first video and add some flair:

1. Record 1-min video of you talking into the camera
2. Import the footage into VideoMaker+ app
3. Click on Effects > Retro
4. Turn on: Automatic Subtitles
5. Export!

And that's it. You now have a retro looking video with auto-generated subtitles ready to be shared with the world!

3. 3 days later - Check up on how they're doing and gather feedback

Subject: A friendly check-in from VideoMaker+

Looks like you've been using VideoMaker+ in the last few days - and we love that! I just wanted to quickly check in and how your experience has been with our service.

1. How did you hear about VideoMaker+?
2. What do you like/dislike about VideoMaker+?
3. What can we do to improve your experience?

Now that we know what the content is going to look like. Let's create our automation file.

Create a new automation file

Candymail uses a single JSON file to describe the automation sequence. The above definition can be encoded into a candymail.automation.json like so,

{
   "automations":[
      {
         "name":"onboarding",
         "description":"Onboard new VideoMaker+ users",
         "trigger_name":"sign-up",
         "emails":[
            {
               "trigger":"time",
               "sendDelay":1,
               "subject":"Welcome to VideoMaker+",
               "body":"<div style='text-align:left'><p>Thanks for joining!<br/><br/>You're officially a part of the VideoMaker+ family! Join 100's of passionate film makers like you making a difference in everyday life by making the most wonderful content.</p></div>",
               "from":"[email protected]"
            },
            {
               "trigger":"time",
               "sendDelay":24,
               "subject":"How to edit your first video?",
               "body":"<div style='text-align:left'><p>Ready to get started? Here's how you can add subtitles to your first video and add some flair:</p><br/><p>1. Record 1-min video of you talking into the camera<br/> 2. Import the footage into VideoMaker+ app<br/> 3. Click on Effects &gt; Retro<br/> 4. Turn on: Automatic Subtitles<br/> 5. Export!</p><br/><p>And that's it. You now have a retro looking video with auto-generated subtitles ready to be shared with the world!</p></div>",
               "from":"[email protected]"
            },
            {
               "trigger":"time",
               "sendDelay":72,
               "subject":"A friendly check-in from VideoMaker+",
               "body":"<div style='text-align:left'><p>Looks like you've been using VideoMaker+ in the last few days - and we love that! I just wanted to quickly check-in and how your experience has been with the app.</p><br/><p>1. How did you hear about VideoMaker+?<br/>2. What do you like/dislike about VideoMaker+?<br/>3. What can we do to improve your experience?</p></div>",
               "from":"[email protected]"
            }
         ]
      }
   ]
}

Note: Remember to change the [email protected] to your own sender email address.

Set up a basic Express Server

Create a new folder.

Let's initialize our project by creating a package.json

{
  "name": "tutorialcandymail",
  "version": "1.0.0",
  "description": "",
  "main": "app.js",
  "scripts": {
    "start": "node app"
  },
  "keywords": [],
  "author": "",
  "license": "ISC",
  "dependencies": {
    "express": "^4.17.1"
  }
}

Install dependencies with a quick,

npm install

Add another file named app.js

const express = require('express')
const port = 4242

const app = express()

app.get('/', async function (
  req,
  res,
  next
) {
  res.send('Hello World!')
})


app.listen(port, () => console.log(`Listening on port ${port}!`))

We can now run our simple server by running,

npm start

Our application should be live at http://localhost:4242.

Install Candymail

Import the candymail.automation.file to the root level of the project directory.

Let's install Candymail by running,

npm install --save [email protected]

In app.js,

const express = require('express')
const path = require('path')
const candymail = require('candymail')
const port = 4242

const app = express()

const automationPath = path.resolve('candymail.automation.json')

candymail.init(automationPath, {
  senderEmail: '[email protected]',
  senderPassword: 'senderPassword',
  hostingURL: 'http://localhost:' + port,
})

candymail.start()

app.get('/', async function (
  req,
  res,
  next
) {
  res.send('Hello World!')
})

app.listen(port, () => console.log(`Listening on port ${port}!`))

Note: Remember to add your own GMail credentials to senderEmail and senderPassword.

Allow Gmail Access

Google has made it easier to give access to individual apps using App Passwords. For Gmail:

  1. Login at https://myaccount.google.com/security
  2. Click on App Passwords
  3. Add a new Gmail password

Now you can use the generated password with the email address to send emails.

Set up a "Sign Up" endpoint

Let's set up a /signup endpoint to capture when a user successfully signs up.

app.post('/signup', (req, res) => {+
	const user = '[email protected]'
  candymail.runAutomation('onboarding', user)

	console.log(candymail.getAllScheduledMessages())
	res.status(200).send('Signed up successfully')
})

Perfect! Now when the user [email protected] signs up, they will receive a sequence of 3 emails as part of the onboarding process.

But what if the user wants to not receive the emails anymore? Fear not, every email is sent out with an Unsubscribe link in the footer that makes a GET request to the /unsubscribe endpoint on your hosting server.

Set up Unsubscribe endpoint

app.get('/unsubscribe', (req, res) => {
  const { email } = req.query
  candymail.unsubscribeUser(email)
  res.send(`Sent an unsubscribe request for ${email}`)
})

Test it out

npm start

Let's fire up Postman and make a POST request to /signup . This will start the automation sequence - Onboarding. We are also printing out the scheduled messages to be sent out at what time. Notice that the time listed is in UTC.

We should expect 3 emails to be sent - 1 at the top of the next hour, the next one in 24 hours, and the one after that in 72 hours.

Simulating a user signing up using Postman 

Here's the first email I received in my inbox.

Sample of a welcome email sent to a newly signed up user

Every email comes with an unsubscribe link that the user can click on and they will stop getting future communications.

Next Steps

There we go! We just set up a brand new email marketing sequence with Node.js and Candymail for our new users.

Didn't find this guide useful? Let me know