Skip to main content
PushMail.dev

Website Tracking

Track page views and custom events on your website with a lightweight JavaScript snippet. Tie anonymous visitors to known contacts.

PushMail's tracking snippet is a lightweight JavaScript tag (~1.5 KB) that you embed on your website. It automatically tracks page views, supports custom events, and links anonymous visitors to known contacts when they identify themselves (e.g. via a signup form).

Quick setup

Get your site ID

Every site in PushMail has a numeric ID. Find it in the dashboard under Sites, or via the API:

cURL
curl https://pushmail.dev/api/v1/sites \
  -H "Authorization: Bearer pm_live_YOUR_KEY"

Note the id field in the response.

Embed the tracking snippet

Add this script tag to every page you want to track, just before the closing </body> tag:

index.html
<script src="https://pushmail.dev/api/v1/tracking/script?siteId=YOUR_SITE_ID"></script>

Replace YOUR_SITE_ID with your actual site ID (e.g. 1, 42).

That's it. Page views are now being tracked automatically, including SPA navigation via the History API.

Identify visitors (optional)

When a visitor logs in or submits a form, call pushmail.identify() to link their anonymous session to a contact:

After login or form submit
<script>
  pushmail.identify('user@example.com', {
    firstName: 'Jane',
    plan: 'pro'
  });
</script>

This creates or updates the contact and re-attributes all past anonymous page views to them.

JavaScript API

The snippet exposes a global pushmail object with three methods:

pushmail.track(event, properties?)

Track a custom event.

// Track a custom event
pushmail.track('viewed_pricing');

// With properties
pushmail.track('added_to_cart', {
  product: 'Enterprise Plan',
  value: 299
});

Page views are tracked automatically on load and on SPA navigation. You can also call pushmail.page() manually.

pushmail.identify(email, properties?)

Link the current anonymous visitor to a contact by email. If the contact does not exist, it is created automatically with source: "tracking_snippet".

pushmail.identify('jane@example.com', {
  firstName: 'Jane',
  lastName: 'Doe',
  plan: 'starter',
  company: 'Acme Inc'
});

Properties are merged into the contact's customFields. The special keys firstName and lastName are mapped to the corresponding contact fields when creating a new contact.

pushmail.page(properties?)

Explicitly track a page view. This is called automatically on page load and SPA navigation, but you can call it manually if needed.

pushmail.page({ section: 'docs' });

REST API endpoints

The tracking snippet communicates with two public endpoints. You can also call these directly from your backend if you prefer server-side tracking.

POST /api/v1/tracking/event

Record a tracking event.

cURL
curl -X POST https://pushmail.dev/api/v1/tracking/event \
  -H "Content-Type: application/json" \
  -d '{
    "siteId": 1,
    "anonymousId": "pm_abc123",
    "event": "page_view",
    "url": "https://example.com/pricing",
    "referrer": "https://google.com",
    "properties": { "campaign": "spring-sale" }
  }'
FieldTypeRequiredDescription
siteIdnumberYesYour site ID
eventstringYesEvent name (page_view, custom names)
anonymousIdstringNo*Anonymous visitor ID (from localStorage)
emailstringNo*Contact email (alternative to anonymousId)
urlstringNoPage URL
referrerstringNoReferrer URL
propertiesobjectNoCustom event properties (stored as JSON)

* At least one of anonymousId or email is required.

POST /api/v1/tracking/identify

Link an anonymous visitor to a known contact.

cURL
curl -X POST https://pushmail.dev/api/v1/tracking/identify \
  -H "Content-Type: application/json" \
  -d '{
    "siteId": 1,
    "email": "jane@example.com",
    "anonymousId": "pm_abc123",
    "properties": {
      "firstName": "Jane",
      "plan": "pro"
    }
  }'
FieldTypeRequiredDescription
siteIdnumberYesYour site ID
emailstringYesContact email address
anonymousIdstringNoAnonymous ID to re-attribute past events
propertiesobjectNoCustom fields to set on the contact

GET /api/v1/tracking/script

Returns the JavaScript tracking snippet. Not typically called directly -- use the <script> tag instead.

ParamTypeRequiredDescription
siteIdnumberYesYour site ID (query parameter)

How it works

  1. When the script loads, it generates a random anonymous ID and stores it in localStorage under the key pm_aid.
  2. On every page load (and SPA navigation), it sends a page_view event to /api/v1/tracking/event with the anonymous ID, URL, and referrer.
  3. When you call pushmail.identify(email), it sends the email and anonymous ID to /api/v1/tracking/identify. PushMail looks up or creates the contact, then re-attributes all past anonymous page views to them.
  4. After identification, subsequent track() calls still use the anonymous ID, but the server can join them to the contact via the page_views table.

Rate limits

The tracking endpoints are rate limited per site to prevent abuse:

EndpointLimit
/tracking/event100 requests/minute per site
/tracking/identify30 requests/minute per site

These are public endpoints and do not require an API key. They are validated by siteId.

Security

  • The tracking endpoints are intentionally public (no API key needed) so the snippet can run on any website.
  • The siteId is visible in the script tag URL. This is safe -- it only allows writing tracking events, not reading data.
  • Rate limiting prevents abuse.
  • No cookies are used. The anonymous ID is stored in localStorage only.

Framework integration examples

Next.js (App Router)

app/layout.tsx
import Script from 'next/script';

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html>
      <body>
        {children}
        <Script
          src="https://pushmail.dev/api/v1/tracking/script?siteId=1"
          strategy="afterInteractive"
        />
      </body>
    </html>
  );
}

React SPA

src/App.tsx
import { useEffect } from 'react';

function App() {
  useEffect(() => {
    const script = document.createElement('script');
    script.src = 'https://pushmail.dev/api/v1/tracking/script?siteId=1';
    script.async = true;
    document.body.appendChild(script);
  }, []);

  // After user logs in:
  function onLogin(user: { email: string; name: string }) {
    window.pushmail?.identify(user.email, { firstName: user.name });
  }

  return <div>...</div>;
}

Server-side (Node.js)

If you prefer server-side tracking, call the endpoints directly:

server.ts
async function trackEvent(siteId: number, email: string, event: string) {
  await fetch('https://pushmail.dev/api/v1/tracking/event', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ siteId, email, event }),
  });
}

// Track a purchase
await trackEvent(1, 'jane@example.com', 'purchase');

DNS Setup & Troubleshooting

Configure DNS records for email authentication, click tracking, and deliverability. Provider-specific instructions and fixes for common issues.

Email Click & Open Tracking

Track clicks and opens in your emails with custom branded domains and automatic SSL. No CDN setup, no support tickets.

On this page

Quick setupGet your site IDEmbed the tracking snippetIdentify visitors (optional)JavaScript APIpushmail.track(event, properties?)pushmail.identify(email, properties?)pushmail.page(properties?)REST API endpointsPOST /api/v1/tracking/eventPOST /api/v1/tracking/identifyGET /api/v1/tracking/scriptHow it worksRate limitsSecurityFramework integration examplesNext.js (App Router)React SPAServer-side (Node.js)