MailnapticSign inCreate an accountHelp CenterAPI docs

How Site Tracking Works

Understand page views, events, cookies, and sessions

How Site Tracking Works

Mailnaptic's site tracking system connects your email marketing data with website visitor behavior. This article explains the technical architecture — how page views are recorded, how custom events work, how cookies identify visitors, and how anonymous sessions are resolved to known email contacts.

Architecture overview

The site tracking system consists of three components:

  1. Tracking script — A lightweight JavaScript file served from GET /tracking-script.js (public, no auth, 1-hour cache). This runs in the visitor's browser and sends events to Mailnaptic.
  2. Ingest endpoint — POST /site/ingest receives events from the tracking script. This endpoint uses CORS headers to accept requests from any origin and authenticates via the site_key in the request body.
  3. Site event storage — Events are stored in the site_event table and linked to contacts when identity is known.

Page view tracking

When the tracking script loads on a page, it automatically records a page view event. The event includes:

  • URL — The full page URL.
  • Page title — The HTML document title.
  • Referrer — The previous page URL, if available.
  • Timestamp — When the page was loaded.
  • Anonymous ID — The _mn_aid cookie value identifying this browser.

For single-page applications, the script monitors the browser's History API to detect client-side navigation and records page views for each route change.

Custom events

You can send custom events from your website using the tracking API:

window.mn('track', 'event_name', { key: 'value' });

Custom events are stored with the event type track and include the event name and any properties you pass. Common custom events include:

  • product_viewed — Visitor viewed a product page.
  • cart_abandoned — Visitor left without completing a purchase.
  • purchase_completed — Visitor completed a purchase.
  • signup_started — Visitor began a signup flow.
  • pricing_viewed — Visitor viewed the pricing page.

Cookie and session management

The _mn_aid cookie

The first time the tracking script runs in a browser, it creates a first-party cookie called _mn_aid (Mailnaptic anonymous ID). This cookie:

  • Contains a randomly generated unique identifier.
  • Persists for 365 days.
  • Is first-party only (set on your website's domain, not a third-party domain).
  • Is used to group events from the same browser together.

The anonymous ID allows Mailnaptic to build a history of a visitor's behavior before their identity is known.

Identity resolution

The key challenge of site tracking is connecting anonymous browser sessions to known email contacts. Mailnaptic solves this through email click identity resolution:

  1. A contact clicks a tracked link in a Mailnaptic email.
  2. The click tracking system (/track/click) generates a single-use 64-character hex identity token.
  3. The token is appended to the redirect URL as a query parameter: ?_mn=TOKEN.
  4. The visitor lands on your website with the _mn parameter.
  5. The tracking script detects the parameter and sends an identify_token event to the ingest endpoint.
  6. The server resolves the token to a contact_id using the contact_identity_token table.
  7. The anonymous ID (_mn_aid) is now linked to the contact.

Retroactive attribution

After identification, Mailnaptic calls SiteEventModel.resolveContactForAnon() to retroactively update all previous anonymous events from that browser with the now-known contact ID. This means page views and events recorded before the visitor was identified are correctly attributed to the contact.

Using site data in Mailnaptic

Segments

Site tracking data powers several segment filter types:

  • site_visited_page / site_not_visited_page — Filter contacts by page visits.
  • site_triggered_event / site_not_triggered_event — Filter contacts by custom events.
  • site_purchased / site_not_purchased — Filter contacts by purchase events.

Automations

Site events can trigger automations using the site_event trigger type. Configure the trigger to fire on specific event types (page or track) and event names.

Contact activity feed

Each contact's profile includes a filterable activity feed. Use the web filter to see all site tracking events for that contact, including page views, custom events, and identification events.

Graceful degradation

All site tracking database queries in Mailnaptic gracefully handle the case where the site_event table does not exist (e.g., if the migration has not been run yet). Segment filters referencing site data return no matches instead of errors, and the tracking endpoints return appropriate error responses.

Site tracking bridges the gap between email marketing and website behavior, giving you a complete picture of how contacts interact with your brand across both channels.

·

More in Site Tracking