Overview / Tracking and Unsubscribe

Tracking and Unsubscribe

Deploy the hosted PHP scripts Virtual Mailer uses for open tracking and unsubscribe handling, then synchronize the resulting activity back into the application.

Purpose

What This Feature Does

Virtual Mailer supports self-hosted open tracking and self-hosted unsubscribe processing. Instead of relying on a third-party email marketing platform, the application can upload PHP scripts to your web hosting account, record activity there, and later synchronize the results into the local database.

Open Tracking

Records message-open events through a tracking pixel endpoint that writes activity to a protected log.

Unsubscribe

Processes unsubscribe requests through a hosted PHP endpoint and records them for later synchronization.

Sync Back

Imports open and unsubscribe records into Virtual Mailer so reports, suppression behavior, and message history stay aligned.

This is an infrastructure feature. It works best when your web hosting path, public URL, and file-transfer settings are validated before you use it in production campaigns.
Files

What Gets Deployed

File Role Notes
pixel_tracking.php Receives tracking-pixel requests and records opens. Used for open tracking when the campaign and license tier support it.
unsubscribe.php Receives unsubscribe requests and writes them to the unsubscribe log. Required for hosted unsubscribe processing.

These files are deployed from the Tracking & POP... dialog inside the Mail Account editor.

Requirements

Before You Start

  • A working Mail Account with valid transfer credentials.
  • A web host that can run PHP scripts.
  • A server folder that maps cleanly to a public website URL.
  • Permission to upload files to that folder.
  • A campaign or test message that will use the account after deployment.
The public URL and the upload folder must refer to the same hosted location. If those two do not match, deployment may succeed while tracking still fails in production.
Readiness Rule

What Makes Tracking Sync Ready

Virtual Mailer now treats tracking synchronization as ready only when both the public URL and the transfer path are configured correctly.

  • Tracking URL: a valid public folder URL must be saved on the Mail Account.
  • Transfer configuration: the account must also have a transfer host, user name, and a valid FTP, FTPS, or SFTP protocol.
  • Staged save is allowed: the Mail Account editor can save the Tracking URL before transfer settings are complete, but sync will remain unavailable until both parts are configured.
Workflow

Recommended Deployment Sequence

  1. Open Mail Accounts and edit the sending profile you want to use.
  2. Click Tracking & POP....
  3. Enter the transfer host, port, username, password, protocol, upload folder, and public folder URL.
  4. Confirm the tracking script filename if your edition allows customization.
  5. Click Deploy Tracking Script.
  6. Verify that both PHP scripts exist on the server in the expected folder.
  7. Send a small live test campaign that includes tracking and unsubscribe behavior.
  8. Run synchronization and confirm the local application records the activity correctly.
Manual Option

Manual Upload Is Also Possible

The built-in deploy button is the preferred workflow, but you can also upload the tracking files manually with your own FTP, FTPS, or SFTP client if needed.

  • Upload both pixel_tracking.php and unsubscribe.php into the same hosted folder.
  • After manual upload, Virtual Mailer still needs the correct folder URL and transfer settings for later synchronization.
  • When possible, keep the standard filenames unless your release and license policy explicitly support custom tracking-script naming.
Transfer Setup

How the Mail Account Settings Relate to Tracking

Setting Why It Matters Guidance
FTP Host Defines the server Virtual Mailer connects to for upload and later log retrieval. Use the file-transfer hostname, not the public website URL.
Port Determines the transfer port used for the selected protocol. Typical values are 21 for FTP and 22 for SFTP.
User / Password Authenticates the transfer session. Use a dedicated account if possible and limit it to the intended deployment area.
Protocol Determines how files are transferred. FTPS and SFTP (SSH) are the secure choices. FTP remains a legacy compatibility option.
FTP Upload Folder Server-side destination for the PHP files and log files. Examples include ./tracking, /public_html/tracking, or the host's mapped directory format.
URL to FTP Folder The public web location corresponding to the upload folder. Enter the folder URL only, such as https://yourdomain.com/tracking/.
Open Logging Script Tracking script filename used by the application. Must be filename-only and end in .php. Do not include slashes or a full URL.
Paths and URLs

Understanding the Folder Mapping

The most common source of failure is a mismatch between the upload path and the public URL. Both must represent the same physical location on the web server.

Correct Example

  • Upload Folder: ./tracking
  • Public URL: https://yourdomain.com/tracking/
  • Result: the uploaded scripts are reachable from that public folder.

Incorrect Example

  • Upload Folder: ./tracking
  • Public URL: https://yourdomain.com/assets/
  • Result: deployment may upload the files, but campaigns will point recipients to the wrong location.
Do not enter a direct file URL in the folder URL field. Use the folder only, and let Virtual Mailer append the script filename internally.
Validation

How to Verify Deployment

  1. After deployment, inspect the remote folder and confirm both PHP files exist.
  2. Open the tracking folder in a browser and confirm you are using the expected public path.
  3. Request a direct tracking test URL, such as the tracking script plus a test identifier, and confirm the host responds as expected.
  4. Confirm that raw log files are not publicly downloadable.
  5. Send a real test message and verify that opening the message later creates activity during synchronization.
A simple direct test is the tracking endpoint with a test ID. A blank or pixel-like response is expected. The more important check is whether the server records the event and sync later imports it correctly.
The hosted log files are intended to be protected. The application now relies on FTP or SFTP for synchronization rather than a legacy HTTP fallback.
Open Tracking

How Open Tracking Works

When open tracking is enabled and properly deployed, Virtual Mailer inserts a tracking pixel URL into the outgoing message. When the recipient's mail client loads remote images, the hosted script records the event.

  • Open tracking depends on the recipient allowing remote image loading.
  • Some privacy tools and mail clients block or proxy tracking pixels.
  • Open metrics are directional, not absolute; use them with caution.
  • Synchronization updates message history and tracking log records in the local application database.
A low open rate does not always mean low engagement. Some mail clients intentionally suppress or proxy image requests, which can reduce observable opens.
Unsubscribe

How Unsubscribes Work

The unsubscribe script provides the hosted endpoint used when a recipient clicks an unsubscribe link generated by the application. The script records the request, and Virtual Mailer later imports that activity during synchronization.

  • Deploying the unsubscribe script alone does not guarantee every message contains an unsubscribe link.
  • The campaign must be configured to include unsubscribe behavior.
  • Unsubscribe requests should be synchronized promptly to keep suppression accurate.
  • List-unsubscribe headers and one-click flows should remain part of your broader compliance and deliverability strategy where supported.
Treat unsubscribe handling as compliance-critical, not optional. Test it before public campaigns and verify that the contact is actually suppressed after sync.
Behavior Rule

Footer Links vs One-Click Unsubscribe

There are two different unsubscribe experiences to understand:

  • Header-based one-click unsubscribe: when supported by mailbox providers, the unsubscribe must be processed immediately with no extra confirmation step.
  • Footer unsubscribe link: you may show a confirmation or informational page after the unsubscribe has already been processed, but the recipient should not be required to take a second action to opt out.
Do not build an unsubscribe flow that requires login, payment, or extra identity questions before the unsubscribe is honored.
Server Readiness

Permissions and Hosting Expectations

  • The hosting environment must support PHP.
  • The deployment folder must allow the scripts to create and update their log files.
  • If the folder is not writable, deployment may succeed while tracking or unsubscribe logging still fails at runtime.
  • Protect raw log files from public download whenever possible.
Licensing

Edition Considerations

Feature availability can vary by license tier.

  • Basic edition supports unsubscribe deployment but has limitations around open tracking customization.
  • Professional and Agency editions provide broader open tracking capability.
  • If a field is disabled or fixed to a default script name, that is usually controlled by the active license policy rather than a deployment error.
Synchronization

How Sync Works After Deployment

Virtual Mailer later connects back to the configured transfer server to read the hosted log files and update the local database.

  • Open sync: imports recorded opens and updates matching message records.
  • Unsubscribe sync: imports unsubscribe requests and marks recipients accordingly.
  • Transfer requirement: sync requires valid FTP, FTPS, or SFTP settings. If those settings are missing or wrong, sync will fail even if the scripts exist on the web server.
  • Campaign-editor gating: the Sync Tracking command in the Campaign Editor is now disabled until both the Tracking URL and transfer configuration are ready.
Deployment success does not prove synchronization will work. The same account still needs correct transfer access to the log files later.
Security

Security Recommendations

  • Prefer FTPS or SFTP over plain FTP.
  • Keep raw log files protected from direct public access.
  • Use a dedicated deployment account with the smallest practical set of permissions.
  • Avoid hosting the scripts in a public directory tree that exposes unrelated customer files.
  • Do not place tracking scripts in temporary or auto-cleaned folders.
  • Validate the public URL carefully so unsubscribe requests do not point to the wrong host or environment.
Troubleshooting

Common Problems and Fixes

Problem Likely Cause What to Check
Deployment says success but tracking does not work Public URL does not match upload folder Confirm the uploaded files live in the same folder represented by the configured public URL.
Deployment fails immediately Wrong transfer host, credentials, path, or protocol Verify host, port, username, password, transfer protocol, and remote folder permissions.
No opens recorded Images blocked, pixel not inserted, script path wrong, or sync not run Confirm the campaign included open tracking, the pixel URL is correct, and the hosted logs are being synchronized.
Unsubscribe clicks do not suppress contacts Script path wrong, sync not run, or campaign did not generate the expected unsubscribe link Test the unsubscribe URL directly and confirm sync processes the resulting request.
Browser can read the raw log file Server-side protection not configured correctly Apply the expected access-blocking behavior so logs are only retrieved through the transfer protocol.
Sync cannot retrieve logs Transfer settings are wrong or the files are in a different directory than expected Validate both deployment and retrieval paths, not just the public web path.
Operational Practice

Recommended Testing Before Public Release

  1. Deploy both scripts to a test environment first.
  2. Send a campaign to one or two inboxes you control.
  3. Open the message in more than one mail client.
  4. Use the unsubscribe link once and confirm the request records correctly.
  5. Run synchronization and verify the local database updates as expected.
  6. Repeat the same process in the production hosting environment before public rollout.
Related Guides

Next Steps

  • Use Mail Accounts to configure the sending profile that owns the tracking deployment settings.
  • Use Campaigns to enable tracking and unsubscribe behavior in outgoing mail.
  • Use Deliverability and Compliance to make sure unsubscribe and sender identity practices are production-safe.