Configuring a custom SSL forward proxy for click tracking your branded link emails in Sendgrid

Francisco Hanna — Fri, 06 Nov 2020 01:40:08 +0000

When you setup your Sendgrid emails to have branded links, that is, that the mail from that your customers see when receiving an email from you says something like From: bob@yourdomain.com, then, to enable click tracking of your emails, you need to pass the requests through a SSL forward proxy before sending the tracking requests to Sendgrid (at sendgrid.net). This proxy must live under your custom domain, or in a subdomain of it.

In this article I will show you how to setup a custom SSL configuration to enable click tracking over branded links in Sendgrid.

I'm writing this because, while configuring the click tracking for our JSON API service (Jornalia, a news aggregator API for argentinian sources) emails, the official Sengrid documentation on this topic it's not clear enough, specially for people not too familiar with networks and systems administration.

I'm assuming that:

You have an understanding of a Unix shell
You are using Ubuntu Server 20.04 on your server instance.
You have installed NGINX and NodeJS on your server.
You have already verified your custom domain to brand your links on Sendgrid. Follow their guide if you haven't do this yet.

Setting up the SSL forward proxy

For this, we are going to use:

A NGINX instance acting as a reverse proxy that will handle the requests and sending them to a NodeJS app.
A NodeJS app built with Express, that will forward the requests to sendgrid.net.

Configuring a NGINX reverse proxy

Open your NGINX's default sites-available file, running:

sudo nano /etc/nginx/sites-available/default

Add the following server block to the default file, where url1234.yourdomain.net is your branded link for tracking that you obtained while validating your custom domain on Sendgrid:

server {
        server_name url1234.yourdomain.net;

        location / {
                proxy_pass http://localhost:7000;
                proxy_http_version 1.1;
                proxy_set_header Upgrade $http_upgrade;
                proxy_set_header Connection 'upgrade';
                proxy_set_header Host $host;
                proxy_cache_bypass $http_upgrade;
        }
}

Adding a CNAME for your branded link.

Add the following records to your domain's DNS zone (the first one may already be there, 63.98.25.184 would be your server's IP):

Type	Name	Content
A	yourdomain.com	63.98.25.184
CNAME	url1234.yourdomain.com	yourdomain.com

Build and run a forward proxy with Node and Express

Crete a new folder on your server named mail-proxy. Move inside that folder and run:
npm init -y
Then, install the following packages:

npm i express morgan http-proxy-middleware

Create an index.js file and add the following content:

const express = require('express');
const morgan = require('morgan');
const { createProxyMiddleware } = require('http-proxy-middleware');

const app = express();

const PORT = 7000;
const HOST = 'localhost';
const SENDGRID_URL = 'https://sendgrid.net';

app.use(morgan('dev'));

app.use('/', createProxyMiddleware({
  target: SENDGRID_URL,
  changeOrigin: true,
  secure: false,
  headers: {
    'Host': 'url1234.yourdomain.com'
  }
}));

app.listen(PORT, HOST, () => {
  console.log(`Starting Proxy at ${HOST}:${PORT}`);
});

This simple Express app listens for requests on PORT 7000 and the handler for the index / is a http-proxy-middleware instance, that forwards every request to sendgrid.net.

Now, install pm2 (a Node process manager), and run your forward proxy, like so:

npm i -g pm2
pm2 start index.js --watch

Securing the proxy with SSL

For this, we are going to use Certbot to generate a Let's Encrypt certificate. To install Certbot, follow the official guide

After you have installed Certbot, run the following command on the terminal to generate a SSL certificate your for branded links domain, like so:

certbot --nginx -d url1234.yourdomain.com

Contact Sendgrid

After you have configured your forward proxy, you need to contact Sendgrid's Support for them to enable the click tracking feature for branded links. Make sure you also enable the Click Tracking setting.

That's all. Hope it helps!