Toweringmedia Extension Docs

User Tools

Site Tools

You are here: start » magento2 » extensions » magento-2-constant-contact
magento2:extensions:magento-2-constant-contact

Differences

This shows you the differences between two versions of the page.

Link to this comparison view

magento2:extensions:magento-2-constant-contact [2026/08/20 23:53] – created - external edit 127.0.0.1magento2:extensions:magento-2-constant-contact [2026/08/24 19:43] (current) – swatwik
Line 1: Line 1:
-====== Toweringmedia Constant Contact (Magento 2) User Guide ======+====== Toweringmedia Constant Contact Extension for Magento 2 ======
  
-===== Related overview =====+===== Extension Overview =====
  
-For a shopper-friendly overview of features and setup, see the [[https://toweringmedia.com/magento-2-constant-contact-user-guide|Magento 2 Constant Contact User Guide - Sync Customers & Subscribers]] on the storefront. This wiki page remains the full technical documentation.+The Toweringmedia Constant Contact Extension connects Magento 2 customers and newsletter subscribers with Constant Contact through secure, bidirectional synchronization. It uses OAuth 2.0, queue-based outbound processing, scheduled inbound polling, and configurable conflict resolution to keep subscription data synchronized reliably without slowing Magento operations.
  
-===== Extension context =====+===== Product Information =====
  
-This is a Toweringmedia Magento 2 extension guide for the current admin extension catalog.+**Product Name:** [[https://toweringmedia.com/toweringmedia-constant-contact-magento-2|Toweringmedia Constant Contact Extension for Magento 2]]
  
-===== Product page =====+**Support & Updates:** 12 months included
  
-  * [[https://toweringmedia.com/toweringmedia-constant-contact-magento-2|Toweringmedia Constant Contact (Magento 2)]] (SKU ''tm-constant-contact'')+===== Key Features =====
  
-===== Overview =====+  * Bidirectional synchronization between Magento customers, newsletter subscribers, and Constant Contact 
 +  * Secure Constant Contact API v3 integration using OAuth 2.0 
 +  * Database-backed queue for reliable outbound synchronization 
 +  * Scheduled inbound contact polling with synchronization checkpoints 
 +  * Magento Wins, Constant Contact Wins, and Newest Wins conflict-resolution options 
 +  * Automatic retry with exponential backoff for temporary API failures 
 +  * Loop prevention and idempotent processing to reduce duplicate synchronization 
 +  * Encrypted storage of OAuth access and refresh tokens 
 +  * Magento Admin controls for connecting, disconnecting, testing, and monitoring synchronization 
 +  * Manual synchronization and dry-run testing through Magento CLI commands
  
-This extension connects Magento 2 to Constant Contact using the Constant Contact API v3. Customers and newsletter subscribers are pushed to your Constant Contact account through a queued sync so that list membership stays current without blocking storefront or admin actions. Authentication uses OAuth. +===== Installation =====
- +
-===== What this extension does =====+
  
-  * Syncs Magento customers and newsletter subscribers to Constant Contact via API v3. +Please refer to the installation guide in the following article: [[https://toweringmedia.com/installation|https://toweringmedia.com/installation]]
-  * OAuth-based connection with client ID and client secret. +
-  * Queued sync so contact updates do not block checkout or admin saves. +
-  * Sync logs for troubleshooting failed or pending contact pushes. +
-  * Configurable logging level.+
  
 ===== Requirements ===== ===== Requirements =====
  
-  * Magento 2.4.x (Open Source or Adobe Commerce). +Before configuring the extension, ensure the following requirements are available:
-  * PHP: ^8.1 (as declared by the published package). +
-  * A current Toweringmedia license and Composer credentials for ''https://composer.toweringmedia.com/''. +
-  * A Constant Contact account with API access, and an application registered there to obtain the OAuth client ID and client secret.+
  
-===== Installation =====+  * A supported Magento 2 installation 
 +  * An active Constant Contact account 
 +  * A Constant Contact developer application with an API Key and Client Secret 
 +  * The exact Magento OAuth callback URL registered in the Constant Contact developer portal 
 +  * HTTPS enabled for the Magento Admin URL 
 +  * Magento cron configured and running correctly 
 +  * Constant Contact list membership IDs for synchronization 
 +  * Magento Admin access for extension configuration 
 +  * Outbound server access to the Constant Contact API endpoints
  
-Install and validate in a staging environment before production rollout.+===== Admin Configuration =====
  
-<code bash> +After installing and enabling the extension, go to: 
-cd /path/to/magento + 
-composer require toweringmedia/module-constant-contact+**Magento Admin > Stores > Configuration > Customers > Constant Contact (Towering Media)** 
 + 
 +==== General Settings ==== 
 + 
 +  * Enable or disable the Constant Contact integration. 
 +  * Enable the required outbound and inbound synchronization options. 
 +  * Select the appropriate website or store-view scope before saving configuration values. 
 + 
 +==== OAuth Configuration ==== 
 + 
 +Enter the credentials generated from your Constant Contact developer application: 
 + 
 +  * API Key / Client ID 
 +  * Client Secret 
 +  * Redirect URI Override - leave empty to use the automatically generated Magento callback URL, or enter the exact registered callback URL when required. 
 + 
 +The default callback URL follows this format:
  
-bin/magento module:enable Toweringmedia_ConstantContact +<code> 
-bin/magento setup:upgrade +https://your-domain.com/{admin_path}/constantcontact/oauth/callback
-bin/magento setup:di:compile +
-bin/magento setup:static-content:deploy -f +
-bin/magento cache:flush+
 </code> </code>
  
-Currently published versions at the time of writing:+The callback URL configured in Magento must exactly match the URL registered in the Constant Contact developer portal.
  
-  * ''toweringmedia/module-constant-contact'' — 1.0.0+==== Connect Constant Contact ====
  
-Toweringmedia packages are served from the licensed Composer repository ''https://composer.toweringmedia.com/''. If Composer reports that the package could not be found, your credentials are missing or the license does not cover this package yet. Retrieve your keys from **My Account** on toweringmedia.com, or contact [[mailto:support@toweringmedia.com|support@toweringmedia.com]].+After saving the OAuth credentials:
  
-General installation notes that apply to every Toweringmedia extension are in the [[https://toweringmedia.com/installation|installation guide]].+  - Click **Connect**. 
 +  - Sign in to the required Constant Contact account. 
 +  - Approve the requested permissions. 
 +  - Constant Contact redirects back to Magento Admin. 
 +  - Confirm that the connection status shows as connected.
  
-===== Configuration =====+Access and refresh tokens are stored using Magento's encryption service.
  
-  * Stores > Configuration > Towering Media > **Constant Contact (Towering Media)** (config section ''toweringmedia_constantcontact''). +==== Synchronization Settings ====
-  * Groups: ''general'' (enable, logging level) and ''oauth'' (client ID, client secret). +
-  * Admin screens: Marketing > Constant Contact > **Sync Queue**, **Sync Logs**, and **Configuration**.+
  
-===== Basic usage and what to expect =====+Configure the following synchronization options:
  
-  - Register an application in Constant Contact and copy the client ID and client secret into the OAuth group, then complete the OAuth authorization. +  * Magento customer synchronization 
-  - Enable the module, then watch Marketing > Constant Contact > Sync Queue to confirm contacts are being picked up. +  * Magento newsletter-subscriber synchronization 
-  - Check Sync Logs if contacts stay queued or report an error.+  * Outbound queue processing 
 +  * Scheduled inbound contact polling 
 +  * Constant Contact list membership IDs 
 +  * Synchronization batch or processing settings, where available
  
-===== Validation checklist =====+==== Conflict Resolution ====
  
-  * ''bin/magento module:status'' shows the module(s) as enabled. +Select how subscription conflicts between Magento and Constant Contact should be handled: 
-  * Extension configuration saves without errors in Admin. + 
-  * The admin screens listed above are reachable and load without error. +  * **Magento Wins** - Magento is treated as the preferred source. 
-  * Expected storefront/admin behavior is present after a cache flush. +  * **Constant Contact Wins** - Constant Contact membership is treated as the preferred source. 
-  * No critical PHP/JS errors appear in ''var/log/'' during the primary test flow.+  * **Newest Wins** - The most recently updated state is used. 
 + 
 +Choose this setting carefully according to the store's subscription-management workflow. 
 + 
 +==== Test the Connection ==== 
 + 
 +Click **API Smoke Test** to confirm that: 
 + 
 +  * OAuth authentication is valid. 
 +  * Magento can communicate with Constant Contact API v3. 
 +  * The configured account and tokens are working. 
 + 
 +==== Disconnect ==== 
 + 
 +Use **Disconnect** when you need to remove the current Constant Contact authorization. After disconnecting, automatic synchronization cannot continue until the account is connected again. 
 + 
 +===== Basic Usage and What to Expect ===== 
 + 
 +After the Constant Contact account is connected and synchronization settings are saved, the extension works automatically through Magento observers, the synchronization queue, and scheduled cron jobs. 
 + 
 +==== Normal Synchronization Flow ==== 
 + 
 +  * A Magento customer or newsletter-subscriber record is created or updated. 
 +  * The extension adds a synchronization request to its database-backed outbound queue. 
 +  * Magento cron or the synchronization CLI processes the queued request and sends the update to Constant Contact. 
 +  * The scheduled inbound process retrieves Constant Contact contact membership changes using synchronization checkpoints. 
 +  * Magento applies the configured conflict-resolution rule and records the result in the synchronization logs. 
 + 
 +==== What to Expect ==== 
 + 
 +  * Synchronization is asynchronous. Changes may not appear in Constant Contact or Magento immediately because they are processed by cron. 
 +  * Reliable Magento cron execution is required for automatic outbound queue processing and inbound polling. 
 +  * Temporary API failures and rate-limit responses are retried automatically using exponential backoff. 
 +  * Permanent errors are marked as failed and remain available for administrative review. 
 +  * Idempotent processing and synchronization hashes help prevent duplicate work and update loops. 
 +  * The selected conflict-resolution mode determines which subscription state is kept when Magento and Constant Contact disagree. 
 +  * Initial processing or large contact lists may take longer and may require batch-size or cron-frequency adjustments. 
 + 
 +==== Monitoring Synchronization ==== 
 + 
 +Use the read-only synchronization queue and log grids in Magento Admin to review pending, processing, retry, completed, or failed operations. If a change has not synchronized, first confirm that cron is running, the OAuth connection is active, and the configured Constant Contact list membership IDs are correct. 
 + 
 +==== Manual and Dry-Run Processing ==== 
 + 
 +Administrators can use the Magento CLI synchronization command for controlled manual processing. Dry-run mode can be used to validate the synchronization flow without applying live changes. 
 + 
 +<code bash> 
 +php bin/magento toweringmedia:constantcontact:sync --dry-run 
 +</code> 
 + 
 +==== Important Limitations ==== 
 + 
 +  * Inbound synchronization primarily reconciles Magento newsletter subscription status. Customer information is updated only where supported and linked by the integration. 
 +  * The extension uses scheduled polling rather than Constant Contact webhooks. 
 +  * Campaign sending, journeys, ecommerce catalog synchronization, and storefront signup widgets are not included. 
 +  * Disconnecting the Constant Contact account stops synchronization until the account is authorized again. 
 + 
 +===== Validation Checklist ===== 
 + 
 +After configuration, complete these checks before relying on automatic synchronization: 
 + 
 +  * Confirm that the ''Toweringmedia_ConstantContact'' module is enabled. 
 +  * Confirm that the extension settings are saved under the intended website or store scope. 
 +  * Verify that the OAuth callback URL exactly matches the URL configured in the Constant Contact developer application. 
 +  * Confirm that Magento Admin shows the Constant Contact account as connected. 
 +  * Run **API Smoke Test** and confirm that it completes successfully. 
 +  * Confirm that Magento cron is installed and running reliably. 
 +  * Test outbound synchronization by updating a Magento customer or newsletter subscriber, then verify that the queue item is processed and the Constant Contact list membership is updated. 
 +  * Test inbound synchronization by changing a contact's Constant Contact list membership, then verify that Magento reconciles the newsletter subscription status after the next polling cycle. 
 +  * Verify that the selected conflict-resolution mode produces the expected result when Magento and Constant Contact contain different subscription states. 
 +  * Review the synchronization queue and log grids for unexpected failures or a growing retry backlog. 
 +  * Run ''php bin/magento toweringmedia:constantcontact:sync --dry-run'' and confirm that it completes without unexpected errors. 
 +  * Confirm that application logs do not expose OAuth access tokens, refresh tokens, or the Client Secret.
  
 ===== Troubleshooting ===== ===== Troubleshooting =====
  
-  * **Composer cannot find the package**: confirm the ''https://composer.toweringmedia.com/'' repository and your credentials are present in ''auth.json'', and that your license covers this package. +Use the following checks when synchronization or authorization does not work as expected. 
-  * **Feature not visible**: verify module status, flush cache, and redeploy static content. + 
-  * **Admin setting not applying**: clear cache and confirm the config scope (default / website / store view). +==== Constant Contact Does Not Connect ==== 
-  * **Unexpected behavior**: retest with only the required related modules enabled.+ 
 +  * Confirm that the API Key / Client ID and Client Secret are correct. 
 +  * Verify that the callback URL in Magento exactly matches the redirect URI registered in the Constant Contact developer application, including the protocol, domain, and Magento Admin path. 
 +  * Confirm that the Magento Admin URL uses HTTPS, save the configuration, and try **Connect** again. 
 + 
 +==== API Smoke Test Fails ==== 
 + 
 +  * Confirm that the account still shows as connected and that the configured Constant Contact account is active. 
 +  * Disconnect and reconnect the account if the authorization has expired or been revoked. 
 +  * Confirm that the Magento server can make outbound HTTPS requests to Constant Contact API endpoints. 
 + 
 +==== Magento Changes Are Not Reaching Constant Contact ==== 
 + 
 +  * Confirm that customer or newsletter-subscriber synchronization is enabled for the correct configuration scope. 
 +  * Verify that Magento cron is running and processing the outbound queue. 
 +  * Review the synchronization queue and logs for pending, retry, or failed items. 
 +  * Run ''php bin/magento toweringmedia:constantcontact:sync --dry-run'' to check the synchronization flow without applying live changes. 
 + 
 +==== Constant Contact Changes Are Not Appearing in Magento ==== 
 + 
 +  * Confirm that inbound synchronization is enabled and that the correct Constant Contact list membership IDs are configured. 
 +  * Allow time for the next scheduled polling cycle; inbound changes are not received through webhooks. 
 +  * Confirm that cron is running and review the synchronization logs for polling or checkpoint errors. 
 +  * Remember that inbound synchronization primarily reconciles newsletter subscription status; customer data is updated only where supported and linked. 
 + 
 +==== Items Remain in Retry or Failed Status ==== 
 + 
 +  * Temporary rate-limit and server errors are retried automatically with exponential backoff, so processing may be delayed during an API outage. 
 +  * Permanent API errors are marked as failed. Review the logged error, correct invalid configuration or contact data, and process the synchronization again. 
 +  * If the retry backlog continues to grow, confirm API availability, OAuth status, cron frequency, and processing settings. 
 + 
 +==== Subscription Status Changes Unexpectedly ==== 
 + 
 +  * Review the selected Magento Wins, Constant Contact Wins, or Newest Wins conflict-resolution mode. 
 +  * Confirm which system should be the preferred source for subscription changes, then save the appropriate mode at the correct configuration scope. 
 +  * Review synchronization timestamps and logs to determine which update was applied. 
 + 
 +==== Before Contacting Support ==== 
 + 
 +  * Record the Magento version, extension version, affected store or website scope, and approximate time of the issue. 
 +  * Include the relevant queue status and sanitized synchronization-log message. 
 +  * Never share OAuth access tokens, refresh tokens, authorization codes, or the Client Secret in screenshots or support messages.
  
 ===== Support ===== ===== Support =====
Line 89: Line 228:
 ===== Related Magento 2 docs ===== ===== Related Magento 2 docs =====
  
-  * [[magento2:extensions:start|Magento 2 extension index]] +  * [[https://toweringmedia.com/pub/docs/doku.php?id=magento2:extensions:start|Magento 2 extension index]] 
-  * [[start|Global docs home]] +  * [[https://toweringmedia.com/pub/docs/doku.php?id=magento2:extensions:start|Global docs home]]
magento2/extensions/magento-2-constant-contact.txt · Last modified: by swatwik