Marketing Events API

Overview

Marketing Events is the raw and aggregated event stream underlying engagement and analytics features across Campaigns and Subscribers — email events (opens, clicks, bounces, deliveries) sourced from SparkPost, website events, and events sourced from the HubSpot integration. This page also documents the top-level Subscriber–Campaign Engagements query, which reads pre-aggregated engagement documents across campaigns and subscribers rather than raw events.

If you only need engagement data scoped to one resource, the resource-scoped endpoints may be simpler:

• POST /api/campaigns/{campaignCode}/engagements — see Marketing Campaigns API.
• POST /api/subscribers/{subscriberId}/engagements — see Marketing Subscribers API.

Authentication

All endpoints require API key authentication:

X-API-Key: your-api-key-here

Get HubSpot events

GET /api/marketing_events/hubspot

Fetches events sourced from the HubSpot integration for a given recipient.

Query parameters

Parameter	Type	Required	Description
recipient	string (email)	Yes	Recipient email address.
campaignId	string	No	Filter by HubSpot campaign ID.
eventType	string	No	Filter by event type.
startTimestamp	string	No	Range start.
endTimestamp	string	No	Range end.
page	integer	Yes	Page number, 1-based.
limit	integer	Yes	Items per page.

Example response

{
  "total": 1,
  "totalPages": 1,
  "results": [
    {
      "id": "evt_123",
      "appId": 12345,
      "created": 1735689600,
      "type": "OPEN",
      "recipient": "visitor@example.com",
      "subject": "Welcome!",
      "deviceType": "desktop"
    }
  ]
}

Get marketing events

POST /api/marketing_events

Bulk/filtered fetch across the event store. Events are a discriminated union — source: "email" events carry an email object; source: "website" events carry a website object.

Request body

{
  "page": 1,
  "limit": 50,
  "filters": {
    "campaign_code": { "operation": "eq", "value": "SUMMER-SALE-2024" }
  }
}

Example response (email event)

{
  "results": [
    {
      "id": "evt_9kL3mP5n",
      "timestamp": "2026-01-01T09:15:00.000Z",
      "subscriber_id": "sub_123456",
      "campaign_code": "SUMMER-SALE-2024",
      "source": "email",
      "type": "open",
      "email": {
        "template_id": "email_xyz789ghi012",
        "recipient_address": "visitor@example.com",
        "subject": "Summer Sale Starts Now"
      }
    }
  ],
  "total": 1,
  "totalPages": 1
}

Example response (website event)

{
  "results": [
    {
      "id": "evt_9kL3mP5o",
      "timestamp": "2026-01-01T10:31:05.000Z",
      "subscriber_id": "sub_123456",
      "source": "website",
      "type": "_page_view",
      "website": {
        "website_id": "site_main",
        "page_url": "/products/outdoor",
        "device_type": "desktop"
      }
    }
  ],
  "total": 1,
  "totalPages": 1
}

Search marketing events

POST /api/marketing_events/search

Runs a named search/aggregation query over the event store. The available named queries are:

Query name	Vars	Returns
getCampaignEngagedSubscribersCount	campaignCode, marketingEmailId	Count of engaged subscribers, grouped by event type.
listDistinctSubscribers	page, limit, eventTypes[], campaignCode, marketingEmailId, subscriberId?	Distinct subscribers who engaged with a campaign.

Example request

{
  "query": {
    "name": "getCampaignEngagedSubscribersCount",
    "vars": {
      "campaignCode": "SUMMER-SALE-2024",
      "marketingEmailId": "email_xyz789ghi012"
    }
  }
}

Example response

{
  "queryName": "getCampaignEngagedSubscribersCount",
  "result": { "open": 3640, "click": 1305, "unsubscribed": 45 }
}

Subscriber–Campaign Engagements

POST /api/subscriber-campaign-engagements/list

Queries pre-aggregated engagement documents directly, without pinning to a single campaign or subscriber — useful for cross-cutting reporting/exports. Each result mirrors an engagement snapshot: delivery/open/click counters, clicked-link detail, page-view and purchase attribution, and a computed engagement_score.

Request body

{
  "page": 1,
  "limit": 50,
  "filters": {
    "campaign_code": { "operation": "eq", "value": "SUMMER-SALE-2024" }
  }
}

Example response

{
  "results": [
    {
      "subscriber_id": "sub_123456",
      "campaign_code": "SUMMER-SALE-2024",
      "marketing_email_id": "email_xyz789ghi012",
      "email_sent_at": "2026-01-01T09:00:00.000Z",
      "email_delivered_at": "2026-01-01T09:00:15.000Z",
      "delivery_status": "DELIVERED",
      "open_count": 2,
      "click_count": 1,
      "unique_click_count": 1,
      "clicked_links": [
        {
          "url": "https://example.com/summer-sale",
          "count": 1,
          "first_clicked_at": "2026-01-01T10:31:00.000Z",
          "last_clicked_at": "2026-01-01T10:31:00.000Z"
        }
      ],
      "page_view_count": 8,
      "total_engagement_time_seconds": 840,
      "purchase_count": 1,
      "total_purchase_amount": 149.99,
      "engagement_score": 85.5,
      "updated_at": "2026-01-01T23:59:59.000Z",
      "campaign_metadata": {
        "send_date": "2026-01-01T09:00:00.000Z",
        "subscription_type": "promotional",
        "subject_line": "Summer Sale Starts Now"
      }
    }
  ],
  "total": 1,
  "totalPages": 1
}

delivery_status is one of DELIVERED, SOFT_BOUNCE, HARD_BOUNCE, SPAM, PENDING.

Related

• Marketing Campaigns API — campaign-scoped engagement queries and campaign email metrics.
• Marketing Subscribers API — subscriber-scoped engagement queries.
• Reports API — generate a downloadable export instead of paging through raw events.