User Manual - Newsletter Popup & Maker
Newsletter Popup & Maker user guide
Installing the Magento 2 Newsletter Popup & Maker extension
Command Line Installation
-
Backup your web directory and store database
-
Download the Scheduler installation package
-
Upload contents of the Scheduler installation package to your store root directory
-
In SSH console of your server navigate to your store root folder:
|
Run the following command:
php bin/magento module:enable Aheadworks_Newsletter |
then:
php bin/magento setup:upgrade |
after:
php bin/magento setup:static-content:deploy -f |
-
Flush store cache; log out from the backend and log in again
|
Make sure the installation is done from the FTP administrator account. Otherwise, set 775 permissions to the store root directory after the extension is deployed. |
Composer Installation
If you are installing an extension from Aheadworks for the first time, you need to add our composer repository to your Magento store:
Login to your ssh console and navigate to your store folder:
cd path_to_the_store_root_folder |
Run the following commands:
composer config repositories.aheadworks composer https://dist.aheadworks.com/ |
After the command was executed successfully, you can use the composer to install the extension.
To install the extension:
Login to your ssh console and navigate to your store folder:
cd path_to_the_store_root_folder |
Run the following command to install the latest version of the extension:
composer require aheadworks/module-scheduler |
if you need to install a specific version, run this command:
composer require aheadworks/module-scheduler<version> |
Specify the version of the extension in <version>
When prompted, enter Public Key (Username) and Private Key (Password):
Both Public Key (Username) and Private Key (Password) can be found in My Projects and Licenses in your personal account on our site:
To upgrade the extension:
To update or upgrade an extension:
Download the updated extension file. Take note of the module-name and version. Export the contents to your Magento root.
If a composer package exists for the extension, run one of the following.
Update per module name:
composer update aheadworks/module-newsletter |
Updater per version:
composer require aheadworks/module-newsletter:<version> |
Run the following commands to upgrade, deploy, and clean the cache.
php bin/magento setup:upgrade --keep-generated |
Set up cron
If you have already configured cron jobs for your Magento installation then you can skip this step. Read the following instructions on setting cron job for your Magento store: Magento user guide.-
Generally, it would be enough to run in SSH console of your server:
crontab -e |
And insert the following line:
*/3 * * * * php -c <ini-file-path> <your Magento install dir>/bin/magento cron:run |
Remember to confirm the Save request when exiting the installation.
Uninstalling the Magento 2 Newsletter Popup & Maker extension
Since Magento introduced declarative Database you need to be very careful when uninstalling or disabling the module.
|
NOTE: Please be very careful when uninstalling/disabling this module. This module uses a declarative DB scheme. Once the module is uninstalled its DB tables will be lost. |
Manual Removal
1. Disable the module by executing the following commands:
php bin/magento module:disable Aheadworks_Newsletter |
2. Remove the extension files from the following folder:
app/code/Aheadworks/Newsletter |
Automatic Removal (via Composer)
1. Disable the module by executing the following commands:
php bin/magento module:uninstall Aheadworks_Newsletter |
Extension Compatibility
|
Module Version |
Magento Version |
|
As of version 1.0.0 |
2.4.6 - 2.4.8 |
Introducing to Magento 2 Newsletter Popup & Maker
Extension Overview
Newsletter Popup & Maker for Magento 2 provides a comprehensive toolkit for growing your subscriber base through targeted storefront popups and personalized incentives. The extension allows you to configure precise display rules, integrate unique coupon codes, and automate follow-up communication.
In addition to popup management, the module features a Visual Newsletter Editor, enabling the creation and styling of Magento email templates using a drag-and-drop interface directly within the admin panel.
Key Features
-
Design professional newsletters with a Visual Newsletter Editor.
-
Drive conversions by offering unique discount codes that can be applied to the cart automatically.
-
Target the right audience by showing popups based on specific pages, categories, or store views.
-
Capture more leads by showing popups at the perfect moment using time-delay triggers or specific CSS selectors.
-
Ensure brand consistency across multiple stores with easy template export and import tools.
-
Optimize for all devices with fully responsive templates that look perfect on mobile and desktop.
-
Protect your growth from spam bots with integrated Google reCAPTCHA v3 support.
Using Magento 2 Newsletter Popup & Maker
Extension Configuration
To enable the extension, go to Stores > Configuration > AHEADWORKS EXTENSIONS > Newsletter
General Settings
Configure the core behavior of the extension:
-
Enable popup on frontend — toggles the visibility of the subscription window on the storefront:
-
Yes — the module is enabled, and popups will be displayed based on active campaign rules.
-
No — the module is disabled globally, and no popups will appear to visitors.
-
Development Mode — defines the cookie persistence during the testing phase:
-
Yes — sets a 1-second cookie lifetime, allowing the popup to reappear upon every page reload for rapid testing.
-
No — uses the standard timing defined in your campaigns, which is recommended for live production stores.
-
Cookie Name — defines the unique prefix for the browser cookie that tracks if a visitor has already seen or dismissed a popup.
Default Magento Newsletter Subscription Settings
This section extends popup features to standard Magento forms, such as those located in the footer or sidebar:
-
Send coupon to all subscribers — controls the distribution of discount codes across all subscription methods:
-
Yes — unique discount codes will be sent to every new subscriber, regardless of the form used.
-
No — restricts coupon generation strictly to users who subscribe via the extension's popups.
-
Campaign — specifies the default campaign rules used to generate coupons for standard Magento subscribers.
-
Show Additional Fields — toggles the visibility of custom popup fields in standard subscription blocks:
-
Yes — displays extra fields (e.g., Name or Preferences) in default Magento subscription forms.
-
No — keeps standard forms limited to the default email field only.
Google Recaptcha Settings
Protect your mailing list from spam and automated bots by configuring verification:
-
Enable Google ReCaptcha V3 — toggles background verification for all subscription requests:
-
Yes — activates reCAPTCHA v3 to validate subscriptions.
-
No — disables reCAPTCHA protection.
-
Include recaptcha/api.js — controls the loading of the Google script:
-
Yes — loads the necessary script from Google's servers.
-
No — prevents loading (select this if your theme or another module already includes it).
-
Site Key / Secret Key — used to authenticate your site with Google; enter your public and private keys here.
How to set up reCAPTCHA:
-
Go to https://www.google.com/recaptcha/admin and sign in with your Google account.
-
Create a new site (or use an existing one) for your domain, selecting reCAPTCHA v3.
-
Copy the Site Key and Secret Key from the Google console.
-
Paste both into the fields above.
-
Save the configuration.
Newsletter Editor
Enable the visual drag-and-drop builder for newsletter templates:
-
Is Active — toggles the visual editor tools within the admin panel:
-
Yes — enables the Newsletter Editor menu and the builder interface.
-
No — hides the editor tools from the admin.
-
Sender Name — defines the default "From Name" used when creating new templates via the builder.
-
Sender Email — defines the default "From Email" used for new templates.
Newsletter Editor Settings
Manage advanced styling options for your email templates:
-
Additional Fonts — manages the typography options available in the builder:
-
Enter custom font names (one per line) to include them in the editor's typography settings.
-
Translate
This section allows you to customize and localize the text displayed to customers on the storefront. Each field can be translated individually for different store views.
Creating a new popup
To manage your popup designs, navigate to Marketing > Newsletter Popup By Aheadworks > Popups. This grid allows you to create, view, and edit all subscription windows used in your store.
To start building a new design, use the Add New Popup button.
-
Add New Popup — opens the configuration form to define the appearance and behavior of your subscription window.
-
Content Types — click the arrow on the button to choose the popup type:
-
Newsletter Subscription Form — used to collect customer emails and offer discounts.
-
Static Cms Block — allows you to embed pre-built content from a Magento CMS block into the popup.
Newsletter Subscription Form
General Settings
-
Name — Assign a unique name to the popup.
Popup Settings
-
Theme — select a visual theme for the popup. Built-in options include Default, Clear, Orange, and Osom.
-
Disable Auto Position on Mobile Devices — Controls the positioning logic for mobile screens:
-
No — the extension automatically scales and positions the popup to fit mobile screens.
-
Yes — disables automatic logic. Use this if your store design is non-responsive or if you are using custom CSS for manual positioning.
Based on the configuration screens for creating a Newsletter Subscription Form, here is the functional breakdown for the guide:
General Settings
-
Name — assigns a unique name to the popup for identification in the admin panel grid.
Popup Settings
-
Theme — provides visual presets for the popup, such as Default, Clear, Orange, or Osom.
-
Disable Auto Position on Mobile Devices — determines the positioning logic of the window on mobile devices:
-
No — the system automatically scales and centers the popup for correct display on smartphone screens.
-
Yes — automatic positioning is disabled; this is useful if you are using custom CSS styles or if your site design is non-responsive.
Discount Coupon
Link a unique discount to the subscription process:
-
Is Active — toggles the coupon generation feature:
-
Yes — enables the generation and distribution of unique discount codes for this popup.
-
No — disables coupon functionality for this popup.
-
Show in Popup — controls immediate code visibility:
-
Yes — displays the generated coupon code inside the popup window immediately after the user subscribes.
-
No — hides the coupon code from the popup interface (but it still will be sent via email if option Is Active is set to yes).
-
Apply to Cart — manages automatic discount application:
-
Yes — automatically applies the discount code to the customer's shopping cart upon successful subscription.
-
No — requires the customer to manually enter the code during checkout.
-
Cart Price Rule — allows you to select the specific Magento sales rule used to govern the discount.
-
Coupon Customization — configure technical details such as Coupon lifetime, Code Length, Code Format, and Prefix/Suffix.
Follow Up Email
-
Is Active — toggles automated reminders for unused coupons:
-
Yes — the system sends a follow-up email if the customer has not yet redeemed their coupon.
-
No — disables the follow-up email feature.
-
Email Template — allows you to choose the template used for the follow-up message.
-
Send after X hours — sets the delay (in hours) before the reminder is sent.
-
Sender Name/Email — set a custom name and email address for these specific outgoing messages.
Social Links
-
This section provides fields to enter links for Facebook, Twitter, Pinterest, Instagram, LinkedIn, and YouTube to be displayed in the popup.
Trigger Button Settings
-
Is Active — toggles the manual trigger button:
-
Yes — displays a floating button that allows visitors to open the popup manually.
-
No — disables the manual trigger button.
-
Trigger Button HTML selector — specify a CSS selector to bind the popup trigger to an existing element on your site.
-
Button Text — customize the text displayed on the floating trigger button.
-
Button Only — defines the popup's appearance logic:
-
Yes — the popup will not show automatically; it will only appear when a user clicks the trigger.
-
No — the popup follows standard automatic display rules.
-
Button Position — choose where the trigger button floats and adjust Padding Top for fine-tuned placement.
Additional Fields
This section allows you to expand your subscription form by collecting specific customer data beyond a basic email address.
-
Field Name — sets the internal unique identifier for the field used within the Magento Admin panel.
-
Field Label — defines the administrative title for the field.
-
Input Type — determines the format of the data entry field on the storefront. Available options include:
-
Text — includes Text Field (single line) and Textarea (multi-line).
-
Select — provides a Drop Down menu for fixed options.
-
Checkbox — allows users to toggle a selection, such as agreeing to terms.
-
Hidden — creates a field that is not visible to the user but can pass background data.
-
Required — toggles the validation for this specific field:
-
Checked — the field is mandatory; the user cannot submit the form without completing it.
-
Unchecked — the field is optional.
-
After Email Field — defines the visual order of the form:
-
Checked — the custom field will be placed below the standard email input.
-
Unchecked — the field will be placed above the email input.
-
Store Frontend Label — allows you to set a specific, customer-facing title for the field that will appear in the popup.
-
Error Message: field is required — permits the customization of the alert text shown to the user if they attempt to submit a mandatory field while it is empty.
Static CMS Block
General Settings
-
Name — assigns a unique name to the popup for identification in the admin panel grid.
Popup Settings
-
Disable Auto Position on Mobile Devices — determines the positioning logic of the window on mobile devices:
-
No — the system automatically scales and centers the popup for correct display on smartphone screens.
-
Yes — automatic positioning is disabled; this is useful if you are using custom CSS styles or if your site design is non-responsive.
Trigger Button Settings
-
Is Active — toggles the manual trigger button:
-
Yes — displays a floating button that allows visitors to open the popup manually.
-
No — disables the manual trigger button.
-
Trigger Button HTML selector — specify a CSS selector to bind the popup trigger to an existing element on your site.
-
Button Text — customize the text displayed on the floating trigger button.
-
Button Only — defines the popup's appearance logic:
-
Yes — the popup will not show automatically; it will only appear when a user clicks the trigger.
-
No — the popup follows standard automatic display rules.
-
Button Position — choose where the trigger button floats and adjust Padding Top for fine-tuned placement.
Static CMS Block Settings
This section selects the content that will be displayed inside the pop-up window:
-
Static CMS Block — contains a dropdown list of all existing CMS blocks in your store. You can select any block. The content of the selected block (text, images, links) will be fully rendered within the popup window.
Creating a new campaign
To manage the display rules for your popups, navigate to Marketing > Newsletter Popup By Aheadworks > Campaigns. This section allows you to schedule and target specific popups to different customer segments or pages.
General Settings
Configure the basic targeting and timing for your campaign in this section:
-
Is Active — toggles the campaign functionality globally:
-
Yes — the campaign is enabled and will process rules to show the popup.
-
No — the campaign is disabled; no popups assigned to this campaign will appear on the storefront.
-
Campaign Name — enter a unique name to identify this set of rules in the admin panel.
-
Start Date / End Date — use the calendar icons to define the exact campaign activity period.
-
Show in Stores — select the specific Store Views or Websites where the popup should be displayed.
-
Show in Pages — select the page types where the popup is allowed to appear.
-
Required Params — allows for URL-based targeting. Enter specific parameters to show the popup only to visitors coming from specific marketing sources.
Popup Settings
Use these settings to control how and when the popup appears to your customers:
-
Popup — select the pre-designed popup from the dropdown menu.
-
Popup Delay Time — set the number of seconds a visitor must stay on the page before the popup appears.
-
Close after Click on Popup Layer — controls how the popup can be closed:
-
Yes — the popup will close if a user clicks on the background layer outside the popup window.
-
No — the user must interact with the popup or click the specific close button to dismiss it.
-
Show again after X minutes — defines the period before the same user sees the popup again
Note: enter 525600 minutes for a year-long block
-
Show popup once per — determines the frequency tracking logic:
-
Store — the frequency limit applies across the entire store view.
-
Page — the frequency limit is tracked individually for each unique page.
Newsletter editor
Enabling the Newsletter Editor
Before you can start building templates, you must activate the editor in your store settings:
-
Navigate to Stores > Configuration > Aheadworks Extensions > Newsletter.
-
Locate the Newsletter Editor group and set Is Active to Yes.
-
Enter a Sender Name and Sender Email to be used as the default contact information for your templates.
-
Click Save Config to apply these settings.
Creating a New Newsletter Template
This section defines the core identity and delivery parameters of your email campaign.
-
Template Name — enter a unique internal name for the template to ensure easy identification within the admin panel.
-
Template Subject — specify the subject line as it will appear in the customer's inbox. Sender Name — define the display name that recipients will see in the "From" field.
-
Sender Email — enter the email address from which the newsletter campaign will be dispatched.
Template Content section allows you to build your email using a flexible editor that supports both visual design and direct code editing.
-
Show / Hide Editor — use this button to open or close the main editing window.
-
Integrated Editor — here you can create your layout by either typing text and using the formatting bar (to change fonts and sizes) or by pasting your own HTML code.
The buttons located at the top of the New Template screen allow you to manage the final steps of your design:
-
Convert to Plain Text — automatically generates a text-only version of the email to ensure compatibility with all email clients.
-
Preview Template — use this to see exactly how your finished email will look to a customer before you finish.
-
Save Template — saves all your work and settings directly to the system.
Working with the Newsletter Editor
There are two primary ways to access the visual builder within the Magento Admin:
-
Via the extension menu: Go to Marketing > Newsletter Popup By Aheadworks > Newsletter Editor.
-
Via Newsletter Templates: Navigate to Marketing > Communication > Newsletter Templates and click the Newsletter Editor button on any existing template.
When you initiate the creation of a new template within the Newsletter Editor, a configuration modal appears to define the core identity of your email campaign.
-
Newsletter Template Name — enter a unique internal name for the template.
-
Newsletter Subject — specify the subject line that recipients will see in their inbox.
-
Template Selector — choose a starting point for your design from the dropdown menu. This allows you to load existing layouts or base your new campaign on a successful previous design.
-
Upload a file (.zip, .html) — provides the option to import external assets.
-
Create new — click this button to proceed to the visual builder with your defined settings.
-
Back to Magento — exits the editor without saving changes, returning you to the standard Magento Admin interface.
The Newsletter Editor provides a side panel for managing global visual parameters, ensuring brand consistency across your template without the need for manual code adjustments in every block.
When an Image is selected in the editor canvas, you can adjust the following attributes to ensure high-precision placement:
-
Dimensions — manually set the Width and Height in pixels to maintain the correct aspect ratio and layout integrity.
-
Margin — define specific spacing around the image for the top, right, bottom, and left sides to achieve the desired white space.
-
Image Alt — enter descriptive alternative text for accessibility and for instances where images are disabled in the recipient's email client.
-
Image Title — provide a title that typically appears when a user hovers over the image.
-
Image Style — apply custom CSS styles or classes directly to the specific image element for advanced design requirements.
-
Select Image — click this button to open the media library or upload new files directly from your device.
Selecting an image on the canvas reveals contextual toolbars for quick adjustments:
-
Alignment Toolbar — use the floating icons at the top of the selected image to set text wrapping and horizontal alignment (Left, Center, Right, or Justify).
-
Link — quickly add a hyperlink to the image
-
Remove — remove the element from the canvas using the dedicated icons.
When you highlight text within the template, a floating contextual toolbar appears immediately above the selection for rapid formatting:
-
Typography Controls — change the font family, adjust the font size, and apply specific hex color codes to the selected text.
-
Styling Options — quickly apply Bold, Italic, or strikethrough effects.
-
Alignment and Lists — set text justification (Left, Center, Right, or Justify) or convert text into bulleted and numbered lists.
-
Advanced Elements — use the integrated icons to insert hyperlinks, add images, or wrap the selection in specific code tags using the Source Code (</>) icon.
Color Scheme tab remains accessible in the sidebar while you edit text, allowing for global style management:
-
Other Font Colors — the sidebar displays a predefined palette.
-
Real-time Updates — clicking a color swatch in the sidebar while text is selected allows you to quickly test different brand colors from your established theme.
-
Palette Consistency — these slots ensure that you are always using the correct, approved brand colors rather than manually entering hex codes every time.
To ensure your design looks professional across all devices, use the Preview tool located in the left-hand sidebar. This feature allows you to see how your template adapts to different screen sizes before you save or send it.
-
Full screen — Displays the newsletter in a standard desktop view, showing the complete layout as it appears on larger monitors.
-
Tablet — Switches the view to simulate how the template renders on a tablet device, helping you check for proper scaling and alignment.
-
Mobile — Adjusts the workspace to a smartphone-sized screen to verify that your content is fully responsive and readable for mobile users.
Send
The Send tab is used to verify how your email looks and functions in a real inbox.
Note: To receive test emails, ensure SMTP is enabled in the Transport field and your email credentials (Username/Password) are correctly entered in Stores > Settings > Configuration > Advanced > System > Mail Sending Settings.
Actions
-
Change info – opens a modal to manage the template's data.
-
Delete template – permanently removes the current template from the system.
-
-