fix utm params

Author: pierre-b

CHANGELOG.md

@@ -2,6 +2,10 @@
 
 All notable changes to this project will be documented in this file.
 
+## [30.3] - 2026-05-14
+
+- **Fix**: UTM parameters (`utm_source`, `utm_medium`, `utm_campaign`, `utm_content`, `utm_term`) were dropped from tracked links when click tracking was enabled — the encrypted `/r/` redirect token embedded the raw destination URL instead of the UTM-augmented one. The UTM parameters are now preserved in the redirect target.
+
 ## [30.2] - 2026-05-13
 
 - **Fix**: SES `4.4.7 Message expired` (retry-exhaustion) now suppresses on the first event, and any recipient that accumulates 5 consecutive soft bounces with no successful delivery in between is also suppressed; `MessageTooLarge`/`ContentRejected`/`AttachmentRejected` never count (#323).

config/config.go

@@ -15,7 +15,7 @@ import (
 	"github.com/spf13/viper"
 )
 
-const VERSION = "30.2"
+const VERSION = "30.3"
 
 type Config struct {
 	Server              ServerConfig

pkg/notifuse_mjml/template_compilation.go

@@ -172,61 +172,70 @@ func isNonTrackableURL(urlStr string) bool {
 	return false
 }
 
-func (t *TrackingSettings) GetTrackingURL(sourceURL string) string {
-	// Ignore if URL is empty, a placeholder, mailto:, tel:, or already tracked (basic check)
-	if sourceURL == "" || strings.Contains(sourceURL, "{{") || strings.Contains(sourceURL, "{%") || strings.HasPrefix(sourceURL, "mailto:") || strings.HasPrefix(sourceURL, "tel:") {
+// applyUTMParameters appends the configured UTM parameters to sourceURL and
+// returns the result. The URL is returned unchanged when it is empty, a Liquid
+// placeholder, a mailto:/tel: link, cannot be parsed, or already carries any
+// utm_* query parameter.
+func (t *TrackingSettings) applyUTMParameters(sourceURL string) string {
+	if sourceURL == "" || strings.Contains(sourceURL, "{{") || strings.Contains(sourceURL, "{%") ||
+		strings.HasPrefix(sourceURL, "mailto:") || strings.HasPrefix(sourceURL, "tel:") {
 		return sourceURL
 	}
 
-	// parse sourceURL to get the domain
 	parsedURL, err := url.Parse(sourceURL)
 	if err != nil {
 		return sourceURL
 	}
 
-	// Get existing query parameters
 	queryParams := parsedURL.Query()
 
-	// Check if URL already has UTM parameters - if yes, don't modify them
-	hasExistingUTM := false
+	// If the URL already has UTM parameters, leave them untouched
 	for key := range queryParams {
 		if strings.HasPrefix(strings.ToLower(key), "utm_") {
-			hasExistingUTM = true
-			break
+			return sourceURL
 		}
 	}
 
-	// Add UTM parameters to the URL if no existing UTM parameters
-	if !hasExistingUTM {
-		if t.UTMSource != "" {
-			queryParams.Add("utm_source", t.UTMSource)
-		}
-		if t.UTMMedium != "" {
-			queryParams.Add("utm_medium", t.UTMMedium)
-		}
-		if t.UTMCampaign != "" {
-			queryParams.Add("utm_campaign", t.UTMCampaign)
-		}
-		if t.UTMContent != "" {
-			queryParams.Add("utm_content", t.UTMContent)
-		}
-		if t.UTMTerm != "" {
-			queryParams.Add("utm_term", t.UTMTerm)
-		}
-		parsedURL.RawQuery = queryParams.Encode()
+	if t.UTMSource != "" {
+		queryParams.Add("utm_source", t.UTMSource)
+	}
+	if t.UTMMedium != "" {
+		queryParams.Add("utm_medium", t.UTMMedium)
+	}
+	if t.UTMCampaign != "" {
+		queryParams.Add("utm_campaign", t.UTMCampaign)
+	}
+	if t.UTMContent != "" {
+		queryParams.Add("utm_content", t.UTMContent)
 	}
+	if t.UTMTerm != "" {
+		queryParams.Add("utm_term", t.UTMTerm)
+	}
+	parsedURL.RawQuery = queryParams.Encode()
+
+	return parsedURL.String()
+}
+
+func (t *TrackingSettings) GetTrackingURL(sourceURL string) string {
+	// Ignore if URL is empty, a placeholder, mailto:, tel:, or already tracked (basic check)
+	if sourceURL == "" || strings.Contains(sourceURL, "{{") || strings.Contains(sourceURL, "{%") || strings.HasPrefix(sourceURL, "mailto:") || strings.HasPrefix(sourceURL, "tel:") {
+		return sourceURL
+	}
+
+	// Append UTM parameters to the destination URL
+	destinationURL := t.applyUTMParameters(sourceURL)
 
 	if !t.EnableTracking {
-		return parsedURL.String()
+		return destinationURL
 	}
 
-	// parse endpoint and add url to the query params
+	// parse endpoint and add the UTM-augmented destination URL to the query params
 	parsedEndpoint, err := url.Parse(t.Endpoint)
 	if err != nil {
 		return sourceURL
 	}
 	endpointParams := parsedEndpoint.Query()
-	endpointParams.Add("url", parsedURL.String()) // Use the URL with UTM parameters
+	endpointParams.Add("url", destinationURL)
 	parsedEndpoint.RawQuery = endpointParams.Encode()
 
 	return parsedEndpoint.String()
@@ -622,13 +631,16 @@ func TrackLinks(htmlString string, trackingSettings TrackingSettings) (updatedHT
 			return match // Return original link unchanged
 		}
 
-		// Apply tracking to the URL
-		trackedURL := trackingSettings.GetTrackingURL(originalURL)
+		// Append UTM parameters to the destination URL
+		destinationURL := trackingSettings.applyUTMParameters(originalURL)
+		trackedURL := destinationURL
 
 		if trackingSettings.EnableTracking {
-			// Use current Unix timestamp (seconds) for bot detection
+			// Use current Unix timestamp (seconds) for bot detection.
+			// The UTM-augmented destination URL is what gets encrypted into the
+			// token, so the redirect target preserves the UTM parameters.
 			sentTimestamp := time.Now().Unix()
-			trackedURL = GenerateEmailRedirectionEndpoint(trackingSettings.WorkspaceID, trackingSettings.MessageID, trackingSettings.Endpoint, originalURL, sentTimestamp)
+			trackedURL = GenerateEmailRedirectionEndpoint(trackingSettings.WorkspaceID, trackingSettings.MessageID, trackingSettings.Endpoint, destinationURL, sentTimestamp)
 		}
 
 		// Return the updated tag

pkg/notifuse_mjml/template_compilation_test.go

@@ -2,9 +2,11 @@ package notifuse_mjml
 
 import (
 	"encoding/json"
+	"regexp"
 	"strings"
 	"testing"
 
+	"github.com/Notifuse/notifuse/pkg/crypto"
 	"github.com/stretchr/testify/assert"
 )
 
@@ -296,6 +298,62 @@ func TestTrackLinksInvalidHTML(t *testing.T) {
 	}
 }
 
+// TestTrackLinks_PreservesUTMInEncryptedToken verifies that when click tracking
+// is enabled, the UTM parameters are NOT dropped: they must be appended to the
+// destination URL that gets encrypted into the /r/{token} redirect link.
+func TestTrackLinks_PreservesUTMInEncryptedToken(t *testing.T) {
+	trackingSettings := TrackingSettings{
+		EnableTracking: true,
+		Endpoint:       "https://track.example.com",
+		UTMSource:      "newsletter",
+		UTMMedium:      "email",
+		UTMCampaign:    "spring-sale",
+		UTMContent:     "hero-button",
+		UTMTerm:        "running-shoes",
+		WorkspaceID:    "ws-1",
+		MessageID:      "msg-1",
+	}
+
+	htmlInput := `<a href="https://shop.example.com/product?ref=email">Buy Now</a>`
+
+	result, err := TrackLinks(htmlInput, trackingSettings)
+	if err != nil {
+		t.Fatalf("TrackLinks failed: %v", err)
+	}
+
+	// Extract the encrypted /r/{token} link that TrackLinks generated
+	tokenRegex := regexp.MustCompile(`href="https://track\.example\.com/r/([^"]+)"`)
+	m := tokenRegex.FindStringSubmatch(result)
+	if m == nil {
+		t.Fatalf("expected a /r/{token} tracking link, got: %s", result)
+	}
+
+	// Decrypt the token: format is "messageID\nworkspaceID\ntimestamp\ndestinationURL"
+	plaintext, err := crypto.DecryptTrackingToken(m[1])
+	if err != nil {
+		t.Fatalf("failed to decrypt tracking token: %v", err)
+	}
+	parts := strings.Split(plaintext, "\n")
+	if len(parts) != 4 {
+		t.Fatalf("expected 4 token parts, got %d: %q", len(parts), plaintext)
+	}
+	destinationURL := parts[3]
+
+	// The destination URL embedded in the token must carry every UTM parameter
+	for _, want := range []string{
+		"utm_source=newsletter",
+		"utm_medium=email",
+		"utm_campaign=spring-sale",
+		"utm_content=hero-button",
+		"utm_term=running-shoes",
+		"ref=email", // pre-existing query params must be preserved too
+	} {
+		if !strings.Contains(destinationURL, want) {
+			t.Errorf("expected destination URL %q to contain %q", destinationURL, want)
+		}
+	}
+}
+
 func TestGetTrackingURL(t *testing.T) {
 	trackingSettings := TrackingSettings{
 		EnableTracking: true,

tests/integration/email_handler_test.go

@@ -7,12 +7,14 @@ import (
 	"io"
 	"net/http"
 	"net/url"
+	"regexp"
 	"strings"
 	"testing"
 	"time"
 
 	"github.com/Notifuse/notifuse/internal/domain"
 	"github.com/Notifuse/notifuse/pkg/crypto"
+	"github.com/Notifuse/notifuse/pkg/notifuse_mjml"
 	"github.com/Notifuse/notifuse/tests/testutil"
 	"github.com/stretchr/testify/assert"
 	"github.com/stretchr/testify/require"
@@ -944,6 +946,80 @@ func TestEmailHandler_EncryptedTracking(t *testing.T) {
 	})
 }
 
+// TestEmailHandler_TrackedLinkPreservesUTM exercises the real pipeline end to
+// end: it compiles an email template with click tracking enabled and UTM
+// parameters configured (exactly as the broadcast message sender does), then
+// follows the generated /r/{token} link against the running server and asserts
+// that the final redirect destination still carries every UTM parameter.
+func TestEmailHandler_TrackedLinkPreservesUTM(t *testing.T) {
+	testutil.SkipIfShort(t)
+	testutil.SetupTestEnvironment()
+	defer testutil.CleanupTestEnvironment()
+
+	suite := testutil.NewIntegrationTestSuite(t, appFactory)
+	defer func() { suite.Cleanup() }()
+
+	baseURL := suite.ServerManager.GetURL()
+
+	mjmlSource := `<mjml><mj-body><mj-section><mj-column>` +
+		`<mj-button href="https://shop.example.com/product?ref=email">Buy Now</mj-button>` +
+		`</mj-column></mj-section></mj-body></mjml>`
+
+	compileResp, err := notifuse_mjml.CompileTemplate(notifuse_mjml.CompileTemplateRequest{
+		WorkspaceID: "ws-utm",
+		MessageID:   "msg-utm",
+		MjmlSource:  &mjmlSource,
+		TrackingSettings: notifuse_mjml.TrackingSettings{
+			EnableTracking: true,
+			Endpoint:       baseURL,
+			UTMSource:      "newsletter",
+			UTMMedium:      "email",
+			UTMCampaign:    "spring-sale",
+			UTMContent:     "hero-button",
+			UTMTerm:        "running-shoes",
+			WorkspaceID:    "ws-utm",
+			MessageID:      "msg-utm",
+		},
+	})
+	require.NoError(t, err)
+	require.NotNil(t, compileResp)
+	require.True(t, compileResp.Success)
+	require.NotNil(t, compileResp.HTML)
+
+	// Extract the encrypted /r/{token} tracking link the pipeline generated
+	linkRegex := regexp.MustCompile(`href="(` + regexp.QuoteMeta(baseURL) + `/r/[^"]+)"`)
+	match := linkRegex.FindStringSubmatch(*compileResp.HTML)
+	require.NotNil(t, match, "expected a tracked /r/ link in compiled HTML: %s", *compileResp.HTML)
+	trackedLink := match[1]
+
+	client := &http.Client{
+		CheckRedirect: func(req *http.Request, via []*http.Request) error {
+			return http.ErrUseLastResponse
+		},
+	}
+	req, err := http.NewRequest(http.MethodGet, trackedLink, nil)
+	require.NoError(t, err)
+	req.Header.Set("User-Agent", "Mozilla/5.0 Chrome/120.0.0.0")
+
+	resp, err := client.Do(req)
+	require.NoError(t, err)
+	defer func() { _ = resp.Body.Close() }()
+
+	require.Equal(t, http.StatusSeeOther, resp.StatusCode)
+
+	// The final redirect destination must carry every configured UTM parameter
+	location := resp.Header.Get("Location")
+	parsedLocation, err := url.Parse(location)
+	require.NoError(t, err)
+	q := parsedLocation.Query()
+	assert.Equal(t, "newsletter", q.Get("utm_source"))
+	assert.Equal(t, "email", q.Get("utm_medium"))
+	assert.Equal(t, "spring-sale", q.Get("utm_campaign"))
+	assert.Equal(t, "hero-button", q.Get("utm_content"))
+	assert.Equal(t, "running-shoes", q.Get("utm_term"))
+	assert.Equal(t, "email", q.Get("ref"), "pre-existing query params must be preserved")
+}
+
 func TestEmailHandler_ConcurrentRequests(t *testing.T) {
 	testutil.SkipIfShort(t)
 	testutil.SetupTestEnvironment()