Ecomail

Popis

Ecomail connects a WooCommerce store with an Ecomail account. It can synchronize contacts and transactions, maintain newsletter subscription state, and send consent-aware storefront events for Ecomail automations.

Main features

• Subscribe or update WooCommerce customers in a selected Ecomail contact list.
• Support classic checkout, Checkout Blocks, guest checkout, pay-for-order, and the customer My Account subscription control.
• Send new orders and maintain Ecomail transaction status updates. Transaction features require an eligible Ecomail plan.
• Run resumable customer, historical-order, and known-order synchronization through WooCommerce Action Scheduler.
• Track carts and last-viewed products for automations when the relevant feature and marketing consent are enabled. These features require an eligible Ecomail plan.
• Use a token-protected webhook to keep local subscription status synchronized from Ecomail.
• Preserve existing contact tags during safe single-contact updates and retain legacy wp_order and wp_newsletter automation compatibility.
• Store searchable, redacted API outcomes without request payloads, response bodies, credentials, or customer contact details.
• Provide English source text plus Czech, Slovak, and Polish translations.

Administration and checkout

Loading the Ecomail settings page does not contact Ecomail. Test connection and Refresh lists are explicit administrator actions. Checkout and order creation are not made dependent on a successful Ecomail response.

Podpora

For help, contact support@ecomail.cz or use chat in the Ecomail application. When reporting an API problem, include the timestamp and correlation ID from the redacted API request logs. Never send your API key or token-protected webhook URL.

Requirements and compatibility

• WordPress 7.0 or later; tested through WordPress 7.1.
• PHP 8.2 through PHP 8.5.
• WooCommerce 10.9 or later; tested through WooCommerce 11.0.
• WooCommerce HPOS is supported. Legacy order storage is retained where WooCommerce still supports it.
• WordPress cron and WooCommerce Action Scheduler must be able to run background actions.
• The PHP OpenSSL extension is required for authenticated encryption of the saved API key.
• Single-site WordPress is supported. Multisite has not been validated and is not currently claimed as supported.
• HTTPS is strongly recommended, especially for authenticated administration and storefront tracking.

Updating from an earlier version

1. Back up the site and test the update on staging when possible.
2. Install the new plugin package without deleting the existing ecomail option or WooCommerce data.
3. Open Settings -> Ecomail and verify the cached connection status, selected list, checkout behavior, and tracking consent configuration.
4. Refresh lists explicitly if the list cache is old.
5. Confirm that the token-protected webhook URL configured in Ecomail still matches the URL shown in WordPress.
6. Review Initial synchronization. Pending legacy synchronization is migrated to one resumable Action Scheduler job.
7. Place 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 contact, cart clearing, live transaction, and transaction status jobs are paused in the same way. Their retry attempt, deadline, and order or customer state remain unchanged until the integration is enabled again.

Initial customer sync checks existing Ecomail tags before updating a contact and adds only the integration tags. A new registered customer without an order or a known newsletter opt-in is imported as unsubscribed. Existing Ecomail subscription states are preserved.

Historical bulk imports do not trigger Ecomail automations based on the Makes an order trigger.

Tags and contact enrichment

Safe single-contact updates fetch the existing Ecomail subscriber and merge tags before sending:

• wp identifies a contact synchronized by this integration.
• wp_order identifies a contact with a WooCommerce order.
• wp_newsletter identifies a known newsletter opt-in. Initial sync does not infer historical opt-in.
• An explicit unsubscribe removes wp_newsletter and the older woocommerce_newsletter tag if present.
• Unrelated existing tags are preserved.
• If an existing subscriber cannot be read safely, live updates omit the tags field; initial sync retries before sending the batch.
• Store language is optional and is sent as the woocommerce_language custom field.

Administrators can see the locally recorded newsletter status and filter it in WordPress Users. This local value can be unknown or lag behind Ecomail when webhooks are not configured. Guest buyers have no WordPress user row.

Privacy

Depending on enabled features, the plugin can send contact identity and selected billing fields, newsletter preference, WooCommerce transaction details, cart contents, and last-viewed product data to Ecomail. Configure only the data needed for the store’s stated purpose and document the processing in the store privacy notice.

Behavioral tracking fails closed without marketing consent. Cart and product events use an email known to WooCommerce for the current customer; an ecmid campaign parameter is not used as the event email. The browser tracker identifies visitors through its separate consent-aware path.

The local API request table stores bounded, redacted outcomes for 7 days by default, up to 1,000 rows. It does not store request payloads, response bodies, API credentials, webhook tokens, or customer contact details. Logs are preserved on uninstall unless Delete API request logs on uninstall is explicitly enabled. Settings, including the encrypted API key, and cached contact lists are preserved unless Delete Ecomail settings on uninstall is enabled. These options are independent; neither removes WooCommerce customers or orders.

Uninstall never deletes WooCommerce customers, orders, products, addresses, or other business data. It removes generated tokens and transient synchronization state. By default, Ecomail settings remain available for a later reinstall; enabling Delete Ecomail settings on uninstall removes them.

Troubleshooting

1. Save the API key, then run Test Ecomail connection. A blank API-key field after saving is expected. If the connection stops working immediately after WordPress salts were rotated, enter and save the API key again.
2. Use Refresh lists if a contact list is missing or stale.
3. Open WooCommerce -> Status -> Scheduled Actions and confirm Action Scheduler is running. Check the site’s WP-Cron or real system cron if a job does not advance.
4. Open API request logs in Settings -> Ecomail. Filter by result, method, endpoint, date, order, job, or correlation ID.
5. Retry a failed synchronization from its stored progress. If hosting limits are involved, clear the finished job, reduce batch sizes, and start a new job.
6. If tracking does not run, verify that the tracking feature is enabled and that WordPress Consent API marketing consent or both fallback cookie values match.
7. If a webhook is rejected, copy the currently displayed URL exactly. Regenerate only if the URL may have leaked, then update Ecomail immediately.
8. If checkout or an order succeeds but Ecomail data is missing, use the redacted logs and Action Scheduler status. Ecomail failures are isolated from WooCommerce checkout success.