Configuring a custom SSL forward proxy for click tracking your branded link emails in Sendgrid
Tags: custom, ssl, sendgrid, email
Published: 2020-11-06 01:40:08

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](https://jornalia.net), a news aggregator API for argentinian sources) emails, the official [Sengrid documentation on this topic](https://sendgrid.com/docs/ui/account-and-settings/custom-ssl-configurations/) 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](https://www.digitalocean.com/community/tutorials/how-to-install-nginx-on-ubuntu-20-04-es) and [NodeJS](https://nodejs.org/es/download/package-manager/) on your server.
4. You have already verified your custom domain to brand your links on Sendgrid. Follow [their guide](https://sendgrid.com/docs/ui/account-and-settings/how-to-set-up-link-branding/) 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:
 
```nginx
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:
```javascript
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](https://certbot.eff.org/) to generate a Let's Encrypt certificate. To install Certbot, follow the [official guide](https://certbot.eff.org/lets-encrypt/ubuntufocal-nginx)

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](https://sendgrid.com/docs/ui/account-and-settings/support/) for them to enable the click tracking feature for branded links. Make sure you also [enable the Click Tracking setting](https://sendgrid.com/docs/ui/account-and-settings/tracking/#click-tracking).

---

That's all. Hope it helps!