MyListing Notification Subscriptions
The {CODICTS} MyListing Notification Subscriptions plugin lets users subscribe to email and push notifications for new listings matching their chosen filters. Admins create Subscription Forms with configurable filter fields; users fill out the forms on the frontend, choose their preferred notification frequency, and receive periodic digest emails (or instant push notifications) whenever new matching listings are published.
Installation & Activation
Start by downloading the plugin from the Downloads page on your dashboard on the CoDicts website.
After downloading, install and activate the plugin in WordPress by navigating to “Plugins” > “Add New” > “Upload Plugin” and selecting the downloaded zip file. Click “Install Now” and then “Activate”.
Once activated, navigate to “Notification Subscriptions” in the WordPress admin sidebar. Create at least one Subscription Form, then copy the generated shortcode and paste it on any page where you want the subscription widget to appear.
Key Features
| Feature | Description |
|---|---|
| Subscription Forms | Place subscription widgets anywhere via shortcode. Create multiple forms with different filter configurations. |
| Configurable Filters | Filter by categories, regions, tags, custom taxonomies, listing types, priority, proximity/radius, keywords, and more. |
| Multiple Frequencies | Instant, monthly, twice a month, weekly, or disabled — each customizable with labels, descriptions, and sort order. |
| Push Notifications | Instant frequency triggers OneSignal web push notifications when new listings are published. |
| Paid Intervals | Attach WooCommerce Subscription products to premium frequencies — users purchase a subscription to unlock the interval. |
| Customizable Email Templates | Full HTML template editor for both confirmation and notification emails, with template tags for personalization. |
| Auto-Subscribe by Role | Automatically subscribe users of specific roles, including new registrations. |
| Proximity/Radius Filter | Map-based location filter with address search and adjustable radius. |
| Guest User Support | Non-registered visitors can subscribe by providing their email address. |
| Frequency Control | Per-listing-type, per-package notification frequency limits for fine-grained control. |
| Subscriber Management | Admin view of all subscribers with expandable filter details and CSV export. |
| One-Click Unsubscribe | Auto-generated unsubscribe links in every email, plus support for custom unsubscribe pages. |
| Test Email Tool | Send test notification emails directly from the admin panel. |
How It Works
The plugin works in three stages:
1. Admin creates Subscription Forms — You define which filters are available (categories, regions, keywords, proximity, etc.), set default values, choose which filters users can modify, configure email templates, and set up notification intervals.
2. Users subscribe on the frontend — Users visit the page with your shortcode and complete a two-step process: first they choose their filters (what listings they’re interested in), then they pick a notification frequency (how often they want to be notified). Their subscription is saved.
3. Notifications are delivered automatically — A daily background process checks all subscribers, determines who is due for a notification based on their chosen frequency, queries for new matching listings, and sends digest emails. For the “Instant” frequency, notifications are sent immediately when a listing is published — via email and/or OneSignal push notification.
Creating a Subscription Form
Step 1: Add a New Form
Navigate to Notification Subscriptions → Add Subscription Form in the WordPress admin.
Step 2: Enter a Title
Give the form a descriptive name (e.g., “New Restaurant Alerts” or “Weekly Listing Digest”). This title is for your internal reference.
Step 3: Configure the Four Tabs
The form editor has four tabs:
| Tab | Purpose |
|---|---|
| Subscription Form | Configure the filter fields and their visibility on the frontend. |
| Confirmation Email Template | Design the email sent when a user first subscribes. |
| Notification Email Template | Design the periodic digest email containing new matching listings. |
| Settings | Configure notification intervals, auto-subscribe roles, and confirmation toggle. |
Step 4: Save
Click “Save”. A shortcode will be displayed below the title field — copy it for use on your pages.
Step 5: Place the Shortcode
Paste the shortcode on any WordPress page or widget:
[codicts-mylisting-notification-subscriptions id="123"]Replace 123 with your Subscription Form’s actual ID. Multiple forms can be placed on the same page with different IDs.
Subscription Form Tab (Filter Fields)
This tab defines which filters are available and their default values.
Available Filters
| Filter | Description | Default |
|---|---|---|
| Email input for guest users. Paired with “Allow unsubscribed users to opt-in?” toggle. Hidden for logged-in users. | — | |
| Filter by Keyword | Free-text keyword search filter. | Empty |
| Filter by Categories | Filter by listing categories. | All |
| Filter by Region | Filter by regions. | All |
| Filter by Tags | Filter by listing tags. | All |
| Filter by Post Categories | Filter by standard WordPress post categories (for blog post notifications). | All |
| Filter by Custom Taxonomies | Automatically generated for each MyListing custom taxonomy. | All |
| Filter by Proximity | Location-based filter with map, address search, and radius slider. Supports Google Maps and OpenStreetMap. | — |
| Filter by Listing Type(s) | Filter by MyListing listing types. | All |
| Filter by Priority | Filter by listing priority: Normal, Featured, Promoted. | All |
| Limit Results by | Maximum number of listings included in each notification email. | 25 |
| Order by | Sort by: Date, Included order, Rating, Random, or Last modified date. | Date |
| Order | Ascending or Descending. | Descending |
| Order by priority first? | When “Yes”, promoted/featured listings appear first in the email digest. | Yes |
The “Show on Frontend” Toggle
Each filter has a paired “Show this option on frontend?” checkbox:
| Setting | Behavior |
|---|---|
| Checked | The user sees this filter and can change it. |
| Unchecked | The admin’s default value is enforced silently. The user cannot see or change this filter. |
Email Templates
Both the Confirmation Email and Notification Email templates are fully customizable with an HTML code editor.
Template Fields
| Field | Description |
|---|---|
| From | Sender email in the format Name <email@domain.com>. |
| Subject | Email subject line. Supports template tags. |
| Message body | HTML email body. Supports template tags. Edited in a code editor with syntax highlighting. |
Available Template Tags
| Tag | Description | Available In |
|---|---|---|
[reciever-email] | Subscriber’s email address. | Both |
[reciever-name] | Subscriber’s display name (or email username if not registered). | Both |
[listing-feed] | HTML block of matching new listings with thumbnails, titles, and descriptions. | Notification only |
[unsubscribe-url] | One-click unsubscribe URL. | Both |
[unsubscribe-key] | Query string for building custom unsubscribe pages. | Both |
Note: The
[listing-feed]tag is only available in the Notification Email Template. The Confirmation Email is a welcome message and does not include listing data.
Confirmation Email
This optional email is sent when a user first subscribes. Enable or disable it in the Settings tab using the “Send Confirmation Notification” toggle.
Notification Email
This is the periodic digest email containing new matching listings. The [listing-feed] tag generates listing blocks with thumbnails, titles, and 150-character description excerpts. If no new matching listings are found since the last notification, no email is sent.
Settings Tab
The Settings tab controls notification intervals, auto-subscribe behavior, and the subscription step appearance.
Auto-Subscribe User Roles
Check user roles (e.g., Subscriber, Customer) to automatically subscribe existing users of those roles when the form is saved. New users registering with a checked role are also auto-subscribed.
Send Confirmation Notification
Enable or disable the confirmation email sent when a user first subscribes.
Subscription Step Text
| Setting | Description | Default |
|---|---|---|
| Subscription Step Title | Heading displayed on Step 2 (frequency selection). | “Choose notification frequency” |
| Subscription Step Sub Text | Description below the heading on Step 2. | “Select how many times you want to be notified” |
Notification Interval Configuration
The plugin includes six built-in notification intervals. For each interval you can configure:
| Setting | Description |
|---|---|
| Enabled? | Whether this interval appears as an option for users. |
| Default Interval | Mark one interval as the pre-selected default. |
| Sort Order | Numeric position for display ordering. |
| Display Label | Custom label shown to users (e.g., “Weekly Digest” instead of “Every week”). |
| Description | Optional description text shown below the label. |
| Attach Paid Subscription Product | Link a WooCommerce Subscription product. Users selecting this interval are redirected to checkout. (Requires WooCommerce + WooCommerce Subscriptions.) |
The Instant interval has two additional settings:
| Setting | Description |
|---|---|
| Enabled Web Push Notification? | Send OneSignal push notifications when new listings are published. (Requires OneSignal plugin.) |
| Enabled Email Notification? | Send email notifications immediately when new listings are published. |
Available Intervals
| Interval | Behavior |
|---|---|
| Instant | Notifications sent immediately when a matching listing is published (via push and/or email). |
| Default | Uses the frequency set in Frequency Control settings (per listing type/package). |
| Once a month | Monthly digest email. |
| Twice a month | Bi-weekly digest email. |
| Every week | Weekly digest email. |
| Disabled | No notifications sent (effectively unsubscribed for this form). |
Frequency Control (Global)
Navigate to Notification Subscriptions → Frequency Control to set per-listing-type, per-package notification frequency limits.
This feature lets you control notification frequency at the listing level rather than just the subscriber level:
1. Enable frequency control for a listing type.
2. For each WooCommerce listing package (or “No Package” for unpackaged listings), choose a notification frequency: Instant, Once a month, Twice a month, Every week, or Disabled.
3. Listings from disabled packages will not appear in notification emails regardless of the subscriber’s chosen interval.
This acts as a secondary filter. For example, even if a subscriber chooses weekly notifications, listings from a package set to “monthly” will only appear on the monthly cycle. This allows you to offer premium packages where listings get notified about more frequently.
Frontend User Experience
Two-Step Subscription Flow
Step 1 — Filter Selection:
Users see the filter fields that you’ve enabled (categories, keywords, proximity, etc.) and configure what kind of listings they want to be notified about. If the user is already subscribed, their previously saved values are pre-filled and a “Subscribed” indicator is shown.
Step 2 — Frequency Selection:
Users choose how often they want to be notified. Each interval shows its custom label, description, and price (if a WooCommerce product is attached). They click “Subscribe” to complete the process.
Guest Users
Non-registered visitors can subscribe by providing their email address — if you’ve enabled the “Allow unsubscribed users to opt-in?” toggle in the Subscription Form tab. The email field is automatically hidden for logged-in users.
Updating a Subscription
If a user is already subscribed and submits the form again, their existing subscription for that form is updated with the new filter values and frequency.
Subscription Status Indicators
| Status | Meaning |
|---|---|
| Subscribed (green checkmark) | Active subscription. |
| Subscription on hold | Associated WooCommerce subscription is on hold. |
| Subscription cancelled | Associated WooCommerce subscription was cancelled. |
| Subscription expired | Associated WooCommerce subscription has expired. |
| Subscription pending | Payment is pending for a paid interval. |
Paid Notification Intervals (WooCommerce)
You can monetize notification frequencies by linking WooCommerce Subscription products to specific intervals.
Requires: WooCommerce and WooCommerce Subscriptions must both be installed and active.
How It Works
1. Create a WooCommerce Subscription product (e.g., “Weekly Alerts — $5/month”).
2. In the Subscription Form’s Settings tab, attach the product to the desired interval using the “Attach Paid Subscription Product” dropdown.
3. When a user selects that interval and clicks Subscribe, they are redirected to the WooCommerce checkout to purchase the subscription.
4. After successful purchase, the paid interval is activated automatically.
5. Before each notification email, the plugin verifies the WooCommerce subscription is still active. Inactive subscriptions do not receive notifications.
6. When a user unsubscribes, any associated WooCommerce subscriptions are cancelled automatically.
Push Notifications (OneSignal)
The “Instant” notification interval can send OneSignal web push notifications when new matching listings are published.
Requires: The OneSignal WordPress plugin must be installed and configured with your App ID and REST API Key.
How It Works
1. Install and configure the OneSignal WordPress plugin.
2. In your Subscription Form’s Settings tab, enable “Enabled Web Push Notification?” for the Instant interval.
3. When a logged-in user visits your site, the plugin automatically links their WordPress account to their OneSignal device for targeted notifications.
4. When a new listing is published, the plugin checks all subscribers with the Instant frequency, runs their filters against the new listing, and sends push notifications to matches.
5. Listing authors are automatically excluded from receiving push notifications about their own listings.
You can also enable “Enabled Email Notification?” on the Instant interval to send both push and email notifications simultaneously.
Auto-Subscribe by User Role
In the Settings tab, you can check user roles to automatically subscribe:
Existing users of the checked roles are subscribed when the form is saved.
New users registering with a checked role are automatically subscribed upon registration.
Auto-subscribed users receive the default notification interval. They can adjust their filters and frequency by visiting the subscription page, or unsubscribe via the email link.
Unsubscribe Mechanism
One-Click Unsubscribe
Every notification email includes an unsubscribe link (via the [unsubscribe-url] template tag). Clicking it immediately sets the subscriber’s interval to Disabled and cancels any associated WooCommerce subscriptions. A confirmation message is displayed.
Custom Unsubscribe Page
Use the [unsubscribe-key] template tag to build custom unsubscribe pages with your own design:
<a href="https://yoursite.com/your-unsubscribe-page?[unsubscribe-key]">Unsubscribe</a>The tag expands to a query string containing the subscriber’s unique account key and form ID. The cmlns_pg=1 parameter in the expanded tag prevents the default success message, allowing your custom page to handle the response.
Subscriber Management
Subscribed List
Navigate to Notification Subscriptions → Subscribed List to view all subscribers.
The list shows each subscriber’s email, whether they’re a registered user, their subscription date, and which forms they’re subscribed to with their frequency status. Click a form badge to expand and view the subscriber’s saved filter details.
CSV Export
Click “Export to CSV” on the Subscribed List page to download a spreadsheet with all subscriber data, decoded filter values, and registration status.
Test Email
Navigate to Notification Subscriptions → Tools to send test notification emails. Enter an email address, select a Subscription Form template, and click “Send Test Email” to verify your template rendering and email delivery.
Managing Subscription Forms
Navigate to Notification Subscriptions → Subscription Forms to see all your forms in a list.
| Feature | Description |
|---|---|
| Search | Search forms by title. |
| Sort | Sort by Title, Author, or Date. |
| Edit | Click a form title to open the editor. |
| Shortcode | Each row displays the shortcode in a copy-friendly input field. |
| Duplicate | Create a copy of a form. |
| Delete / Bulk Delete | Permanently delete forms individually or in bulk. |
WordPress Posts Support
In addition to MyListing’s job_listing post type, the plugin can also filter and notify for standard WordPress posts. Use the “Filter by Post Categories” field to filter by WordPress post categories. The notification digest email and listing feed support both listing types.
Frequently Asked Questions
Can I create multiple Subscription Forms?
Yes. Each form can have different filters, email templates, and interval configurations. Place them on different pages using their unique shortcodes.
Can users subscribe to multiple forms?
Yes. Each form’s subscription is stored independently. A single user can subscribe to multiple forms with different filters and frequencies.
What happens if a user submits the form again?
Their existing subscription for that form is updated with the new filter values and interval.
Can guests (non-registered users) subscribe?
Yes, if the “Allow unsubscribed users to opt-in?” toggle is enabled. Guests provide their email address manually.
How does the “Default” frequency work?
The “Default” frequency uses per-listing-type, per-package timing set in the global Frequency Control settings. This allows different listings to notify at different rates depending on their package.
What is the “Instant” frequency?
Instant triggers notifications immediately when a new matching listing is published, via OneSignal push notifications and/or email. OneSignal is required for push notifications; email notifications work without it.
Can I monetize notification frequencies?
Yes. Attach WooCommerce Subscription products to specific intervals in the Settings tab. Users must purchase the subscription to access that frequency. Requires WooCommerce and WooCommerce Subscriptions.
How do unsubscribe links work?
Each email contains a unique unsubscribe URL. Clicking it sets the user’s interval to Disabled and cancels any associated WooCommerce subscriptions. Use the [unsubscribe-key] tag for custom unsubscribe pages.
Can I export subscriber data?
Yes. Navigate to Notification Subscriptions → Subscribed List and click “Export to CSV”.
How do I test email templates?
Navigate to Notification Subscriptions → Tools. Enter an email address, select a template, and click “Send Test Email”.
What if no new listings match the subscriber’s filters?
No email is sent. The plugin only sends a notification when there are new matching listings published since the last notification.
Are listing authors notified about their own listings?
No. Listing authors are automatically excluded from receiving instant push notifications about their own listings.
Does this work with OpenStreetMap?
Yes. The proximity filter supports both Google Maps and OpenStreetMap for address search and map display.
Troubleshooting
Notification Emails Not Being Sent
| Cause | Solution |
|---|---|
| WP-Cron not running | Ensure DISABLE_WP_CRON is not set to true in wp-config.php. On low-traffic sites, consider setting up a real server cron job that triggers wp-cron.php directly. An SMTP plugin (like WP Mail SMTP) is also recommended for reliable email delivery. |
| No matching listings | The query must find listings published after the subscriber’s last notification. If no new listings match the filters, no email is sent. |
| Frequency cycle not reached | Monthly subscriptions only trigger once per month. Check the subscriber’s cycle timing in the Subscribed List. |
| WooCommerce subscription inactive | For paid intervals, the associated WooCommerce subscription must be active. Check the subscription status in WooCommerce. |
| Frequency Control set to Disabled | Check the global Frequency Control settings. Listings from disabled packages will not appear in notifications. |
| Interval disabled on form | Verify the interval is enabled in the form’s Settings tab. |
Push Notifications Not Working
| Cause | Solution |
|---|---|
| OneSignal not installed | Install and configure the OneSignal WordPress plugin. |
| Missing API credentials | Verify the OneSignal App ID and REST API Key are set in OneSignal settings. |
| User not logged in | OneSignal identity binding requires the user to be logged in so their WordPress account can be linked to their device. |
| “Enabled Web Push Notification?” not checked | Enable push notifications for the Instant interval in the form’s Settings tab. |
| Self-notification | Listing authors are excluded from receiving push notifications about their own listings. This is expected behavior. |
Subscription Form Not Displaying
| Cause | Solution |
|---|---|
Wrong or missing id | Verify the shortcode has the correct id parameter matching an existing Subscription Form. |
| MyListing not active | The plugin requires an active MyListing theme to function. |
| JavaScript error | Check the browser console for errors that might prevent the form from initializing. |
Guest Users Cannot Subscribe
| Cause | Solution |
|---|---|
| Toggle not enabled | Ensure the “Allow unsubscribed users to opt-in?” toggle is checked in the form’s Subscription Form tab. |
Paid Interval Not Activating After Purchase
| Cause | Solution |
|---|---|
| WooCommerce Subscriptions not active | Both WooCommerce and WooCommerce Subscriptions must be installed and active. |
| User didn’t complete checkout | The paid interval only activates after the WooCommerce checkout is completed. Check WooCommerce orders for pending payments. |
| Wrong product type | The attached product must be a WooCommerce Subscription product, not a simple product. |
Proximity/Map Filter Not Working
| Cause | Solution |
|---|---|
| Map API not configured | Ensure Google Maps API or OpenStreetMap is properly configured in your MyListing theme settings. |
| Map not loading | Check for JavaScript errors in the browser console. Some popup or modal-based form placements may require additional initialization. |
“MyListing Theme Not Detected” Error
The MyListing theme must be installed and active. Go to Appearance → Themes to verify.
Settings Page Not Appearing
| Cause | Solution |
|---|---|
| MyListing not active | Install and activate the MyListing theme first. |
| Plugin not activated | Verify the plugin is active in Plugins → Installed Plugins. |
For further support, visit codicts.com or contact us at support@codicts.com.