Developer Documentation

Site Token

Site Tokens are used for client side tracking (JavaScript SDK, mobile tracking). They are safe to expose in browser code because they can only submit tracking events and identify visitors. They cannot read or modify your data.

Pass the token via the X-Site-Token header or the site_token query parameter:

// Header
X-Site-Token: YOUR_SITE_TOKEN

// Query parameter (used by sendBeacon)
POST /api/v1/t?site_token=YOUR_SITE_TOKEN

Find your Site Token in Team Settings. Each team has a unique token.

API Token (Sanctum)

API Tokens are used for server side operations: managing contacts, controlling campaigns, triggering transactional emails, sending conversion events, and registering push devices. Include the token in the Authorization header:

Authorization: Bearer YOUR_API_TOKEN

Generate API tokens from your team settings in the dashboard. Tokens are scoped to your team.

Installation

Add the following snippet to your website, ideally before the closing </body> tag. Replace YOUR_SITE_TOKEN with your actual Site Token.

<script>
  window.markt = [];
  window.markt.SITE_TOKEN = 'YOUR_SITE_TOKEN';
  window.markt.API_HOST = 'https://your-domain.com';
</script>
<script src="https://your-domain.com/js/markt.js" defer></script>

The SDK initializes automatically. Before the script loads, you can queue calls using the array stub syntax:

// Queue calls before SDK loads
window.markt = window.markt || [];
window.markt.push(['track', 'signup_started', { plan: 'pro' }]);
window.markt.push(['identify', '[email protected]', { first_name: 'John' }]);

Methods

Page View

// Automatic (called on page load and navigation)
// No action needed unless you want to manually trigger

// Manual call with custom values
markt.page('https://example.com/products', 'Products Page', 'https://google.com');

Custom Event

// Track a custom event
markt.track('added_to_cart', {
  product_id: 'SKU-123',
  product_name: 'Blue T-Shirt',
  price: 29.99,
  currency: 'USD'
});

// Track without properties
markt.track('newsletter_popup_shown');

Identify

// After login or form submission
markt.identify('[email protected]', {
  first_name: 'John',
  last_name: 'Doe',
  company: 'Acme Inc',
  title: 'CTO',
  phone: '+1234567890',
  website: 'https://acme.com'
});

When identify() is called, all previous anonymous page views and events are retroactively linked to the contact. The SDK flushes any pending events before sending the identify call.

SPA Support

The SDK automatically detects single page application navigation by monkey patching history.pushState, history.replaceState, and listening to the popstate event. Each navigation triggers a page view event automatically. No additional configuration is required for frameworks like React, Vue, Next.js, or Nuxt.

Merge Tags

Use double curly braces in your email template to define dynamic placeholders. When the event is triggered, the data object values replace matching tags.

Hi {{customer_name}},

Your order {{order_id}} has been confirmed.
Total: {{order_total}}

Track your shipment: {{tracking_url}}

Expiring Links

Transactional events support expiring links: time limited URLs that become invalid after a specified number of hours. Configure expiring link fields in the event's payload schema in the dashboard. When the email is rendered, URLs marked as expiring are wrapped in signed URLs that automatically expire.

This is useful for password reset links, magic login links, and download URLs that should not remain valid permanently.

Available Events

Payload Format

All webhooks are sent as JSON with the following structure:

{
  "event": "email.opened",
  "payload": {
    "contact_id": 123,
    "campaign_id": 45,
    "email": "[email protected]"
  },
  "timestamp": "2026-01-15T10:15:30+00:00"
}

Headers included with every webhook:

• Content-Type: application/json
• X-Webhook-Signature : HMAC SHA256 signature of the request body

Signature Verification

Each webhook includes an X-Webhook-Signature header containing an HMAC SHA256 hash of the JSON request body, signed with your webhook secret. Always verify the signature to confirm the webhook came from Markt.

const crypto = require('crypto');

function verifyWebhook(secret, signature, body) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(JSON.stringify(body))
    .digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  );
}

// Express.js example
app.post('/webhook', express.json(), (req, res) => {
  const signature = req.headers['x-webhook-signature'];
  if (!verifyWebhook(process.env.WEBHOOK_SECRET, signature, req.body)) {
    return res.status(401).send('Invalid signature');
  }
  console.log('Event:', req.body.event);
  console.log('Payload:', req.body.payload);
  res.status(200).send('OK');
});

function verifyWebhook(string $secret, string $signature, string $rawBody): bool {
    $expected = hash_hmac('sha256', $rawBody, $secret);
    return hash_equals($expected, $signature);
}

// Laravel example
$signature = $request->header('X-Webhook-Signature');
$rawBody = $request->getContent();

if (!verifyWebhook(config('services.markt.webhook_secret'), $signature, $rawBody)) {
    abort(401, 'Invalid signature');
}

$event = $request->input('event');
$payload = $request->input('payload');

import hmac
import hashlib
import json

def verify_webhook(secret: str, signature: str, body: dict) -> bool:
    expected = hmac.new(
        secret.encode(),
        json.dumps(body, separators=(',', ':')).encode(),
        hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(expected, signature)

# Flask example
@app.route('/webhook', methods=['POST'])
def handle_webhook():
    signature = request.headers.get('X-Webhook-Signature')
    if not verify_webhook(WEBHOOK_SECRET, signature, request.json):
        return 'Invalid signature', 401
    event = request.json['event']
    payload = request.json['payload']
    return 'OK', 200

For detailed event payloads and more examples, see the Webhooks Reference.

iOS Integration (APNs)

To send push notifications to iOS devices:

• 1. Create a Push App in the Markt dashboard with your APNs credentials (Key ID, Team ID, Auth Key .p8 file, Bundle ID)
• 2. In your iOS app, request notification permissions and obtain the device token from didRegisterForRemoteNotificationsWithDeviceToken
• 3. Send the device token to the Markt API via POST /api/v1/push-devices
• 4. Optionally link the device to a contact by passing contact_email

// Swift example
func application(_ application: UIApplication,
  didRegisterForRemoteNotificationsWithDeviceToken deviceToken: Data) {
    let token = deviceToken.map { String(format: "%02.2hhx", $0) }.joined()

    var request = URLRequest(url: URL(string: "https://your-domain.com/api/v1/push-devices")!)
    request.httpMethod = "POST"
    request.setValue("Bearer \(apiToken)", forHTTPHeaderField: "Authorization")
    request.setValue("application/json", forHTTPHeaderField: "Content-Type")
    request.httpBody = try? JSONEncoder().encode([
        "push_app_id": pushAppId,
        "device_token": token,
        "contact_email": userEmail,
        "device_model": UIDevice.current.model,
        "os_version": UIDevice.current.systemVersion
    ])
    URLSession.shared.dataTask(with: request).resume()
}

Android Integration (FCM)

To send push notifications to Android devices:

• 1. Create a Push App in the Markt dashboard with your FCM credentials (Service Account JSON)
• 2. In your Android app, integrate Firebase Cloud Messaging and obtain the device token from FirebaseMessaging.getInstance().getToken()
• 3. Send the device token to the Markt API via POST /api/v1/push-devices

// Kotlin example
FirebaseMessaging.getInstance().token.addOnSuccessListener { token ->
    val json = JSONObject().apply {
        put("push_app_id", pushAppId)
        put("device_token", token)
        put("contact_email", userEmail)
        put("device_model", Build.MODEL)
        put("os_version", Build.VERSION.RELEASE)
        put("app_version", BuildConfig.VERSION_NAME)
    }

    val request = Request.Builder()
        .url("https://your-domain.com/api/v1/push-devices")
        .addHeader("Authorization", "Bearer $apiToken")
        .post(json.toString().toRequestBody("application/json".toMediaType()))
        .build()

    OkHttpClient().newCall(request).enqueue(...)
}

Web Push Integration (VAPID)

To send push notifications to web browsers:

• 1. Create a Push App in the Markt dashboard with platform set to "Web" (VAPID public and private keys will be generated)
• 2. Register a service worker in your website and subscribe the user to push
• 3. Send the subscription JSON as the device_token to the Markt API

// Browser JavaScript
async function subscribeToPush(pushAppId, vapidPublicKey) {
  const registration = await navigator.serviceWorker.ready;
  const subscription = await registration.pushManager.subscribe({
    userVisibleOnly: true,
    applicationServerKey: urlBase64ToUint8Array(vapidPublicKey)
  });

  await fetch('https://your-domain.com/api/v1/push-devices', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer ' + apiToken,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      push_app_id: pushAppId,
      device_token: JSON.stringify(subscription),
      contact_email: userEmail
    })
  });
}

Event Deduplication

The event_id field must be globally unique and is used for deduplication when the same event is sent from both the browser pixel and the server side CAPI. Use the same event_id in both the client side Meta Pixel call and the server side CAPI request so ad platforms can deduplicate correctly.

// Generate a unique event ID to use in both pixel and CAPI
const eventId = 'evt_' + Date.now() + '_' + Math.random().toString(36).substr(2, 9);

// Client side: Meta Pixel
fbq('track', 'Purchase', {value: 49.99, currency: 'USD'}, {eventID: eventId});

// Server side: Markt CAPI (send from your backend)
// POST /api/v1/conversions with the same event_id