Ecomail

Updating from an earlier version

1. 01Back up the site and test the update on staging when possible.
2. 02Install the new plugin package without deleting the existing ecomail option or WooCommerce data.
3. 03Open Settings -> Ecomail and verify the cached connection status, selected list, checkout behavior, and tracking consent configuration.
4. 04Refresh lists explicitly if the list cache is old.
5. 05Confirm that the token-protected webhook URL configured in Ecomail still matches the URL shown in WordPress.
6. 06Review Initial synchronization. Pending legacy synchronization is migrated to one resumable Action Scheduler job.
7. 07Place test orders through every checkout type used by the store before production rollout.

Saved settings, customer metadata, WooCommerce orders, and order metadata are preserved during the supported upgrade path. A legacy plaintext API key is automatically migrated to authenticated encrypted storage derived from the WordPress installation salts and is never returned to the settings page.

Configuration

Connection

• Enable Ecomail integration: enabled by default so existing stores retain their 2.4.3 behavior. Disabling it blocks outbound Ecomail API calls, checkout integration hooks, browser tracking, webhook processing, and new synchronization starts without deactivating the WordPress plugin. Settings and local diagnostics remain available.
• API key: save the Ecomail API key. It is encrypted in the WordPress database and the field remains blank after saving. Leaving the field blank preserves the current key. If WordPress authentication salts are rotated, enter the API key again so it can be encrypted with the new installation keys.
• App ID: enter the first part of the Ecomail account URL.
• Test Ecomail connection: checks the saved key and updates only the cached connection status.
• Refresh lists: explicitly downloads and caches available contact lists. Merely opening settings never refreshes them.
• Unsaved changes: after editing a setting, use the sticky Save changes or Discard changes controls. Leaving a dirty settings page triggers the browser’s standard warning.

Checkout and contacts

• Subscribe on checkout enables the newsletter/contact flow.
• Show checkbox on checkout displays the configured newsletter opt-out field. Review its wording and default behavior against the store’s legal basis and consent policy.
• The selected checkout preference is stored on the order before deferred Ecomail work. Opting out schedules no contact operation and does not unsubscribe an existing Ecomail contact. Opt-in contact work is idempotent, retries bounded transient failures, and updates a registered customer’s local status only after Ecomail succeeds. Pay-for-order preserves the preference already recorded on the order.
• Update subscriber data sends the selected checkout fields for existing contacts.
• Resubscribe subscriber with new order controls whether a new order may resubscribe a previously unsubscribed contact when the checkout preference permits it.
• List for checkout subscriptions selects the cached Ecomail contact list.
• Skip confirmation disables double opt-in. Enable it only when the store has an appropriate legal basis.
• Trigger autoresponders asks Ecomail to run applicable autoresponders when adding the contact.
• Fields to register controls first name, last name, address, company, phone, and store language. Empty optional values are omitted.
• API Source adds the configured source value to contact payloads. It defaults to woocommerce and uses lowercase ASCII letters, digits, and underscores. Live and historical transfers use the same value; _import and _webhook suffixes are not added automatically.
• My Account subscribe and unsubscribe requests are nonce-protected, recorded as Pending, and processed by WooCommerce Action Scheduler. Transient API failures retry up to five times with bounded backoff. The final local preference changes only after Ecomail succeeds; permanent or exhausted failures restore the previous state.

Orders and storefront tracking

• Enable order tracking queues one idempotent order-scoped transaction job. Repeated classic, Blocks, or pay-for-order events reuse the same generation; transient failures retry up to five times with bounded backoff, and a five-minute watchdog restores missing actions. Successful live transactions are marked as remotely known for later historical synchronization.
• Later WooCommerce status transitions use a separate durable per-order job. Rapid changes coalesce to the latest mapped status, stale actions cannot overwrite newer state, and transaction creation completes before a queued status PUT consumes its retry budget.
• Add tracking code to website loads Ecomail storefront tracking only after marketing consent.
• Enable manual tracking identifies a consented visitor using the WooCommerce billing email, with the WordPress account email as fallback.
• Enable cart tracking sends the server-authoritative WooCommerce cart for abandoned-cart automations.
• Successful checkout queues one durable order-scoped cart-clear event. Replayed checkout events reuse the same generation, transient failures retry with bounded backoff, and a five-minute watchdog restores missing actions without delaying checkout.
• Enable Last view tracking sends the last viewed product for the ECM_LAST_VIEW merge tag.

Tracking uses the WordPress Consent API when available. Without it, both Marketing cookie name and Marketing cookie value must match the consent-management platform. Missing or mismatching consent disables browser tracking.

Webhook

Copy the complete token-protected webhook URL shown in Settings -> Ecomail into the Ecomail list settings. Treat it as a secret. Regenerating the token immediately invalidates the previous URL, so update Ecomail at the same time.

Initial synchronization

The Initial synchronization panel is below the main settings form in Settings -> Ecomail. Progress is stored in WordPress, so the page can be closed while Action Scheduler continues.

• Sync customers sends only registered WooCommerce customers or account holders with a WooCommerce order to the selected contact list. Other WordPress accounts are skipped unless they have an order. Explicitly unsubscribed customers and customers who declined on their latest order are skipped. Guests without accounts are not included in this contact import.
• Sync customers and orders first discovers known Ecomail transactions, then sends customers and missing historical orders belonging to registered customers. Historical guest orders remain outside this import; new guest orders use the live order-tracking flow when enabled.
• Update known orders refreshes transactions already known to Ecomail.
• Retry job resumes a failed job from durable progress.
• Cancel job requests cancellation after the current accepted batch is saved.
• Clear finished job removes only the terminal job history so a new job can start.

Only one durable synchronization job runs per site. The default customer batch is 100, with one existing-contact lookup per customer to protect remote tags; the default transaction batch is 1,000, with a 250-record local database chunk. The server caps batches at 3,000 subscribers, 1,000 transactions, and 500 local records. Larger customer batches may be slowed by API and hosting time limits.

Turning off Enable Ecomail integration pauses an active Initial synchronization job at its exact stage, cursor, counts, and retry deadline without sending another batch. The recovery watchdog resumes that preserved work after the integration is enabled again. Cancellation remains available while synchronization is paused.

Already queued My Account, checkout co