How to Set Up SSL Link Branding with Sendgrid and Nginx

In this tutorial we will learn how to set up link branding in Sendgrid, using our custom subdomain and HTTPS.

At Mindee, we use Sendgrid for sending emails to our customers. These mails have various purposes and most of them contain a CTA (call to action) that is materialized by a link.

We want to track the links that are being clicked in each email. Therefore the links we want to insert cannot be sent as it is, but instead will be sent by default to Sendgrid, and then redirected to the right link.

We want to track the links that are being clicked in each email. Therefore the links we want to insert cannot be sent as it is, but instead will be sent by default to Sendgrid, and then redirected to the right link.

For example, suppose we want to add https://mindee.com in our mail template; Sendgrid will rewrite it to a unique link like https://sendgrid.net/ls/click?upn=xxxx. When a user clicks the link, it will first pass to Sendgrid, which allows the link to be tracked, and then redirected to https://mindee.com. However this approach has one caveat: the URLs in our emails start with sendgrid.com, which doesn’t look very professional. Fortunately, Sendgrid allows us to use our own subdomain instead.

Setup Link Branding

From your Sendgrid dashboard,

1. Go to Settings > Sender Authentication. Then go to the “Link Branding” section and click “Brand your links”.
2. Select your DNS provider and continue.
3. In the “from domain” input, add your custom domain, for instance example.com.
4. Under “Advanced Settings”, select “Use a custom link subdomain” and fill the “Return path”.  This path will correspond to your custom subdomain prefix, e.g, if you use “mailing”, your custom subdomain will be mailing.example.com.
5. Finally click “next”. Sendgrid will ask you to copy some DNS records in your DNS provider.
6. Follow the instructions and click “verify”.

Add HTTPS

After these steps, link branding should work properly. Links that you see in new emails should start with your custom subdomain.

However, you will notice the links are served through HTTP and not HTTPS. For instance, your link might point to http://mailing.example.com instead of https://mailing.example.com. This is very detrimental especially because some browsers (including Chrome) block links that are not secure.

Sendgrid disables https for the following reasons:

When a user clicks on a link, the traffic must be forwarded somehow to sendgrid.net, so that Sendgrid can perform tracking. In our current situation, this forwarding is made with CNAME records from mailing.example.com to sendgrid.net. With this setup, https links for mailing.example.com are not possible because Sendgrid would need a valid SSL certificate for mailing.example inside the sendgrid.net server.

To resolve this, we will forward traffic to sendgrid.net with our own web server. Global instructions for these steps are written in the SendGrid documentation at Custom SSL Configuration. We will see a concrete implementation of this with Nginx.

Create a NGINX Web Server

For this step, you need to create a web server with Nginx and an A record pointing to the server. The steps depend on each cloud provider. An example of what we did at Mindee with AWS EC2 and route53 :

• create an EC2 VM and install nginx
• create an A record in Amazon Route53, from sendgrid.example.com (or any new domain) to the Virtual Machine IP.

After this step, you should have a server running with nginx and accessible from your new subdomain (sendgrid.example.com).

Create an Nginx Rule

Create an nginx rule for this server, listening to your branded link’s url (in our case, mailing.example.com) and forwarding the traffic to sendgrid.net, and setting the Host header to mailing.mindee.com .

Create a new file sendgrid.conf in /etc/nginx/conf.d/ and add the following content :

server {
	server_name mailing.example.com;

    listen 80;
	listen [::]:80;
	 
	location / {
    	proxy_pass http://sendgrid.net;
    	proxy_set_header Host mailing.example.com;
	}   
}

server {
	server_name mailing.example.com;

	listen 443 ssl;
	listen [::]:443 ssl;
    
    ssl_certificate /etc/nginx/ssl/fullchain.pem;
    ssl_certificate_key /etc/nginx/ssl/privkey.pem;
    
	location / {
    	proxy_pass https://sendgrid.net;
    	proxy_set_header Host mailing.example.com;
	}   
}

This rule will forward all the traffic from mailing.example.com to sendgrid.net. You also have to create SSL certificates from this server. This certificate must be valid for your branded link subdomain, here mailing.example.com. In our case, we use Let’s Encrypt with Route53 DNS challenges, but you can use another tool like certbot. Then, copy the certificate fullchain.pem and private key privkey.pem to /etc/nginx/ssl/ .

Once the nginx code is created and the certificates are ready, you can restart nginx

sudo service nginx restart

Change the CNAME Record

The last step is to change the DNS record for your branded link.

1. Open the CNAME record that you created for mailing.example.com.

2. Change the CNAME record to point to sendgrid.mindee.com instead of sendgrid.net. Do not revalidate the DNS in Sendgrid.

3. You can check the configuration is working with http by opening any link in sent emails.

Contact Sendgrid

After your configuration, contact Sendgrid’s Support and ask to enable SSL for our custom domain.

That’s all. Hope you find this helpful!

Feature Image Copyright