# RogalMail for OpenCart

**Module version 1.1.0** — new in this version: storefront tracking
(product views, cart adds and purchase events, so browse/cart flows and
campaign product reports work for OpenCart stores). See "Storefront
tracking" below and the upgrade note at the end.

Connect your OpenCart store to your RogalMail account. The module sends your
products, your orders, and your newsletter subscribers to RogalMail so you can
email the people who actually asked to hear from you, build product blocks from
your real catalog, and see order revenue in your RogalMail reports.

There are two packages. Pick the one that matches your store:

- **OpenCart 3.0.x** — `rogalmail-opencart-oc3.ocmod.zip`
- **OpenCart 4.0.x** — `rogalmail-opencart-oc4.ocmod.zip`

## Before you start

You need one thing from RogalMail: an **API key**.

1. Log in to RogalMail.
2. Go to **Settings → API keys** and create a key.
3. Copy it right away — it starts with `rm_live_` and is only shown once.

That one key is all this module needs.

## Install — OpenCart 3

1. In your store admin, go to **Extensions → Installer**.
2. Click **Upload** and choose `rogalmail-opencart-oc3.ocmod.zip`.
3. Go to **Extensions → Modifications** and click the blue **Refresh** button
   (this applies the package, even though this module makes no core file
   modifications).
4. Go to **Extensions → Extensions**, choose **Modules** from the dropdown,
   find **RogalMail**, and click the green **Install** (+) button.
5. Click the **Edit** (pencil) button next to RogalMail to open its settings.

## Install — OpenCart 4

1. In your store admin, go to **Extensions → Installer**.
2. Click **Upload** and choose `rogalmail-opencart-oc4.ocmod.zip`.
3. Go to **Extensions → Extensions**, choose **Modules** from the dropdown,
   find **RogalMail**, and click the green **Install** (+) button.
4. Click the **Edit** (pencil) button next to RogalMail to open its settings.

## Set it up

On the RogalMail settings screen:

1. **RogalMail site URL** — leave this as `https://rogalmail.com` unless you
   run RogalMail somewhere else.
2. **API key** — paste the `rm_live_...` key you copied from RogalMail.
3. **Status** — set to **Enabled**.
4. Click **Save**.
5. Click **Test connection**. You should see a confirmation telling you how
   many contacts your RogalMail account currently holds. If it fails, check
   the URL and key — the **Connection log** at the bottom of the same screen
   shows the exact error RogalMail (or your server) returned.
6. Recommended: click **Sync products now** and **Sync customers now** once,
   so your existing catalog and your existing subscribers are in RogalMail
   right away instead of waiting for new activity.

## What syncs, and when

- **Customers** — automatically, the moment a customer registers or their
  account is edited. **Only customers who subscribed to your newsletter**
  (their OpenCart newsletter flag is on) are sent as contacts. See the
  consent rule below.
- **Orders** — automatically, when an order is placed and again every time
  its status changes (paid, shipped, completed, refunded, and so on). All
  orders are sent, with their items, totals, currency, and date. RogalMail
  matches the buyer by email for reporting and automations.
- **Products** — when you click **Sync products now** on the settings screen.
  It walks your whole enabled catalog (100 at a time) and sends each
  product's name, page link, price (special price when one is active), model
  (as the SKU), first category, a plain-text description, image, and whether
  it is in stock. Run it again after big catalog changes.
- **Customers backfill** — **Sync customers now** sends every existing
  customer whose newsletter flag is on, 100 at a time.

Every sync is quiet and safe: if RogalMail is ever unreachable, your store
keeps working normally — the failed call is written to the Connection log on
the settings screen (the last 30 entries) and nothing is shown to your
shoppers.

## The newsletter consent rule

This module will never turn a buyer into a marketing contact on its own.
A customer is sent to RogalMail as a contact **only** when they opted in to
your store newsletter. Placing an order does not subscribe anyone: orders
are sent for revenue reporting and order-based automations, matched by
email, and a buyer who never opted in is not created as a marketing contact
by this module.

If a subscriber already exists in RogalMail (for example, they signed up
through a RogalMail form first), the module updates their name and leaves
their subscription state exactly as it is.

## Storefront tracking (1.1.0)

The module also reports what shoppers do in your store, so browse and
cart recovery flows and the Products tab on campaign reports work:

- **Product views** — every product page view, reported anonymously
  (it counts interest in a product; it names nobody and enrols nobody).
- **Cart adds** — when an identified shopper adds to the cart, the
  cart's contents at that moment.
- **Purchases** — when an order is placed, alongside the order sync
  (the two records are the same order in RogalMail, never two).

**The tracking consent rule** is the newsletter rule above, extended:
a tracking event carries a shopper's **email only** when they are
logged in *and* their newsletter flag is on — the same flag that gates
contact sync — except a purchase, which carries the order's own email
because orders always sync. A shopper who arrived from one of your
RogalMail email links is identified instead by the signed token in
that link (held for their visit session, with an anonymous visitor id
that lets RogalMail join their earlier anonymous views to them once
identified). Tracking never creates a marketing contact, and whether
anyone is emailed still follows their subscription status in
RogalMail.

## Upgrading from 1.0.x

Upload the new package over the old one (Extensions → Installer),
refresh Modifications (OpenCart 3), then open the RogalMail module
settings page once — the module re-registers its events when the
page opens, so the new tracking events switch on without an
uninstall and without losing your saved API key or settings.

## Uninstall

1. Go to **Extensions → Extensions → Modules**, find **RogalMail**, and click
   the red **Uninstall** (−) button. This removes the module's sync events
   and its settings (including the stored API key and log).
2. Optionally, go to **Extensions → Installer** and delete the uploaded
   RogalMail package from the install history.

Uninstalling stops all syncing immediately. Contacts, orders, and products
already in RogalMail stay there — delete them inside RogalMail if you want
them gone. Nothing in your store's own customers, orders, or products is
changed by installing or uninstalling this module.

## Troubleshooting

- **Test connection fails** — open the Connection log on the settings
  screen. "answered 401" almost always means the API key is wrong or was
  revoked in RogalMail; create a fresh key and paste it in. A cURL or
  timeout message means your server could not reach RogalMail at all.
- **Nothing syncs** — check the module Status is Enabled, the API key is
  saved, and the connection test passes. Remember the buttons and the
  automatic syncs all use the *saved* settings, so save first.
- **A customer is missing in RogalMail** — check their newsletter flag in
  OpenCart (Customers → edit). If it is off, the consent rule above is
  working as intended.
