Campaign Stats

Get detailed analytics for a specific campaign with time-series data.

Endpoint


GET /api/campaigns/:id/stats

Path Parameters

Parameter	Type	Description
`id`	`string`	Campaign ID

Query Parameters

Parameter	Type	Default	Description
`period`	`string`	`30d`	Time period for stats

Period Formats

Days: 7d, 30d, 90d - Last N days
Custom Range: YYYY-MM-DD,YYYY-MM-DD - Specific date range

Example Requests

Last 7 Days


curl -X GET "NEXT_PUBLIC_BASE_URL/api/campaigns/clxyz123/stats?period=7d" \
  -H "x-api-key: your-api-key"

Custom Date Range


curl -X GET "NEXT_PUBLIC_BASE_URL/api/campaigns/clxyz123/stats?period=2024-01-01,2024-01-31" \
  -H "x-api-key: your-api-key"

Response Schema

Field	Type	Description
`campaign`	`object`	Campaign information
`campaign.id`	`string`	Campaign ID
`campaign.name`	`string`	Campaign name
`campaign.createdAt`	`string`	ISO 8601 timestamp
`period`	`object`	Requested time period
`period.start`	`string`	Period start date (ISO 8601)
`period.end`	`string`	Period end date (ISO 8601)
`stats`	`object`	Aggregated statistics
`stats.totalEmails`	`number`	Emails sent in period
`stats.totalOpens`	`number`	Total opens in period
`stats.totalClicks`	`number`	Total clicks in period
`stats.openRate`	`number`	Open rate percentage
`stats.clickThroughRate`	`number`	Click-through rate (clicks/opens)
`stats.uniqueRecipients`	`number`	Unique recipient count
`stats.noInteraction`	`number`	Emails with no opens or clicks
`openAndClicks`	`array`	Daily time-series data
`openAndClicks[].date`	`string`	Date (YYYY-MM-DD)
`openAndClicks[].opens`	`number`	Opens that day
`openAndClicks[].clicks`	`number`	Clicks that day
`openAndClicks[].emails`	`number`	Emails sent that day
`topLinks`	`array`	Top performing links
`topLinks[].url`	`string`	Link URL
`topLinks[].clicks`	`number`	Total clicks

Example Response


{
  "campaign": {
    "id": "clxyz123",
    "name": "Welcome Series",
    "createdAt": "2024-01-15T10:30:00.000Z"
  },
  "period": {
    "start": "2024-01-01T00:00:00.000Z",
    "end": "2024-01-31T23:59:59.999Z"
  },
  "stats": {
    "totalEmails": 1250,
    "totalOpens": 856,
    "totalClicks": 302,
    "openRate": 68.48,
    "clickThroughRate": 35.28,
    "uniqueRecipients": 1200,
    "noInteraction": 394
  },
  "openAndClicks": [
    {
      "date": "2024-01-01",
      "opens": 45,
      "clicks": 12,
      "emails": 50
    },
    {
      "date": "2024-01-02",
      "opens": 62,
      "clicks": 18,
      "emails": 55
    }
  ],
  "topLinks": [
    {
      "url": "https://example.com/signup",
      "clicks": 156
    },
    {
      "url": "https://example.com/learn-more",
      "clicks": 89
    },
    {
      "url": "https://example.com/pricing",
      "clicks": 57
    }
  ]
}

Use Cases

Building Custom Dashboards

Use the openAndClicks array to create time-series charts:


const response = await fetch('/api/campaigns/abc123/stats?period=30d', {
  headers: { 'x-api-key': apiKey }
});
const data = await response.json();
 
// Use with chart library
const chartData = data.openAndClicks.map(day => ({
  x: day.date,
  opens: day.opens,
  clicks: day.clicks
}));

Comparing Periods

Compare performance across different time periods:


// This month
const current = await fetch('/api/campaigns/abc123/stats?period=2024-01-01,2024-01-31');
 
// Last month
const previous = await fetch('/api/campaigns/abc123/stats?period=2023-12-01,2023-12-31');

Error Responses

Status	Description
`401 Unauthorized`	Invalid or missing API key
`404 Not Found`	Campaign not found


{
  "error": "Campaign not found"
}