Star
API reference

Campaigns

A campaign is the label you pass as campaign on notify. These endpoints report on everything sent under it.

List campaigns

GET/v1/campaigns

Auth: Project key, or the admin key or a session with x-project-id.

Labels found in the delivery log, most recent activity first. messages counts tasks. Unreadable dates in since or until are ignored.

Query parameters

NameTypeDefaultDescription
limitnumber201 to 100.
searchstringSubstring of the label.
channelstringOnly messages on this channel.
sincedateOnly activity from this time.
untildateOnly activity up to this time.
minMessagesnumberOnly campaigns with at least this many tasks.

Responses

{
  "campaigns": [
    {
      "campaign": "changelog-2026-03",
      "messages": 4812,
      "firstSentAt": "2026-03-02 09:00:00.114+00",
      "lastActivityAt": "2026-03-05 17:41:12.663+00"
    }
  ]
}
{
  "campaigns": []
}

The two times come straight from Postgres aggregates, so they're in Postgres's text format, not ISO 8601.

Common errors (401, 400, 429, 500)
{
  "error": "unauthorized",
  "message": "Invalid or missing API key"
}
{
  "error": "bad_request",
  "message": "x-project-id header or projectId query param required when using admin token"
}
{
  "error": "too_many_requests",
  "message": "Project rate limit exceeded (max 600 req/min)"
}
{
  "error": "internal_error"
}

Example

curl "http://localhost:3000/v1/campaigns?since=2026-03-01" -H "Authorization: Bearer $NK_KEY"
const { campaigns } = await notifkit.listCampaigns({ since: new Date("2026-03-01") });

Get campaign stats

GET/v1/campaigns/{campaign}/stats

Auth: Project key, or the admin key or a session with x-project-id.

Counts are distinct tasks, so opening an email twice counts once. Rates are percentages to two decimals, or null when the denominator is zero. deliveryRate and bounceRate are against sent, and the other rates against delivered. byChannel has the counts per channel, without rates.

Opens and clicks come from provider webhooks. SMS and push report none, and email reports none without the webhook. Then engagementTracked is false and warnings says so: those figures are untracked, not zero.

Path parameters

NameTypeDescription
campaignstringThe label.

Responses

{
  "campaign": "changelog-2026-03",
  "totals": {
    "sent": 4812,
    "delivered": 4790,
    "failed": 22,
    "opened": 2104,
    "clicked": 388,
    "bounced": 19,
    "complained": 2,
    "unsubscribed": 31,
    "deliveryRate": 99.54,
    "openRate": 43.92,
    "clickRate": 8.1,
    "bounceRate": 0.39,
    "complaintRate": 0.04,
    "unsubscribeRate": 0.65
  },
  "byChannel": {
    "email": {
      "sent": 4812,
      "delivered": 4790,
      "failed": 22,
      "opened": 2104,
      "clicked": 388,
      "bounced": 19,
      "complained": 2,
      "unsubscribed": 31
    }
  },
  "engagementTracked": true,
  "warnings": []
}
{
  "campaign": "irrops-2026-09-12",
  "totals": {
    "sent": 1200,
    "delivered": 1180,
    "failed": 20,
    "opened": 0,
    "clicked": 0,
    "bounced": 0,
    "complained": 0,
    "unsubscribed": 0,
    "deliveryRate": 98.33,
    "openRate": 0,
    "clickRate": 0,
    "bounceRate": 0,
    "complaintRate": 0,
    "unsubscribeRate": 0
  },
  "byChannel": {
    "push": {
      "sent": 800,
      "delivered": 790,
      "failed": 10,
      "opened": 0,
      "clicked": 0,
      "bounced": 0,
      "complained": 0,
      "unsubscribed": 0
    },
    "sms": {
      "sent": 400,
      "delivered": 390,
      "failed": 10,
      "opened": 0,
      "clicked": 0,
      "bounced": 0,
      "complained": 0,
      "unsubscribed": 0
    }
  },
  "engagementTracked": false,
  "warnings": [
    "Opens and clicks are not reported on push, sms — those figures are not tracked, not zero."
  ]
}
{
  "campaign": "welcome-batch-7",
  "totals": {
    "sent": 300,
    "delivered": 297,
    "failed": 3,
    "opened": 0,
    "clicked": 0,
    "bounced": 0,
    "complained": 0,
    "unsubscribed": 0,
    "deliveryRate": 99,
    "openRate": 0,
    "clickRate": 0,
    "bounceRate": 0,
    "complaintRate": 0,
    "unsubscribeRate": 0
  },
  "byChannel": {
    "email": {
      "sent": 300,
      "delivered": 297,
      "failed": 3,
      "opened": 0,
      "clicked": 0,
      "bounced": 0,
      "complained": 0,
      "unsubscribed": 0
    }
  },
  "engagementTracked": false,
  "warnings": [
    "No engagement events recorded. If the provider webhook is not configured, opens and clicks cannot be tracked and will stay at zero."
  ]
}
{
  "error": "not_found",
  "message": "No messages recorded for campaign 'changelog-2026-03'"
}
Common errors (401, 400, 429, 500)
{
  "error": "unauthorized",
  "message": "Invalid or missing API key"
}
{
  "error": "bad_request",
  "message": "x-project-id header or projectId query param required when using admin token"
}
{
  "error": "too_many_requests",
  "message": "Project rate limit exceeded (max 600 req/min)"
}
{
  "error": "internal_error"
}

Example

curl http://localhost:3000/v1/campaigns/changelog-2026-03/stats -H "Authorization: Bearer $NK_KEY"
const { totals, warnings } = await notifkit.getCampaignStats("changelog-2026-03");