Troubleshoot SSL click tracking

Use this page to identify common SSL click tracking issues. The following guidance is generic because every CDN is unique. For CDN configuration, certificates, or proxy issues, contact your CDN’s support team, as these configurations take place outside of Braze.

Start here: Match your symptom

Standard investigation path

1. Confirm your click tracking subdomain points to your content delivery network (CDN)—not directly to your email service provider (SendGrid, SparkPost, or Amazon SES). Ask your IT or web team to verify your domain settings match your Braze setup. For Braze requirements, see Acquire an SSL certificate.
2. Confirm your SSL certificate is active for the tracking domain. Ask your IT or web team to confirm the certificate is current and covers your click tracking subdomain. For setup steps and CDN-specific guides, see Acquire an SSL certificate and Additional resources.
3. Send a test email using the click tracking troubleshooting template. Compare tracked versus untracked URLs.
4. If tracked links fail with 403, review CDN and WAF rules (user agents, query strings, redirect patterns).
5. If setup is complete but links remain HTTP, contact your Braze customer success manager to confirm Braze enabled SSL.
6. For persistent issues, coordinate with your CDN or IT team and contact Braze Support with error codes and any details from your CDN or domain provider.

Key concepts

• Click tracking domain (CTD): The branded subdomain Braze uses to wrap links for click tracking (for example, clicks.mail.yourbrand.com).
• Tracked URL: Wraps the original HTTPS link in your tracking domain. When a user clicks it, the tracking domain resolves the request and redirects to the final destination. A CDN allows you to track secure (HTTPS) URLs. Without it, users may encounter a “connection is not secure” privacy error.
• Untracked URL: Maintains the original URL intact, bypassing the CDN to serve as a control environment.
• Phase 1 and Phase 2 routing: Phase 1 points your click tracking domain CNAME directly to your email service provider (ESP) for initial HTTP verification. Phase 2 points the CNAME to your CDN or web application firewall (WAF), which terminates SSL and proxies requests to the ESP with the required headers. For ESP-specific CNAME destinations, see ESP Phase 1 and Phase 2 routing.

Click tracking domains and DNS phases

SSL click tracking requires a two-phase DNS setup because Braze does not provision or renew external security certificates on your behalf.

1. Phase 1 (initial setup): Your click tracking domain CNAME points directly to your ESP endpoint for unencrypted HTTP verification.
2. Phase 2 (SSL deployment): You update the CNAME to your CDN or WAF edge, which holds your custom SSL certificate and proxies requests to the ESP with the required headers. The ESP logs the click and redirects the recipient to the final destination.

important

Braze enables SSL click tracking only after Phase 1 verification is complete. If SSL is enabled but your DNS still points to the ESP (Phase 1), recipients can see SSL name mismatch errors.

ESP Phase 1 and Phase 2 routing

When troubleshooting link tracking errors, check whether your DNS record points to the unencrypted ESP network (Phase 1) or your CDN (Phase 2).

For CDN setup steps and partner documentation, refer to SSL at Braze.

SSL name mismatch errors

An SSL name mismatch is an identity authentication failure during the TLS handshake. It occurs when a browser establishes an encrypted connection but the domain in the address bar does not match any entry in the certificate’s Common Name (CN) or Subject Alternative Names (SAN) fields.

DNS still points to the ESP (Phase 1)

If you instruct Braze to enable SSL click tracking but leave your DNS CNAME pointing directly to the ESP (for example, SendGrid’s sendgrid.net), the recipient’s browser opens your click tracking domain and hits the ESP’s infrastructure. The ESP has no record of your custom certificate and serves its own fallback certificate (for example, *.sendgrid.net). The name mismatch fails the connection and returns a private connection warning.

Certificate does not cover the tracking subdomain (Phase 2)

If your DNS points to your CDN (Cloudflare, CloudFront, and so on) but your security team applied a certificate that only covers primary web assets (for example, yourbrand.com and www.yourbrand.com), the specific click tracking subdomain (for example, clicks.mail.yourbrand.com) is not included. The CDN serves a certificate that does not match the tracking domain, and browsers show a privacy error.

Triage workflow

Step 1: Run an authoritative CNAME lookup

Open your terminal and check the raw DNS routing for your click tracking domain:

1
dig CNAME clicks.mail.yourbrand.com

In the ANSWER SECTION, review where the CNAME resolves:

Step 2: Validate the TLS certificate

Force a live TLS validation against your click tracking domain to see exactly which certificate browsers receive. Enter your click tracking domain into an external SSL checker, such as SSL Shopper’s SSL Checker (replace clicks.mail.yourbrand.com with your domain).

Confirm the following:

• The certificate is valid and not expired
• Your click tracking domain appears in the Common Name or Subject Alternative Names
• The certificate chain is complete, with no untrusted intermediate certificate warnings

tip

For a more detailed TLS report, you can also use Qualys SSL Labs SSL Server Test.

Step 3: Review CDN configuration issues

If live email links break during setup, confirm that DNS was not pointed to your CDN before configuration was complete. This can appear as a wrong link or connection error. Contact your CDN provider and review their documentation to troubleshoot proxy and origin settings. Coordinate with the team that manages your SSL and CDN configuration for further assistance.

Low email open rates

Symptom: Email open rates dropped suddenly after SSL or CDN changes.

If you’re suddenly experiencing low email open rates, confirm that the SSL certificate is up-to-date. If it’s expired, you must renew that SSL certificate with your CDN or certificate provider.

HTTP 403 on redirect links

Symptom: Tracked email links return “403 Forbidden”.

If tracked redirect links return 403 Forbidden, the failure often occurs at your content delivery network (CDN) or web application firewall (WAF)—for example, rules on AWS WAF or Amazon CloudFront that block certain user agents, query strings, or redirect patterns. Review blocked-request logs and metrics with your CDN or cloud provider. For AWS, see Troubleshooting issues with CloudFront.

To see whether the problem is specific to click tracking, turn off click tracking for one test link (see Turning off click-tracking on a link-to-link basis). If the destination URL loads when click tracking is off but returns 403 when tracking is on, focus on configuration for your click tracking domain, CDN, and WAF. If your CNAME still points to the ESP while SSL is enabled, you may see an SSL name mismatch error instead—start with the triage workflow.

Domain registry issues

Symptom: DNS or CNAME for your tracking subdomain points to your ESP instead of your CDN.

Run a dig command to confirm you point link tracking at the CDN. In your terminal run dig CNAME link_tracking_subdomain. Under ANSWER SECTION, it lists where your CNAME points. If it points to the email service provider (SendGrid, SparkPost, or Amazon SES) and not your CDN, reconfigure your domain registry to point to your CDN.

CDN issues

Symptom: Users see “connection isn’t private” errors, or links break during CDN setup.

If live email links break during setup, you likely pointed DNS toward your CDN before proper configuration. This can appear as a “wrong link” error. Contact your CDN provider and review their documentation to troubleshoot configuration.

If you see an error message that your connection isn’t private, this can indicate that your SSL or CDN isn’t configured correctly. Run a dig command in your terminal (for example, dig CNAME your_link_tracking_subdomain). In the ANSWER SECTION, if the result points to your ESP instead of your CDN, the issue is a misconfiguration. For Braze SSL click tracking to work, the CNAME should point to your CDN. Coordinate with the team that manages your SSL and CDN configuration for further assistance.

SSL enablement status

Symptom: SSL setup is complete but tracked links still appear as HTTP.

If you complete SSL setup and links still appear as HTTP, contact your Braze customer success manager to confirm Braze enabled SSL. Braze enables SSL only after all setup steps are complete.

Amazon SES

If you’re using Amazon SES as your email service provider, the following configuration issues can prevent Braze from enabling SSL or cause errors during setup:

• Region mismatch: Confirm your CDN origin points to the AWS tracking domain for your Braze cluster. US clusters use r.us-east-1.awstrack.me. EU clusters use r.eu-central-1.awstrack.me. Using the wrong region can block SSL enablement.
• Host header: Amazon SES requires your CDN to forward the correct host header. Enable the X-Forwarded-Host header on your click tracking domain. For Phase 1 and Phase 2 routing requirements, refer to ESP Phase 1 and Phase 2 routing.
• Proxy configuration: A proxy or CDN setup that overrides or conflicts with the host header can cause SSL enablement to fail. Review proxy settings with your CDN provider to confirm they don’t interfere with host header forwarding.
• Route 53 alias record: If you use Route 53 to manage DNS for your domain, create an alias record in Route 53 that points to your CDN distribution (for example, d111111abcdef8.cloudfront.net). Using a standard CNAME instead of an alias record can return HTTP 400 errors.
• Header forwarding disabled: If SSL enablement still fails after you configure X-Forwarded-Host, try disabling header forwarding on your CDN or proxy. Some setups resolve the issue when forwarding is turned off entirely. Work with your IT team or CDN provider to test this configuration.

Click tracking issues

Symptom: Tracked email links fail but untracked links work, or users see certificate or DNS errors after clicking.

Common redirection issues typically result from an improper configuration between the CDN hosting the tracking domain and its associated SSL certificates or DNS CNAME records. These misconfigurations often cause users to receive a “connection is not secure” privacy error or a 404 failure after clicking a tracked email link.

After completing the triage workflow, use the following template to test the CDN configuration of your tracking domain, which is the mechanism supporting analytics for links within your emails.

1. Copy and paste the following template into a Braze HTML email campaign.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
<!DOCTYPE html>
<html lang="en" xmlns:v="urn:schemas-microsoft-com:vml" xmlns:o="urn:schemas-microsoft-com:office:office">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <meta name="color-scheme" content="light dark">
    <meta name="supported-color-schemes" content="light dark">
    <title>Click Tracking Test</title>
    <style>
        /* Base Dark Mode (Default) */
        body { 
            margin: 0; 
            padding: 0; 
            background-color: #2b0562; 
            font-family: 'Helvetica Neue', Arial, sans-serif; 
            color: #ffd1e9; 
        }
        
        .email-container { 
            width: 100%; 
            max-width: 600px; 
            margin: 40px auto; 
            background-color: rgba(255, 255, 255, 0.05); 
            border: 1px solid #F3697F; 
            border-radius: 16px; 
            overflow: hidden; 
        }
        
        .header { 
            background: linear-gradient(135deg, #E83F21 0%, #F3697F 100%); 
            padding: 40px 20px 50px 20px; 
            text-align: center; 
        }

        .logo {
            display: block;
            margin: 0 auto 25px auto;
            border: 0;
            outline: none;
            text-decoration: none;
        }
        
        .header h1 { 
            color: #ffffff; 
            margin: 0; 
            font-size: 26px; 
            font-weight: 800; 
            letter-spacing: -0.5px; 
        }
        
        .content { 
            padding: 40px 40px 20px 40px; 
            line-height: 1.8; 
            font-size: 15px; 
        }

        .troubleshoot {
            margin: 0 40px 40px 40px;
            padding: 25px;
            background-color: rgba(253, 167, 216, 0.1);
            border-radius: 12px;
            font-size: 14px;
            border: 1px dashed #F3697F;
        }
        
        .troubleshoot h2 {
            margin-top: 0;
            font-size: 18px;
            color: #ffffff;
        }

        .btn-section { 
            padding: 0 40px 40px 40px; 
            text-align: center; 
        }
        
        .btn { 
            display: inline-block; 
            padding: 16px 32px; 
            border-radius: 12px; 
            font-weight: 700; 
            text-decoration: none; 
            margin: 10px;
            font-size: 14px;
        }
        
        .btn-tracked { 
            background-color: #F3697F; 
            color: #ffffff; 
        }
        
        .btn-untracked { 
            border: 2px solid #FDA7D8; 
            color: #FDA7D8; 
            background-color: transparent;
        }

        .footer { 
            text-align: center; 
            font-size: 12px; 
            color: #FDA7D8; 
            padding-bottom: 40px; 
            opacity: 0.6; 
        }

        /* Light Mode Overrides */
        @media (prefers-color-scheme: light) {
            body { background-color: #F7FCFF !important; color: #2b0562 !important; }
            .email-container { background-color: #ffffff !important; border: 1px solid #FDA7D8 !important; box-shadow: 0 4px 20px rgba(43, 5, 98, 0.1); }
            .content { color: #2b0562 !important; }
            .troubleshoot { background-color: #F7FCFF !important; border-color: #F3697F !important; color: #2b0562 !important; }
            .troubleshoot h2 { color: #E83F21 !important; }
            .btn-untracked { color: #F3697F !important; border-color: #F3697F !important; }
            .footer { color: #2b0562 !important; }
            strong { color: #E83F21 !important; }
        }

        /* Mobile Optimization */
        @media only screen and (max-width: 480px) {
            .btn { display: block !important; margin: 10px 0 !important; width: auto !important; }
            .content, .troubleshoot { padding: 25px !important; }
        }
    </style>
</head>
{%- capture url -%}https://example.com{%- endcapture -%}
<body>
    <center>
        <table class="email-container" role="presentation" width="600" border="0" cellpadding="0" cellspacing="0">
            <tr>
                <td class="header">
                    <img src="https://cdn-staging.braze.com/appboy/communication/assets/image_assets/images/60aecba96a93150c749b4d57/original.png?1622068137" 
                         width="150" 
                         alt="Logo" 
                         class="logo">
                    <h1>Testing Click Tracking Functionality</h1>
                </td>
            </tr>
            <tr>
                <td class="content">
                    <p>
                        Use this template to test the <strong>CDN configuration</strong> of your tracking domain—the mechanism supporting analytics for links within your emails.
                    </p>
                    <p>
                        A <strong>Tracked URL</strong> wraps the original HTTPS link in your tracking domain. When a user clicks it, the tracking domain resolves the request and redirects to the final destination. A CDN allows you to track secure (HTTPS) URLs; without it, users may encounter a "connection is not secure" privacy error. An <strong>Untracked URL</strong> maintains the original URL intact, bypassing the CDN to serve as a control environment.
                    </p>
                    <p>
                        Common redirection issues typically result from an improper configuration between the CDN hosting the tracking domain and the <strong>associated SSL certificate or DNS CNAME records.</strong>
                    </p>
                    <p>
                        <i style="font-size: 13px;">This template uses "example.com" as the destination URL. To test your own domain, replace the URL in the <strong>capture</strong> tag located on line 125.</i>
                    </p>
                </td>
            </tr>
            <tr>
                <td class="btn-section">
                    <a href="{{url}}" class="btn btn-tracked">Tracked URL</a>
                    
                    <a href="{{url}}" 
                       class="btn btn-untracked"
                       clicktracking="off" 
                       data-msys-clicktrack="0" 
                       ses:no-track="true">
                       Untracked URL
                    </a>
                </td>
            </tr>
            <tr>
                <td>
                    <div class="troubleshoot">
                        <h2>Troubleshooting the Test</h2>
                        <ul>
                            <li><strong>Tracked URL Fails / Untracked Works:</strong> This indicates a CDN or SSL certificate issue. Verify that your SSL certificate is valid and correctly bound to your tracking domain.</li>
                            <li><strong>Privacy Error (HTTPS):</strong> Ensure your CDN is configured to handle port 443 traffic and that the certificate matches your tracking CNAME.</li>
                            <li><strong>Both URLs Fail:</strong> Check the destination URL or your internal network firewall settings.</li>
                            <li>For more information, visit: <a href="{{ site.homeurl }}{{ site.baseurl }}/user_guide/channels/email/email_setup/ssl">SSL at Braze</a></li>
                        </ul>
                    </div>
                </td>
            </tr>
        </table>
        <div class="footer">
            Braze :: 63 Madison Avenue, 13th Floor :: New York, NY 10016
        </div>
    </center>
</body>
</html>

2. Configure your URL. Replace the URL in the capture tag near the top of the template body (where https://example.com is set). For example, replace https://example.com with https://braze.com/docs.
3. Send a test email to yourself and select both buttons.
4. Verify that the expected behavior and success criteria are as described in the template.

If your untracked URL works but your tracked URL fails, you may have a configuration gap. Refer to the documentation for your specific ESP and CDN provider. For detailed requirements on certificate provisioning, see SSL at Braze.

Use the following table to diagnose common errors when testing click tracking.