# Tracking Custom Events

Send custom event data from your website to Mailnaptic

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:

1. **Event name** (string, required) — a descriptive identifier like `product_viewed`, `signup_completed`, or `cart_updated`. Use snake_case for consistency.
2. **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:

1. Open your browser's developer console and confirm the network request to the ingest endpoint returns a `200` status.
2. In Mailnaptic, navigate to **Domains → your domain → Tracking**. The event count should increment and the "last received" timestamp should update.
3. 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.
