Advanced Newsletter Suite for Magento 2 - installation and configuration guide

Document purpose

This document describes the installation and configuration of the magento-2-package-advanced-newsletter-suite package. It is a complete newsletter and email marketing package for Magento 2, covering audiences, capture, campaigns, content, sending, tracking, an operational panel, and frontend sign-up points.

Prerequisites

Before implementation, prepare:

• Magento Open Source 2.4.x,
• Composer,
• CLI access to bin/magento,
• a Magento administrator account,
• SMTP access credentials,
• configured Magento cron,
• readiness to run queue consumers,
• a test environment to verify subscriptions, campaigns, and sends.

What the package installs

The package includes:

• Kowal_MarketingCore,
• Kowal_EmailTransport,
• Kowal_EmailSmtp,
• Kowal_EmailEvents,
• Kowal_EmailTemplateStudio,
• Kowal_NewsletterAudience,
• Kowal_NewsletterCapture,
• Kowal_NewsletterCampaigns,
• Kowal_NewsletterConsole,
• Kowal_NewsletterFrontend.

This is the highest level of aggregation in the ecosystem of email marketing modules for Magento.

Installation

1. Installing the Composer package

composer config repositories.kowal.package.advanced.newsletter.suite vcs https://github.com/kowalco/package-advanced-newsletter-suitecomposer config repositories.kowal.module.email.events vcs https://github.com/kowalco/module-email-eventscomposer config repositories.kowal.module.email.smtp vcs https://github.com/kowalco/module-email-smtpcomposer config repositories.kowal.module.email.template.studio vcs https://github.com/kowalco/module-email-template-studiocomposer config repositories.kowal.module.email.transport vcs https://github.com/kowalco/module-email-transportcomposer config repositories.kowal.module.marketing.core vcs https://github.com/kowalco/module-marketing-corecomposer config repositories.kowal.module.newsletter.audience vcs https://github.com/kowalco/module-newsletter-audiencecomposer config repositories.kowal.module.newsletter.campaigns vcs https://github.com/kowalco/module-newsletter-campaignscomposer config repositories.kowal.module.newsletter.capture vcs https://github.com/kowalco/module-newsletter-capturecomposer config repositories.kowal.module.newsletter.console vcs https://github.com/kowalco/module-newsletter-consolecomposer config repositories.kowal.module.newsletter.frontend vcs https://github.com/kowalco/module-newsletter-frontendcomposer config --global --auth github-oauth.github.com composer require kowal/package-advanced-newsletter-suite

2. Enabling modules in Magento

bin/magento module:enable \ Kowal_MarketingCore \ Kowal_EmailTransport \ Kowal_EmailSmtp \ Kowal_EmailEvents \ Kowal_EmailTemplateStudio \ Kowal_NewsletterAudience \ Kowal_NewsletterCapture \ Kowal_NewsletterCampaigns \ Kowal_NewsletterConsole \ Kowal_NewsletterFrontendbin/magento setup:upgradebin/magento cache:flush

In production mode, additionally run:

bin/magento setup:di:compilebin/magento setup:static-content:deploy -f

Configuration

1. Admin section

The basic configuration should be available in:

Kowal / Email Marketing

According to the specification, the expected setting groups are:

• general,
• transport,
• smtp,
• campaigns,
• double_opt_in,
• events.

2. Sending configuration

First, configure the delivery foundation:

• module activity,
• default transport type,
• send logging,
• SMTP account or accounts,
• message routing,
• fallback for backup accounts, if used.

Implementing the full package still requires an efficient SMTP and transport layer.

3. Audience and sign-up configuration

Next, confirm the configuration of the audience layer:

• integration with newsletter_subscriber,
• mailing lists,
• segments,
• subscription statuses,
• additional subscriber metadata,
• acquisition sources,
• marketing consents.

Also configure the subscription process:

• forms and sign-up points,
• double opt-in,
• confirmation message template,
• confirmation token expiration time.

4. Campaign configuration

In the campaigns section, set:

• batch_size,
• max_retry_count,
• send_rate_limit_per_run,
• watchdog_timeout_minutes.

The package supports:

• campaign definition,
• scheduling,
• recipient queue,
• send batching,
• campaign execution history,
• test sends.

5. Template Studio configuration

If the implementation includes work on newsletter content, configure EmailTemplateStudio according to the MVP scope:

• working with native Magento newsletter templates,
• selecting product layouts,
• saving the generated section to the native template,
• importing ready content into a campaign.

6. Email event configuration

In the events section, configure:

• event processing,
• payload retention,
• the policy for accepting duplicate events from providers.

The EmailEvents layer is responsible for delivery process observability and linking events to transport logs and campaigns.

7. Admin panel and frontend configuration

The full package includes:

• Kowal_NewsletterConsole as the operational panel,
• Kowal_NewsletterFrontend as the layer for frontend forms and sign-up widgets.

After installation, verify:

• dashboard availability,
• shortcuts to configuration and operational modules,
• the view of recent errors and sends,
• the presence of sign-up forms on the store frontend.

Cron and queue consumers

The full package requires asynchronous processing to be running.

1. Magento cron

bin/magento cron:install

Cron should be responsible for:

• campaign scheduling,
• task recovery,
• operational watchdog.

2. Queue consumers

Queue consumers should be responsible for the actual processing of sending batches. Consumer names should be taken from the current etc/queue_consumer.xml files of the deployed modules.

In the production environment, make sure to provide:

• running consumers in the background,
• autostart after server restart,
• failure monitoring,
• error logging.

Post-installation steps

After deployment, complete the full checklist:

1. Configure and test the SMTP account.
2. Verify message routing.
3. Check subscriber sign-up and double opt-in.
4. Confirm compatibility with the native Magento newsletter.
5. Create a test list or segment.
6. Prepare a test campaign.
7. Perform a test send.
8. Check campaign scheduling via cron.
9. Verify queue processing by consumers.
10. Confirm logging of email logs and events.
11. Check the admin dashboard.
12. Verify frontend forms and sign-up widgets.

Acceptance test after deployment

The package is correctly implemented if:

• the modules install correctly in Magento 2.4.x,
• SMTP sending works through accounts and routing,
• subscriber sign-up remains compatible with the native Magento newsletter,
• a campaign is scheduled by cron and processed by a queue consumer,
• delivery statuses update logs and email events,
• the admin panel shows basic operational data,
• frontend sign-up points work correctly,
• after disabling the modules, the base Magento_Newsletter mechanism can still operate.

Implementation notes

• The full package is best implemented together with a proven SMTP and tracking configuration.
• Extended data should be stored in dedicated tables, without duplicating the native newsletter_subscriber table.
• The implementation operational documentation should additionally include the procedure for handling queues, webhooks, and regression tests of the admin configuration.

Amazon SES - account setup and configuration for sending integration

Document purpose

This document describes how to prepare an AWS account and the Amazon SES service so that sending integration with this project's modules can be implemented.

The guide covers:

• creating an AWS account,
• launching Amazon SES,
• verifying the domain and sender,
• leaving the sandbox,
• preparing credentials,
• two Magento integration variants:
  • via Amazon SES API,
  • via Amazon SES SMTP.

Important note for this project

There are two integration paths with Amazon SES available in the project code:

1. SES API in Kowal_EmailTransport with the ses transport type.
2. SES SMTP in Kowal_EmailSmtp with the smtp transport type.

This means it is worth preparing the AWS and SES account once, but the final way it is connected to Magento depends on the chosen implementation variant.

Initial assumptions

Before you start, prepare:

• a domain from which messages will be sent, for example example.com,
• access to the DNS of that domain,
• a sender address, for example newsletter@example.com,
• a payment card or an active billing method in AWS,
• a decision on which region SES will operate in, for example eu-central-1 or us-east-1.

1. Creating an AWS account

1. Go to the AWS panel: https://aws.amazon.com/
2. Create an AWS account.
3. Enable MFA for the root account.
4. Do not use root account access keys for application integration.

For Magento integration, prepare a separate IAM user or separate SMTP credentials, depending on the selected variant.

2. Launching Amazon SES

1. Log in to AWS Console.
2. Open the Amazon Simple Email Service service.
3. Select the region where you want to run sending.

This is important because in SES the region has operational significance:

• sender identities are maintained per region,
• sandbox/production access status applies per region,
• Magento configuration data must point to the same region,
• SMTP credentials in SES are unique per region.

If the store operates internationally, it is best to determine the target region for a given market or the entire organization right away and stick to it consistently.

3. Verifying the domain or sender address

The best practice for a store is to verify the entire domain, not just a single email address.

Recommended variant

Verify the domain, for example example.com.

This gives you:

• the ability to send from multiple addresses on that domain,
• an easier path to production sending,
• better preparation for campaigns, transactional messages, and multiple senders,
• easier support for multiple stores, languages, and brands in one ecosystem.

Steps

1. In SES, go to Identities.
2. Select Create identity.
3. Select the Domain type.
4. Enter the sending domain.
5. Enable Easy DKIM unless you have a reason to use your own DKIM keys.
6. Add the DNS records indicated by AWS to your DNS zone.
7. Wait for the Verified status.

Minimum DNS scope

In practice, you will need at least:

• SES verification records,
• DKIM records,
• optionally a record for custom MAIL FROM.

4. Leaving the SES sandbox

A new SES account usually starts in sandbox mode.

Among other things, this means that:

• you can send only from verified identities,
• recipients must also be verified,
• you cannot perform normal production sending to store customers.

Steps

1. In SES, open the Account dashboard or the initial configuration screen.
2. Select the Request production access option.
3. Fill out the form according to the system purpose:
   • transactional,
   • marketing,
   • newsletter,
   • e-commerce communications.
4. Describe that sending will be performed from your own Magento for an online store.
5. Submit the request.

Before sending the request, it is a good idea to have the domain already verified. This usually speeds up approval.

5. Deliverability configuration

This is not the mandatory minimum for the first test, but it is strongly recommended before production.

DKIM

If you use Easy DKIM, SES signs messages automatically after correct DNS configuration.

Custom MAIL FROM

If you want to improve control over the technical sender and deliverability:

1. Open the verified domain in SES.
2. Configure the Custom MAIL FROM domain, for example mail.example.com.
3. Add to DNS:
   • an MX record,
   • an SPF/TXT record for MAIL FROM.

This is especially sensible for stores that run regular email marketing and want to reduce sender reputation issues.

6. Variant A - integration via Amazon SES API

This variant uses the ses transport type available in Kowal_EmailTransport.

When to choose this variant

Choose SES API if:

• you want to use Amazon SES directly as the provider,
• you want to maintain a ses transport account,
• you want to route messages through Kowal_EmailTransport.

6.1. Creating an IAM user for sending

Do not use the root account.

Prepare a separate IAM user, for example:

• magento-ses-sender

Then assign it a policy with the minimum permissions required for sending.

Example minimum policy

{ 'Version': '2012-10-17', 'Statement': [ { 'Effect': 'Allow', 'Action': [ 'ses:SendEmail', 'ses:SendRawEmail' ], 'Resource': '*' } ]}

If you want, you can extend it with read access to limits or statistics, but for sending itself the above scope is the starting point.

6.2. Creating an Access Key and Secret Key

1. Open IAM.
2. Go to Users.
3. Open the prepared user.
4. Go to the Security credentials tab.
5. In the Access keys section, select Create access key.
6. Save:
   • Access Key ID
   • Secret Access Key

You will see the secret only once. If you lose it, you must create a new key.

6.3. Data required in Magento for the API variant

For the ses transport account in Magento, prepare:

• provider_region, for example eu-central-1,
• provider_api_key,
• provider_api_secret,
• sender_name,
• sender_email,
• reply_to_email optionally,
• store_id if the account is to work only for a specific store view.

6.4. Mapping to the Magento panel

In Kowal / Email Marketing:

1. Add a new transport account.
2. Set:
   • Transport Type = Amazon SES,
   • Region = SES region,
   • Access Key = IAM key,
   • Secret Key = IAM secret.
3. Save the account.
4. Link the account to message routing.
5. Perform a sending test from the transport account level.

7. Variant B - integration via Amazon SES SMTP

This variant uses Kowal_EmailSmtp.

When to choose this variant

Choose SES SMTP if:

• you want to implement Amazon SES as the SMTP source,
• you use the Advance Email Delivery package,
• you want to keep a simpler integration model on the Magento side.

7.1. Creating SMTP credentials in SES

1. Open Amazon SES.
2. Go to SMTP settings.
3. Select Create SMTP credentials.
4. AWS will guide you through creating an IAM user for SMTP.
5. Save:
   • SMTP username
   • SMTP password

These are not standard AWS keys. They are separate SMTP credentials for SES.

7.2. SMTP endpoint

For SES, use a host in the format:

email-smtp..amazonaws.com

Example:

email-smtp.eu-central-1.amazonaws.com

7.3. Port and encryption

The most commonly used settings:

• port 587 + STARTTLS,
• or port 465 + TLS Wrapper / SSL.

In practice, for Magento the safest starting point is:

• host: email-smtp..amazonaws.com
• port: 587
• security: STARTTLS

7.4. Data required in Magento for the SMTP variant

Prepare:

• SMTP host,
• port,
• encryption type,
• SMTP login,
• SMTP password,
• a sender address consistent with the verified identity in SES.

7.5. Mapping to the Magento panel

In Kowal / Email Marketing:

1. In the smtp section, set globally:
   • enabled = Yes,
   • host = SES endpoint,
   • port = 587,
   • username = SMTP username,
   • password = SMTP password,
   • connection_security = STARTTLS,
   • test_recipient_email = test address.
2. Save the configuration.
3. Perform Send Test Email.

If you use multiple accounts or multiple store views, you can also configure a separate smtp transport account with dedicated connection data.

8. What to choose in this project

Choose SES API if:

• you want to use ses transport accounts,
• you want to route sending per account and provider,
• you want to develop transport without relying entirely on the SMTP layer.

Choose SES SMTP if:

• you want a faster initial implementation,
• you want to treat SES as an external SMTP server,
• you are mainly implementing the delivery package based on Kowal_EmailSmtp.

9. Minimum checklist before the sending test

Before the first test, confirm:

1. The AWS account exists and has active billing.
2. The SES region has been selected.
3. The domain or sender address has the Verified status.
4. The SES account has production access, or you are testing only under sandbox conditions.
5. DKIM is configured.
6. Magento has correct sender data.
7. The integration variant has been selected:
   • API,
   • or SMTP.
8. Credentials are stored securely.
9. A test has been sent and message delivery has been confirmed.

10. Most common errors

The account is still in sandbox mode

Symptom:

• the message is not sent to normal recipients.

Cause:

• no production access.

The domain is not verified

Symptom:

• sender error or rejected send.

Cause:

• no verified identity for the domain or sender address.

Wrong region

Symptom:

• the data looks correct, but sending still does not work.

Cause:

• the identity is verified in a different region than the one used by the integration.

Confusing API keys with SMTP credentials

Symptom:

• SMTP login does not work.

Cause:

• IAM keys were entered for SMTP instead of SMTP username and SMTP password.

Using the root account

Symptom:

• no security separation and more difficult credential rotation.

Cause:

• integration is based on root data instead of a separate IAM user or separate SMTP credentials.

11. Links to official AWS documentation

• Set up your SES account: https://docs.aws.amazon.com/ses/latest/dg/setting-up.html
• Creating and verifying identities: https://docs.aws.amazon.com/ses/latest/dg/creating-identities.html
• Verified identities: https://docs.aws.amazon.com/ses/latest/dg/verify-addresses-and-domains.html
• Request production access: https://docs.aws.amazon.com/ses/latest/dg/request-production-access.html
• SMTP credentials: https://docs.aws.amazon.com/ses/latest/dg/smtp-credentials.html
• SMTP endpoint connection: https://docs.aws.amazon.com/ses/latest/dg/smtp-connect.html
• Custom MAIL FROM: https://docs.aws.amazon.com/ses/latest/dg/mail-from.html
• SES regions: https://docs.aws.amazon.com/ses/latest/dg/regions.html
• SES credentials overview: https://docs.aws.amazon.com/ses/latest/dg/send-email-concepts-credentials.html
• IAM access keys: https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_access-keys.html

12. Data that must be provided for implementation

At the end, the person setting up SES should provide exactly this set for implementation:

For the SES API variant

• SES region,
• verified domain,
• access key,
• secret key,
• sender address,
• reply-to, if it is to be different,
• information on whether the account should work globally or per store view.

For the SES SMTP variant

• SES region,
• SMTP host,
• port,
• security mode,
• SMTP username,
• SMTP password,
• sender address,
• test address for verification.