- An order confirmation is sent. A tiny image inside the email is fetched a few seconds later.
- It is tempting to turn that signal into a business fact: the buyer read the confirmation, the supplier saw the cancellation, the approver received the request.
- Email clients can block images, preload them through privacy proxies, cache them or fetch them more than once.
- For a Medusa procurement platform, we built first-party email activity telemetry with that boundary at its centre.
The client problem
An order confirmation is sent. A tiny image inside the email is fetched a few seconds later. The dashboard marks the message as opened.
It is tempting to turn that signal into a business fact: the buyer read the confirmation, the supplier saw the cancellation, the approver received the request.
That conclusion is unsafe.
Email clients can block images, preload them through privacy proxies, cache them or fetch them more than once. A pixel request proves that an instrumented resource was requested. It does not prove who looked at the message, what they understood or whether they agreed to anything.
For a Medusa procurement platform, we built first-party email activity telemetry with that boundary at its centre. It records submission state and pixel fetches, links activity to the relevant commerce entity and gives operators a useful diagnostic view—without allowing “opened” to become an approval, delivery receipt or payment decision.
Start with the business question, not the vanity metric
Why track an email at all?
The useful questions are usually operational:
- Was the message prepared for the provider?
- Did submission return an identifier?
- Was tracking instrumentation available?
- Has the embedded resource ever been fetched?
- Which order, quote, conversation or import generated the email?
- Are emails failing before they leave the platform?
Those questions can help support investigate a missing notification or compare templates and categories. They do not require pretending to know a person's attention.
We therefore treat the word opened as a convenient dashboard label for fetch_count > 0, then explain the precise meaning: at least one request reached the tracking endpoint for that send.
The business truth remains elsewhere. An order is acknowledged through an order action. A quote is accepted through its workflow. An invoice is reviewed through the invoice lifecycle. Email activity can prompt investigation; it cannot replace those events.
Create one opaque token per instrumented send
Every eligible email send receives a fresh random token.
The public HTML contains that token in a pixel URL. The database stores only a SHA-256 digest, not the original token. When the image endpoint receives a request, it hashes the supplied value and looks up the matching active record.
This follows the same principle used for other bearer-like secrets: possession of the database should not expose the live URLs directly.
The tracking record can retain operational context such as recipient, subject, template or category, authorised actor and a bounded commerce entity type and ID. Supported entity types include orders, order sets, quotes, conversations, invoices, seller invitations, imports and wishlists.
That context makes the activity useful. An operator can investigate “email for order X” rather than comparing timestamps across a generic provider log.
The token identifies one send. It does not identify a human viewer.
Instrument the final HTML, not the template idea
Medusa notifications may begin as a template plus data or as already-rendered content.
The tracking service prepares the actual email that will be submitted. When an eligible template has not yet been rendered into HTML, it renders the canonical email first. It then injects one hidden 1×1 image before the closing body tag, or appends it when no closing tag exists.
A marker prevents the same email from receiving the pixel twice. The tracking metadata is removed before the provider receives the notification so internal orchestration fields do not leak into the provider contract.
This placement matters because telemetry should describe the submitted HTML, not merely the existence of a template definition. If rendering falls back or the content has no eligible HTML, the system can still send the email without pretending it was instrumented.
Delivery remains the primary capability. Tracking is an optional layer around it.
Never make telemetry a dependency of email delivery
The platform creates a pending tracking record before injecting the pixel. If preparation succeeds, it submits the email through Medusa's notification service and records the resulting state and provider notification ID when one is available.
Several telemetry steps can fail: the tracking module may be unavailable, template rendering may fail, the database write may exceed its short deadline or pixel injection may fail.
In those cases, the notification path warns and sends the original email where possible. A tracking transition timeout after provider success does not turn a delivered email into a failed business notification.
This ordering reflects the client's priority. A supplier still needs the order email even if the analytics table is temporarily unavailable.
The activity view therefore distinguishes submitted, failed, instrumentation_failed, pending and unknown. It does not collapse telemetry health and email-provider outcome into one optimistic status.
Make the pixel endpoint cheap and boring
An email client should receive the same tiny image regardless of whether telemetry storage succeeds.
The public route validates the token's shape, hashes it and attempts a bounded database update. It uses in-process admission control to limit concurrent writes and applies a short statement timeout. When the telemetry path is saturated or unavailable, it sheds the update and logs a warning rather than making the image request slow or exposing an internal error.
The response is always a constant 1×1 GIF. It sets no cookie, removes cache validators and applies no-store headers. Invalid, expired and unknown tokens do not produce a different public body that would reveal whether a tracking record exists.
This is a deliberately narrow endpoint: receive an opaque token, attempt one bounded update, return constant bytes.
That shape protects the rest of the Medusa application from a burst of automatic image fetches generated by recipient infrastructure.
Record fetch evidence precisely
When a valid, unexpired tracking record is found, the update preserves the first fetch time, writes the latest fetch time and increments a counter.
Those three fields answer different operational questions:
first_fetched_at: when did any request first reach the pixel?last_fetched_at: when was it most recently requested?fetch_count: how many matching requests were recorded?
A first fetch can also reconcile a pending or unknown send into submitted. The reasoning is limited but useful: some downstream system could only request the unique pixel URL after receiving the instrumented HTML.
It still does not prove human attention. The first fetch may come from automated scanning. Later fetches may be repeated rendering, caching behaviour or forwarding. Ten requests do not mean ten readers.
We store the evidence the endpoint actually observed and avoid translating it into psychology.
Understand false positives and false negatives
Pixel telemetry is incomplete in both directions.
A false positive occurs when the resource is fetched without the recipient reading the message. Privacy infrastructure may proxy images before the user opens the email. Security scanners can inspect content automatically. Forwarding can produce another fetch unrelated to the original recipient.
A false negative occurs when a person reads the message without requesting the image. The client may block remote images, display only text, serve a cached copy or prevent the request for privacy reasons.
That is why “unopened” in the activity view means submitted with zero recorded pixel fetches. It does not mean unread.
This vocabulary is not a footnote. Product labels, support playbooks and automated decisions should all preserve it. A useful UI can show “pixel fetched” or add explanatory help beside “opened”.
Precision protects the team from building false urgency on noisy data.
Link telemetry to commerce without changing commerce state
An activity record becomes more useful when it points to the entity that caused the notification.
The project supports bounded entity types such as order, quote, conversation, invoice and import. Operators can search by recipient, subject, template, category or provider notification ID and navigate from the activity row toward the relevant workflow.
This helps answer questions such as:
- Was the cancellation email submitted for this order?
- Did the conversation notification receive a pixel request?
- Are one template's sends failing instrumentation?
- Is an import-completion email still pending?
The relationship is diagnostic, not causal. Recording a fetch does not update the order, accept the quote, mark an invoice reviewed or close a support case.
Commerce state changes only through the governed domain action designed for that decision.
Give operators a truthful activity view
The admin endpoint returns individual sends with recipient, subject, template, category, entity, submission state, provider ID, first and last fetch, count and creation time.
It also aggregates totals for sent, pixel-fetched, submitted-without-fetch and failed records. Filters let an operator narrow the list without reading application logs.
The view is useful for patterns. A group of instrumentation_failed rows can reveal a rendering change. A pending group can expose a tracking transition problem. A submitted record with no fetch can inform support, provided nobody treats it as proof that the recipient ignored the email.
The dashboard should lead with the strongest fact available. “Submitted at 10:42; no pixel fetch recorded” is more honest and more actionable than “customer did not open”.
Operational telemetry earns trust by refusing to over-interpret itself.
Retain only what the investigation needs
Tracking rows contain personal and commercial context. They should not live forever by default.
The project configures token expiry and a scheduled cleanup policy. Stale pending rows move to unknown in bounded batches, acknowledging that the final submission transition may have been lost. Older tracking rows are deleted in bounded batches under a configurable retention window.
The system also provides targeted deletion by tracking record, actor or commerce entity. That creates a practical path for data lifecycle requirements without scanning the complete table.
Retention is part of the capability, not housekeeping added after launch. If the business cannot explain why an old recipient address and subject remain stored, the telemetry has outlived its purpose.
Short-lived opaque tokens and bounded records are easier to govern than an indefinite archive of email behaviour.
A practical email-telemetry checklist
Before instrumenting Medusa email, ask:
- Which operational question will the activity answer?
- Is each send assigned a fresh opaque token?
- Is only a digest stored?
- Is the final HTML instrumented exactly once?
- Can the email still send when tracking preparation fails?
- Are provider submission and instrumentation state separate?
- Does the public endpoint return constant bytes for every token outcome?
- Are database concurrency and statement time bounded?
- Are first fetch, last fetch and count recorded separately?
- Does “unopened” mean only zero recorded fetches?
- Are pixel fetches excluded from approvals and other business decisions?
- Can activity link to a bounded commerce entity?
- Are retention, expiry and deletion policies explicit?
If the product wants proof of acknowledgement, build an acknowledgement action. Do not rename an image request.
Why Medusa was the right foundation
Medusa's notification path already connected templates, recipients and commerce events. We extended that path with a first-party tracking record, deterministic HTML instrumentation, a bounded pixel endpoint and an operational activity view.
Because the capability lives beside the commerce context, an email can be traced back to its order, quote, conversation or import without letting telemetry mutate those domains.
The result is useful precisely because it is modest. The platform can diagnose whether an instrumented send was submitted and whether its resource was fetched. It cannot know whether a human read, understood or accepted the message.
Good architecture does not make weak evidence sound stronger. It makes the boundary visible—and gives the business a proper action when certainty actually matters.