Tracking Custom Events

Send custom event data from your website to Mailnaptic

Tracking Custom Events

Beyond automatic page views, Mailnaptic's site tracking snippet lets you send custom events from your website. Custom events capture specific user actions — button clicks, form submissions, video plays, purchases — and make that data available for segmentation, automation triggers, and contact activity feeds.

Sending a custom event

Once the Mailnaptic tracking snippet is installed on your site, use the global mailnaptic object to fire events:

mailnaptic.track('product_viewed', {
  product_id: 'SKU-4821',
  product_name: 'Wireless Headphones',
  price: 59.99,
  currency: 'USD'
});

The track method accepts two arguments:

Event name (string, required) — a descriptive identifier like product_viewed, signup_completed, or cart_updated. Use snake_case for consistency.
Properties (object, optional) — arbitrary key-value pairs that describe the event in more detail.

Naming conventions

Consistent event naming makes segmentation and automation rules much easier to build. Follow these guidelines:

Use snake_case: order_completed instead of OrderCompleted or order-completed.
Start with a noun, then the action: form_submitted, video_played, cart_abandoned.
Be specific: pricing_page_viewed is more useful than a generic page_viewed.
Keep names under 64 characters.

Common event examples

Event name	When to fire	Suggested properties
`signup_completed`	User finishes registration	`plan`, `source`
`product_added_to_cart`	Item added to cart	`product_id`, `quantity`, `price`
`order_completed`	Purchase confirmed	`order_id`, `total`, `items_count`
`feature_activated`	User enables a product feature	`feature_name`
`support_ticket_opened`	User submits a help request	`ticket_id`, `category`

Property data types

Event properties support strings, numbers, and booleans. Nested objects are flattened automatically. Keep property values concise — avoid sending large blobs of HTML or lengthy text.

Verifying events are received

After firing an event, verify it arrived in Mailnaptic:

Open your browser's developer console and confirm the network request to the ingest endpoint returns a 200 status.
In Mailnaptic, navigate to Domains → your domain → Tracking. The event count should increment and the "last received" timestamp should update.
If the visitor has been identified (via an email click or identity token), the event will appear in the contact's Activity tab under the Web filter.

Rate limits and payload size

Each browser session can send up to 100 events per minute. Each event payload is limited to 8 KB of JSON. Events exceeding these limits are silently dropped. If you need to track high-frequency interactions (e.g., scroll depth every pixel), batch or throttle them client-side before calling mailnaptic.track.

Tip: You can use custom events as triggers for automations. See Trigger automations from web events for details.

Tracking Custom Events