=== Sitebix to EmailOctopus ===
Contributors: sitebix
Donate link: https://sitebix.com
Tags: email, emailoctopus, marketing, elementor, webhook
Requires at least: 6.2
Tested up to: 7.1
Requires PHP: 7.4
Stable tag: 1.0.1
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

Sync WordPress users and forms to EmailOctopus lists with mapping profiles, webhooks, bulk sync, and an activity log.

== Description ==

Sitebix to EmailOctopus connects your site to [EmailOctopus](https://emailoctopus.com/) API v2:

* **Connection** — API key (encrypted in the database or via `wp-config.php` constant), list picker, default contact status (`subscribed` vs `pending` for double opt-in), connection test.
* **Sources** — Multiple named profiles with field mapping (source keys → EmailOctopus field tags), static tags, and optional dynamic tags from one payload field.
* **WordPress user sync** — Role filters, comparison against list contacts (paginated API), batched upserts via Action Scheduler when available, otherwise WP-Cron.
* **Elementor Pro** — Native “Sitebix → EmailOctopus” form action after submit (mapping profile selector).
* **Webhook** — REST endpoint `POST /wp-json/sitebix-weo/v1/webhook/{source_id}` with shared secret (`?secret=` or `X-Sitebix-WEO-Secret`). Optional IP allowlist. First-hit “hold until mapped” workflow with sample payload and replay.
* **Activity log** — Custom database table; filterable/paginated admin log (created, updated, skipped, webhook held, errors, bulk sync).

No Composer dependencies. Rate limits (429) are handled with retries/backoff.

**Developer:** [K. Young](https://profiles.wordpress.org/sitebix/) · **Brand:** [Sitebix](https://sitebix.com) · **Support:** support@sitebix.com

== Installation ==

1. Upload the `sitebix-to-emailoctopus` folder to `wp-content/plugins/` or install the ZIP via **Plugins → Add New → Upload Plugin**.
2. Activate **Sitebix to EmailOctopus**.
3. Go to **Sitebix EO** in the admin menu.
4. Enter your EmailOctopus API key (or define `SITEBIX_WEO_API_KEY` in `wp-config.php`), choose a list, set default contact status, save, and use **Test connection**.

Optional `wp-config.php` override (key is never stored in the database when set):

`define( 'SITEBIX_WEO_API_KEY', 'your-api-key-here' );`

== Elementor Pro (native action) ==

1. In **Sitebix EO → Sources & mapping**, add an **Elementor** profile and map form field IDs to EmailOctopus tags (include one row for your list’s contact email field — often `emailAddress` or `email_address`).
2. Edit your Elementor form → **Actions After Submit** → add **Sitebix → EmailOctopus**.
3. Select the mapping profile and save.

== Webhook (Elementor “Webhook” action or any HTTP client) ==

1. Add a **Webhook** source; set a **New webhook secret** and save.
2. Copy the **Webhook URL** from the source card. Append `?secret=YOUR_SECRET` or send header `X-Sitebix-WEO-Secret: YOUR_SECRET`.
3. On first receive, while mapping is incomplete or the source is inactive, the plugin **holds** the payload, stores a redacted sample, and returns HTTP 202. Complete mapping, set state to **Active**, check **Active**, then save. Use **Replay sample** if needed.

**IP allowlist:** One IP per line in the source settings; empty list allows all. Behind reverse proxies, `REMOTE_ADDR` may need server configuration for accuracy.

== User sync & background processing ==

Bulk sync enumerates existing list contacts (paginated), compares to WordPress users (optional role checkboxes on the Connection tab), then upserts missing contacts in batches. If **Action Scheduler** is available (e.g. via WooCommerce), jobs run there; otherwise **WP-Cron** schedules follow-up ticks. Keep **WP_CRON** or a real cron visiting `wp-cron.php` enabled on budget hosts.

== Frequently Asked Questions ==

= Will bulk sync work on large lists? =

The plugin paginates EmailOctopus contacts and processes WordPress users in pages. Very large lists increase memory use for the on-site email set; for huge directories consider segmenting by role or running off-peak.

= What happens on uninstall? =

By default options and the log table are removed. To retain data, add to a small must-use plugin or theme:

`add_filter( 'sitebix_weo_uninstall_preserve_data', '__return_true' );`

= API rate limits? =

EmailOctopus applies token-bucket limits; the client backs off on HTTP 429 using `Retry-After` when present.


== External services ==

This plugin connects to the **EmailOctopus** email marketing API (`https://api.emailoctopus.com`) so site owners can sync WordPress users and form submissions to EmailOctopus lists.

**What it is used for:** creating and updating EmailOctopus contacts, listing lists and fields, testing the API connection, and (when configured) comparing WordPress users to list contacts during bulk sync.

**What data is sent and when:**
* The site owner's EmailOctopus API key is sent as a Bearer token on every API request (after they save it in settings, or via the optional `SITEBIX_WEO_API_KEY` constant).
* Contact data mapped by the site owner (at minimum an email address; optionally names, custom fields, and tags) is sent when a WordPress user is created/updated and matches sync rules, when an Elementor form action or webhook source processes a submission, when a held webhook sample is replayed, or when a bulk user sync runs.
* Connection tests and list/field lookups send only authentication and list identifiers — not contact payloads — when an admin uses those controls.

No contact data is sent until the site owner configures an API key and active mapping sources. EmailOctopus is operated by Three Hearts Digital Ltd.

* Terms of Use: https://emailoctopus.com/legal/terms
* Privacy Policy: https://emailoctopus.com/legal/privacy


== Screenshots ==

1. Connection settings: API key, list, default contact status, role filters, and connection test.
2. Sources and field mapping: add Elementor, webhook, or WordPress user profiles.
3. Bulk WordPress user sync.
4. Filterable activity log.

== Changelog ==

= 1.0.1 =
* Document EmailOctopus as an external service in the readme (terms and privacy links).

= 1.0.0 =
* Initial release.

== Credits ==

Developed by **K. Young** for **Sitebix**.
