Tracking

Track product views and browsing behavior to power abandoned browse flows and personalized recommendations. Product views are automatically linked to contacts and can trigger flow automations.

Track Product View

POST

/track/product-view

Record a product view for a contact

Name	Type	Required	Description
email	string	Optional	Contact email address. Required if contact_id is not provided.
contact_id	string (UUID)	Optional	Contact ID. Required if email is not provided.
product_id	string	Required	Your product identifier (max 100 characters)
product_name	string	Required	Product display name (max 200 characters)
product_url	string (URL)	Required	Full URL to the product page
variant_id	string	Optional	Product variant identifier (max 100 characters)
image_url	string (URL)	Optional	Product image URL
price	number	Optional	Product price (must be >= 0)
currency	string	Optional	3-letter ISO currency code (default: USD)
category	string	Optional	Product category (max 100 characters)
brand	string	Optional	Product brand name (max 100 characters)
sku	string	Optional	Stock keeping unit (max 100 characters)
session_id	string	Optional	Browser session ID for grouping views (max 100 characters)

curl -X POST https://api.topmail.so/api/v1/track/product-view \
  -H "Authorization: Bearer tm_live_abc123" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "shopper@example.com",
    "product_id": "prod_abc123",
    "product_name": "Premium Wireless Headphones",
    "product_url": "https://yourstore.com/products/wireless-headphones",
    "image_url": "https://yourstore.com/images/headphones.jpg",
    "price": 99.99,
    "currency": "USD",
    "category": "Electronics",
    "brand": "AudioCo",
    "sku": "WH-PRO-BLK"
  }'

{
  "data": {
    "id": "view-uuid-12345",
    "contact_id": "contact-uuid-67890",
    "product_id": "prod_abc123",
    "product_name": "Premium Wireless Headphones",
    "viewed_at": "2025-01-15T14:30:00.000Z"
  }
}

Flow Triggers

Product views automatically trigger product_viewed flow automations. Use this to set up abandoned browse emails, product recommendation flows, or price drop notifications.

Contact Required

The contact must already exist in your workspace. If the email or contact_id does not match an existing contact, the API returns a 404 error. Create the contact first using the Contacts API.

Bot Detection & Metric Accuracy

TopMail automatically detects and flags bot activity in email tracking events. Every open and click event includes bot detection metadata so you can filter automated scanner activity from real engagement.

Detection Methods

Honeypot links — Every email includes an invisible link hidden from human readers. Only bots click it. This is the highest-confidence signal.
Click burst detection — 3+ link clicks within 2 seconds, or 5+ within 30 seconds, flags all clicks as bot.
IP detection — Known security scanner IPs (Proofpoint, Microsoft Defender, Mimecast, Barracuda) and datacenter IPs.
User agent analysis — Known bot user agents (Python requests, curl, crawlers, etc.).
Timing analysis — Clicks within 10 seconds of delivery are flagged as suspicious.
Apple MPP detection — Apple Mail Privacy Protection proxy opens are flagged separately.

Inferred Opens

When a human clicks a link but no open was recorded (images blocked), TopMail automatically creates an inferred open event. This prevents click rate from exceeding open rate and matches the approach used by Mailchimp. Inferred opens have metadata.inferred: true in the event data.

Bot Fields on Events

Name	Type	Required	Description
is_bot	boolean	Optional	Whether this event was flagged as bot activity.
bot_type	string	Optional	Type of bot detected: security_scanner, apple_mpp, datacenter, timing, honeypot, user_agent, or behavior.
bot_confidence	string	Optional	Detection confidence: high, medium, or low.
bot_signals	string[]	Optional	Array of detection signals that triggered the classification.

Filtering in Your Analytics

TopMail's dashboard and analytics automatically exclude bot events. If you're using the API or webhooks to build your own analytics, filter events where is_bot = true to get accurate human engagement metrics.