Token-Based Tracking Links

v8.7.4

Starting with v8.7.4, Interspire Email Marketer can replace the traditional plaintext tracking parameters in outbound emails with encrypted tokens. Instead of URLs that expose subscriber, list, and campaign IDs in the query string, emails contain a single opaque ?t= parameter that encodes all the same information securely.

Before (traditional format):

https://example.com/link.php?M=12345&L=5&N=789&l=42

After (token-based format):

https://example.com/link.php?t=dGhpcyBpcyBhIHNhbXBsZS4uLg...

This applies to all outbound tracking URLs: open tracking pixels, link clicks, and unsubscribe URLs.

Why Token-Based Links?

Traditional tracking URLs expose internal identifiers (subscriber ID, list ID, campaign ID) directly in the URL. This means:

Internal identifiers are visible in URLs, browser history, and server logs.
URL parameters can be guessed or modified.

Token-based links address this by encrypting all parameters into a single authenticated token. The token is:

Encrypted — internal IDs are not visible in the URL.
Tamper-proof — the authenticated encryption (AES-256-GCM) detects any modification.
Time-limited — tokens expire after a configurable period (default 90 days), so old links don’t work indefinitely.

Enabling Token-Based Links

Token-based links activate automatically when a tracking key is configured in ~/admin/includes/config.php:

define('SENDSTUDIO_TRACKING_KEY', 'your-base64-encoded-key-here');

Generate a key by running:

php tools/generate-keys.php

This outputs both SENDSTUDIO_ENC_KEY (for credential encryption) and SENDSTUDIO_TRACKING_KEY (for tracking URL encryption). You can use either or both independently.

Once the tracking key is in place, all newly sent emails use token-based URLs. No other configuration is needed.

What Changes for Recipients

Nothing visible. Links in emails still work as expected — clicks are tracked, opens are recorded, and unsubscribe links function normally. The only difference is that the URL format changes from multiple query parameters to a single ?t= token.

What Changes for Administrators

Tracking URLs in sent emails use the ?t= format instead of plaintext parameters.
Previously sent emails continue to work. Legacy URLs (with plaintext parameters) are accepted by default during a transition period. This is controlled by the ALLOW_LEGACY_TRACKING_URLS setting.
The tracking key must not be changed or lost. Changing SENDSTUDIO_TRACKING_KEY invalidates all tracking URLs in previously sent emails.

Configuration Options

All settings go in ~/admin/includes/config.php:

Setting	Purpose	Default
`SENDSTUDIO_TRACKING_KEY`	Enables token-based links when set	Not set (traditional URLs)
`TRACKING_URL_EXPIRATION`	How long tokens remain valid, in days	`90`
`ALLOW_LEGACY_TRACKING_URLS`	Accept old-format plaintext URLs alongside tokens	`true`

Recommended Rollout

Add the tracking key to config.php. All new sends immediately use token-based URLs.
Keep ALLOW_LEGACY_TRACKING_URLS enabled (or leave it unset — it defaults to accepting legacy URLs when the key is first added). This ensures links in emails sent before the key was added continue to work.
After 90 days (or your configured expiration period), set ALLOW_LEGACY_TRACKING_URLS to false. Legacy URLs do not expire on their own — this is a manual cutoff. The 90-day window is a guideline; by that point most pre-token-based emails are old enough that disabling legacy URLs won’t affect many recipients.

Unsubscribe Handling

Token-based links also affect how unsubscribe works:

List-Unsubscribe header: The HTTPS unsubscribe URL in the email header uses a ?t= token.
Mailto fallback (if configured): The encrypted token is placed in the email body rather than the local-part of the address, avoiding the 64-character local-part limit.
One-click unsubscribe (RFC 8058): Works with both token-based and traditional URLs. The POST response codes reflect actual processing results (204 for success, 400 for invalid payload, 409 for processing errors).

Key Safety

The key in config.php is safe — PHP files are executed by the server and never served as plaintext to browsers.

Troubleshooting

Symptom	Cause	Fix
URLs still show `?M=...` format	`SENDSTUDIO_TRACKING_KEY` not defined in config.php	Add the key and resend
”Tracking token expired” in logs	Recipient clicked a link older than the expiration period	Expected behaviour; increase `TRACKING_URL_EXPIRATION` if needed
Old email links return errors	`ALLOW_LEGACY_TRACKING_URLS` set to `false` too early	Set it back to `true` until pre-token-based emails are no longer relevant
Token decryption failures in logs	Key was changed or corrupted	Restore the original key from backup