Token-Based Tracking Links

v8.7.4

Starting with v8.7.4, Interspire Email Marketer can encode the tracking parameters in outbound emails as encrypted tokens. Instead of carrying separate parameter values, emails contain a single opaque ?t= parameter that encodes all the same information securely.

Before (traditional format):

https://example.com/link.php?<tracking parameters>

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?

Tracking URLs carry the parameters they need to identify a click or open. Token-based links take a more privacy-conscious approach by bundling those parameters into a single authenticated token rather than passing them as plain URL values. The token is:

Encrypted — the token’s contents are not readable in the URL.
Tamper-proof — the authenticated encryption (AES-256) 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 separate query parameters.
Previously sent emails continue to work if you allow it. Legacy URLs (in the traditional format) can be accepted during a transition period so that links in older emails keep functioning, controlled by the ALLOW_LEGACY_TRACKING_URLS setting (see Recommended Rollout).
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 traditional-format URLs alongside tokens	Not set — see note

Once a tracking key is configured, traditional-format URLs are accepted only if ALLOW_LEGACY_TRACKING_URLS is explicitly defined as true; if the constant is not defined, legacy URLs are rejected. (Before a tracking key is configured, legacy URLs are always accepted, since they are the only format available.) The bundled config_tracking_secret.example.php template defines ALLOW_LEGACY_TRACKING_URLS as true, so installations that use that template accept legacy URLs during the transition until the value is changed.

Recommended Rollout

Add the tracking key to config.php. All new sends immediately use token-based URLs.
Set ALLOW_LEGACY_TRACKING_URLS to true while emails sent before the key was added are still in circulation, so their links keep working. (If you configure tracking via the config_tracking_secret.example.php template, this is already set for you.)
After the transition period (by default 90 days, matching the token expiration), set ALLOW_LEGACY_TRACKING_URLS to false to stop accepting traditional-format URLs. This is a manual step — legacy acceptance does not end on its own — and completing it is what fully retires the older URL format.

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