Search Alerts Frontend

This document covers the Search Agent (Smart Stock Alerts) feature of the ADP Car Market Hub WordPress Plugin: how visitors subscribe for notifications, how double opt-in confirmation works, and how unsubscribing works.

When to use this document

Read this document if you are setting up the search alerts feature for the first time, helping a visitor understand how to subscribe and manage their alerts, or troubleshooting subscription and notification issues.

Overview

The Search Agent feature allows visitors to save a set of search criteria and receive an email notification whenever a new vehicle matching those criteria is imported into the system. The feature uses a GDPR-compliant double opt-in workflow: the visitor must click a confirmation link in their email before notifications are activated.

Visitors can unsubscribe at any time by clicking the unsubscribe link included in every notification email. No account or login is required.

Requirements or prerequisites

• The Search Agent feature must be enabled in the plugin settings (it is enabled by default, controlled by FEATURE_SEARCH_AGENT).
• The WordPress site must be able to send email. If transactional email is not configured on your hosting, consider using an SMTP plugin. Without working email delivery, confirmation and notification emails will not be sent.
• The search agent subscription form must be visible on the archive page. The plugin renders the form as part of the archive template when the feature is enabled.

Step-by-step instructions

Visitor: subscribe to search alerts

1. Open the vehicle archive page.
2. Locate the Search Agent form below or alongside the search filters.
3. Fill in at least one search criterion (such as make, model, price range, or maximum mileage).
4. Enter an email address in the subscription field.
5. Submit the form.
6. A success message appears: "Almost done! Please check your inbox and confirm your email address."
7. Open the confirmation email and click the confirmation link.
8. A confirmation message is shown on the site. The subscription is now active.

From this point, the visitor will receive an email notification whenever a new vehicle matching their saved criteria is imported.

Visitor: unsubscribe from alerts

1. Open any notification email received from the search alert system.
2. Click the unsubscribe link at the bottom of the email.
3. A confirmation page is shown. The subscription is deactivated immediately.

The unsubscribe action is irreversible from the visitor's side; the visitor would need to subscribe again to receive future alerts.

Configuration reference

Search agent criteria

The subscription form captures the following criteria. The visitor must provide at least one for the subscription to be accepted:

All criteria use AND logic: a vehicle must match every specified criterion to trigger a notification. An empty criterion is ignored.

Subscription statuses

Each subscription is stored in the plugin's custom {prefix}as24ci_search_agents table and has one of the following statuses:

Email templates

The plugin sends two types of email automatically:

Confirmation email (sent on subscribe):

• Subject: "Please confirm your search agent"
• Contains the visitor's saved criteria and the confirmation link.

Match notification email (sent when a new matching vehicle is imported):

• Subject: "New vehicle match: [vehicle title]"
• Contains the vehicle title, a link to the vehicle detail page, the saved criteria, and an unsubscribe link.

Both emails are sent as plain text using the site's configured email address as the sender. The email content is not currently configurable from the admin interface; customisation requires code-level intervention via WordPress filters.

Feature toggle

Operational notes

• The plugin only sends notifications for newly imported vehicles. Vehicles that were already in the system when a visitor subscribed do not trigger a notification. Vehicles that are updated (re-imported) also do not trigger notifications.
• The subscription form includes a honeypot field to reduce bot submissions. If the hidden field is filled in, the submission is silently accepted but no subscription is created.
• Subscriptions are stored in a dedicated custom database table. The table is created automatically during plugin activation and upgraded as needed on plugin load.
• The token used for confirmation and unsubscribe links is a 64-character cryptographically secure hex string. The token is embedded in the confirmation and unsubscribe URLs as a GET parameter.
• Confirmation links have the format: /?as24ci_sa_action=confirm&token=[token]
• Unsubscribe links have the format: /?as24ci_sa_action=unsubscribe&token=[token]
• After a successful confirmation, the visitor is redirected to the homepage with ?as24ci_sa_msg=confirmed.
• After unsubscribing, the visitor is redirected to the homepage with ?as24ci_sa_msg=unsubscribed.
• Administrators can view, edit, pause, and delete subscriptions from the plugin admin panel.

Troubleshooting

The subscription form does not appear on the archive page.

• Verify the Search Agent feature is enabled in the plugin settings.
• Check that the [as24ci_archive] shortcode or native CPT archive is being used. The search agent form is part of the archive template.
• If the form renders but is not visible, check for theme CSS overrides or Layout Manager configuration that may be hiding the widget.

The visitor received no confirmation email.

• Verify that WordPress can send email. Use a plugin such as WP Mail SMTP to test email delivery.
• Check the site's spam filter; confirmation emails from WordPress can sometimes be marked as junk.
• Confirm the visitor's email address is valid and was entered correctly.

The confirmation link is not working.

• Ensure the link is being opened in a browser and is not truncated by an email client.
• Verify the site's permalink settings allow query parameters to be processed.
• If the link was clicked more than once, the second click will not update the status (the row is only updated from pending to active once).

Notification emails are not being sent when vehicles are imported.

• Check that at least one subscription has active status.
• Confirm the imported vehicles were new (not updates to existing vehicles). The plugin does not send notifications for re-imported or updated vehicles.
• Verify that the vehicle meets the subscriber's criteria: all criteria use AND logic, so a vehicle must match every specified field.

Related documents

• Vehicle Archive
• Shortcodes Reference