Documentation · Privacy, Security and Compliance

Search Alerts Double Opt-In

This document describes the double opt-in workflow used by the search alert ("search agent") feature of the ADP Car Market Hub plugin: how subscribers sign up, how they confirm, what data is stored and how unsubscribe is handled.

This document is not legal advice. Site operators should review the consent wording, email content and retention practices with their own legal advisor.

When to use this document

Use this document when you need to:

Enable the search alert feature on a vehicle dealership site.
Document the email-based subscription workflow.
Verify that subscriber data is captured and confirmed correctly.
Configure operational checks for confirmation, matching and unsubscribe.

Overview

The search alert feature lets visitors subscribe to a set of search criteria (for example: a make, model, body type or price range) and receive an email notification when a newly imported vehicle matches those criteria.

A double opt-in workflow is enforced by design: a subscription is only activated after the visitor clicks a confirmation link sent to the email address they provided. Until the link is clicked, the subscription stays in a pending state and no notifications are sent.

Subscriptions are stored in a custom database table ({prefix}as24ci_search_agents).

Data captured per subscription

Each subscription stores the following fields:

Name (optional)
Email address
Search criteria (JSON-encoded; only known keys are accepted)
Confirmation token (cryptographically random, 64 characters)
Frequency (defaults to daily)
Status: pending, active, inactive or paused
Creation timestamp
Confirmation timestamp (set when the user clicks the confirmation link)

Accepted criteria keys are limited to a fixed list: make, model, body_type, drive_type, condition, color, min_price, max_price, mileage_max and status. Any unknown keys are dropped during sanitization.

The double opt-in workflow

The visitor submits the subscription form with an email address and at least one search criterion.
The plugin sanitizes and validates the input: - The email is validated through is_email. - At least one criterion must be provided after sanitization. - A WordPress nonce is required. - A hidden honeypot field silently discards automated submissions.
A new row is inserted with status pending and a fresh random token.
A confirmation email is sent to the address using wp_mail. The email contains a one-time confirmation link of the form ?as24ci_sa_action=confirm&token=… pointing to the site home URL.
When the visitor clicks the link, the plugin verifies that the token has the expected length and that a matching pending row exists. If both are true, the row is updated to active, the confirmation timestamp is recorded and the visitor is redirected to the home URL with a status message.
From this point, the subscription is included in the matching engine and notifications can be sent.

If the link is never clicked, the subscription remains pending and no notifications are produced.

Notification workflow

After a vehicle is imported, the plugin checks all active subscriptions:

The matching engine compares each non-empty criterion against the vehicle's stored data using AND logic.
For new vehicles only (not updates), a notification email is sent to each subscription whose criteria match.
The notification email is sent with wp_mail and includes:
The matched vehicle's title and URL.
A summary of the subscriber's search criteria.
An unsubscribe link of the form ?as24ci_sa_action=unsubscribe&token=….

Unsubscribe is single-click: clicking the link sets the subscription's status to inactive and stops further notifications.

Step by step: enable and verify the workflow

Make sure the site can send email reliably (test by submitting a normal contact form or sending a test mail). The double opt-in depends entirely on email delivery.
Add the search alert subscription form to the appropriate page or template (for example, the search results or vehicle archive page).
Submit a test subscription with an email address you control and at least one criterion.
Confirm that the confirmation email arrives in your inbox (check spam if not), and that clicking the link redirects to the home URL with a confirmation message and changes the row to active in the admin overview.
Open the Search Alerts admin tab and verify the new entry's status, email and criteria.
Optionally, import or wait for a new matching vehicle and verify that a notification email is delivered.
Click the unsubscribe link in the notification and verify that the status changes to inactive.

Configuration reference

The double opt-in workflow itself is enforced and is not user-configurable: new subscriptions always start as pending and require email confirmation. Administrators can manage existing subscriptions in the Search Alerts admin tab:

Action	Effect
Edit	Update the name, email, criteria, frequency or status of an existing subscription.
Set status	Change a subscription to `active`, `inactive` or `paused`.
Delete	Permanently delete a subscription row.

Operational notes

Tokens: each subscription has its own 64-character random token used for both the confirmation link and the unsubscribe link. Tokens should be treated as sensitive — anyone with the token can unsubscribe the subscription. They are not displayed to end users in the public UI.
Pending subscriptions: rows in pending status never receive notifications. Site operators may want to periodically review and remove pending entries that were never confirmed. The plugin does not currently apply automatic expiry to pending subscriptions. Verify this behavior in the current plugin version before publishing automation that depends on it.
Updates do not trigger alerts: only newly imported vehicles trigger notifications. Updates to existing vehicles do not produce alerts.
Email delivery: notifications use wp_mail. Failed deliveries (for example bounces or rate-limited transports) are not retried automatically.
Uninstall: the search agents table is dropped unconditionally on uninstall, so subscriber email addresses and search criteria do not persist after the plugin is removed. See Data Storage Overview.

Operational checks

Recommended checks to run periodically:

Submit a fresh test subscription and confirm end-to-end (subscribe → confirmation email → click link → status active).
Trigger an unsubscribe from a notification and confirm the status moves to inactive.
In the Search Alerts admin tab, monitor the proportion of pending versus active rows. A persistently high pending ratio usually indicates an email delivery problem (for example, confirmation emails ending up in spam).

Troubleshooting

No confirmation email arrives — verify general email delivery on the site, check the spam folder, and confirm that the site's mail transport is correctly configured.
Clicking the confirmation link does nothing — confirm that the URL was not modified by the email client, and that the row is still in pending status. Once a row is confirmed (or moved away from pending), the link no longer changes the status.
Subscriber receives no alerts even after confirming — verify that the subscription is active and that the criteria are not so restrictive that no imported vehicle matches. Remember that updates to existing vehicles do not trigger alerts.
Subscriber wants to be removed — they can use the unsubscribe link in any notification email; an administrator can also delete or set the status to inactive from the Search Alerts admin tab.
Suspected spam submissions — the form already includes a nonce, a honeypot field and the double opt-in itself, which prevents activation for invalid email addresses. Persistent abuse may require server-side protections.