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

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: [e-mail], 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:

1. You have an understanding of a Unix shell
2. You are using Ubuntu Server 20.04 on your server instance.
3. You have installed NGINX and NodeJS on your server.
4. 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:

1. A NGINX instance acting as a reverse proxy that will handle the requests and sending them to a NodeJS app.
2. 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!

Comments

[Ritik Raj]

I spent a lot of time trying to set up branded link click tracking with Sendgrid, and the official documentation didn't provide enough clarity, especially when dealing with network configurations and system admin tasks. After struggling with a couple of issues, I decided to implement an SSL forward proxy to ensure my tracking requests went through securely. The steps provided here, especially regarding setting up NGINX as a reverse proxy and configuring the Node.js app with Express, were a lifesaver. The guide helped me get everything working, from setting up SSL with Certbot to configuring SendGrid’s branded link tracking.

If you're having trouble like I did, I highly recommend following this setup carefully. It solved my issues, and I managed to get everything running smoothly.

For NGINX installation on Ubuntu 24.04, check out this guide, which was super helpful when I had to configure NGINX properly for SSL and reverse proxy setup.

Hope this helps someone else avoid the pain I went through!

[Megha Khateek]

"I had quite a bit of trouble setting up the SSL forward proxy with NGINX and Node.js for branded links in SendGrid. The process of configuring the reverse proxy in NGINX and then connecting it to my Node app felt a bit overwhelming at first, especially with all the SSL and DNS configurations involved. However, after a lot of trial and error, I finally managed to get everything working smoothly.

If you're facing similar issues, I highly recommend checking out this guide on installing NGINX on Ubuntu 24. It was incredibly helpful and really cleared up some of the confusion for me. I’m grateful for these resources that helped me get past the struggles of SSL setup and proxy configuration. It worked perfectly once I got everything aligned!"

Let me know if you need anything else!