Behavioral email is automated and targeted messages sent to customers based on their actions or behavior. By triggering on how your customers interact with your website or product, you’re able to send email whose content is actually aligned with what they’re doing, and will therefore be far more likely to resonate.

API companies are unique ly positioned to take advantage of behavioral emails; If monitoring and analytics is done right, then insights into what’s going on deep within the platform can be surfaced; And insightful, or even prescient, communiqués can be made.

Common capabilities of behavioral email in API platform companies include helping developers speed API integration & try out new product features, and keeping customers informed on subscription & platform issues.

In a prior article , we covered the capabilities of Moesif’s behavioral email solution, and in a companion article we detailed the top 5 behavioral emails every API product company should use.

In this post we’re going to break down what it would take, technically, to build your own behavioral email solution.

What’s required to build your own behavioral email solution?

A behavioral email product consists of at least three parts:

A methodology to get monitoring data from an API
A way to define rules and validate the monitoring data
A process to send specific emails to users when a rule is met

Acquisition of monitoring data from an API

Depending on how confident you feel, you could build a whole monitoring solution from scratch, or you could employ an off-the-shelf open-source system such as Prometheus.

Prometheus is a monitoring solution for microservices. By including a Prometheus client in your application, it can be called when you want to record a metric. The Prometheus server will then poll the data source at regular intervals and persist the result. The Prometheus docs have a setup guide to help with installation.

Prometheus clients come with default metrics configured out-of-the-box, so you don't have to manually set up basic stuff like CPU or memory monitoring.

For a Node.js/Express.js based API, you can install the Node.js client for Prometheus via NPM and configuration only takes a few lines of code:

const prometheus = require('prom-client');
const register = new prometheus.Registry();
prometheus.collectDefaultMetrics({ register });

The default metrics are fundamental and not API related, so you would have to set up more complex metrics yourself.

The code for a very simple API metric might look like:

const activeRequests = new client.Gauge({
  name: 'activeRequests'
});
registry.registerMetric(activeRequests);
api.use((req, res, next) => {
  activeRequests.inc();
  res.on('close', () => activeRequests.dec());
  next();
});

From our article the 15 most important API metrics you should be tracking, Prometheus only covers the first three metrics we identified, the rest have to be defined with custom code.

Defining rules and verifying data

Once you have monitoring data stored in Prometheus, you need to test whether customers did something that would trigger a behavioral email. As its name suggests, behavioral emails require us to look at user behavior.

For this, you’ll have to set up a service that lets you define email rules, poll the monitoring data and verify the data against your rules.

To poll the data, you can use PromQL, Prometheus' query language that allows gathering data via an HTTP API. After you’ve gathered the required data from Prometheus, you can use logical operations, wildcards, and regular expressions to define the rules that should be queried with the monitoring data.

A custom Prometheus metric for responses with status 400 could be defined as below. Using the label feature, custom data such as userID can be added to every value that's tracked:

const status400 = new promClient.Counter({
  name: "status_400",
  labelNames: ["userId"],
});

expressApi.use((req, res, next) => {
  res.on("finish", () => {
    if (res.statusCode == 400)
    status400.labels(req.session.userId).inc();
  });
  next();
});

If you want to get the errors in the last 24h, you’d have to poll them with this PromQL query:

status_400{userId="abc-123"}[24h]

Writing these queries quickly becomes complicated and, if you’re not an engineer, particularly difficult. Would you task the average business person with writing a query like this:

rate(http_requests_total{status_code=~"5.*"}[5m]) / rate(http_requests_total[5m])

Probably not. So you also have to build an editor. Either visual or with some simplified rules language and autocompletion, so a person without an engineering degree can set things up.

Depending on the sophistication level of this rule editor, it could automatically generate the required PromQL from the data specified in the rule. You’d also need another visual editor to allow people to put together their data requirements.

Sending emails to users

The last part of the system is actually sending the emails. You need a way to define email templates that get filled out with user data, and then you need to make sure they correspond to the rules you described in the previous step.

Again, depending on your email creator's technical skills, this could require a more refined editor. Today, many people are confident to write HTML and CSS, which is a good thing because rich text emails have been shown to be more successful than plain text ones.

We've already associated a unique userID with every Prometheus metric, so we now need to find the emails that belongs to that ID. The email system needs to access the user's account data, which in most cases will mean connecting to a SQL database and querying the user profiles within it. Such as SQL query might look something like this:

SELECT firstName, lastName, email FROM Accounts
WHERE userId=abc-123;

Getting the emails delivered to your customer's inboxes is another problem. If you build your own email server, they could end up in a spam folder. The typical way to resolve this issue is to integrate with an email delivery service on the allowlists of major email providers.

One of those providers is SendGrid. They offer an API you can use to send emails via their services directly from your backend. Their Node.js package is straightforward to use. It even comes with a batch feature, so you can send multiple emails at once, which is a nice addition for our use-case.

An example integration with SendGrid could look like this:

const sendgrid = require("@sendgrid/mail");
sendgrid.setApiKey(SENDGRID_API_KEY);

sendEmails([
  {
    to: "recipient1@example.org",
    from: "sender@example.org",
    subject: "Hello recipient 1",
    text: "Hello plain world!",
    html: "<p>Hello HTML world!</p>",
  },
  {
    to: "recipient2@example.org",
    from: "other-sender@example.org",
    subject: "Hello recipient 2",
    text: "Hello other plain world!",
    html: "<p>Hello other HTML world!</p>",
  },
]);

async function sendEmails(emails) {
  try {
    await sendgrid.send(emails);
  } catch (error) {
    console.error(error);
    if (error.response) console.error(error.response.body);
  }
}

Maintenance of your home grown system

After you build your system, you’ll also need to maintain it. It’ll require updates, bug fixes, refinements, and maybe, as you grow, more hardware to scale.

It’d be best to be able to share how your emails perform, so that colleagues, managers and partners are aware of how it’s doing:

What rules actually got triggered?
Do emails get delivered?
Are emails opened?
How many customers opened which email?
What did they do with your API after they opened the email?

A user interface that visualized email data, so it can be efficiently shared across your company should also be built and maintained.

Summary

Building a behavioral email platform isn't magic, and can be achieved by proficient coders who know their way around API monitoring. Open source tools can be leveraged to get up and running more quickly, without needing to build everything from scratch.

But, there’s still a ton of custom code that’s required to integrate these tools. A behavioral email platform needs to be operated by non-technical team members, which requires building graphical user interfaces like editors for creating queries, rules and email templates. A dashboard that allows you to view what’s happening would also be preferable.

Building these GUIs is very code intensive, and is a time-consuming undertaking. If you run a small API company or don't want to invest in building and maintaining monitoring and analytics tools, you’re better off using a tool like Moesif.

Moesif specializes in API analytics and monitoring, and has already gone down the path of building a behavioral email platform from scratch. Our scalable solution can handle billions of API calls and thousands of emails, and takes only a few lines of code to integrate into your platform.

Looking for a complete customer-centric API analytics solution? Check out Moesif!

This article was originally written for the Moesif blog.

Build vs. Buy Behavioral Email Platform for API Product Companies