API Reference
Campaigns

Campaigns

Product: Campaigns (module key campaigns).

You can create and edit campaign drafts: a message, a channel and an audience. Sending is not available yet. No channel has a working sender, so POST /v1/campaigns/:id/send refuses every campaign. Nothing is sent and nothing is charged.

Routes

RoutePermissionWhat it does
GET /v1/campaigns/summarycustomers.viewCounts for the campaign dashboard
GET /v1/campaignscustomers.viewThe newest 100 campaigns. Optional status and channel filters.
GET /v1/campaigns/:idcustomers.viewOne campaign, with its newest 50 recipients
POST /v1/campaignscustomers.editCreate a draft
PATCH /v1/campaigns/:idcustomers.editEdit any campaign that is not sent
POST /v1/campaigns/:id/sendcustomers.editAlways refused today (see below)
POST /v1/campaigns/:id/cancelcustomers.editCancel a draft
DELETE /v1/campaigns/:idcustomers.editDelete a campaign. Returns { "ok": true }.

Creating a draft

{
  "name": "Tuesday double points",
  "channel": "whatsapp",
  "templateName": "loyalty_points_reminder",
  "messageBody": "You have points waiting.",
  "audienceFilter": {
    "segments": ["vip", "regular"],
    "marketingConsentRequired": true
  }
}

name (up to 160 characters) and channel are required. channel is one of whatsapp, email, sms or push. Optional fields:

FieldType
descriptionstring, up to 1,000 characters
templateNamestring, up to 120 characters
messageBodystring, up to 4,096 characters
quickRepliesup to 3 strings of up to 20 characters
mediaUrlURL
audienceFiltersee below
scheduledAtISO-8601 date-time. Stored only: nothing sends at that time.
abEnabled, abVariantBA/B variant (messageBody, templateName), stored with the draft

A new campaign always starts as draft.

Audience filter

{
  segments?: ('vip' | 'regular' | 'new' | 'at_risk' | 'lapsed' | 'dormant')[];
  tags?: string[];                     // customers with any of these tags
  minOrders?: number;
  minSpendMinor?: number;              // lifetime spend, in minor units
  marketingConsentRequired?: boolean;  // default true
}

Segments are computed the same way as the CRM module's segments. Unless marketingConsentRequired is false, only customers who gave marketing consent are included. Anonymised customers are always excluded.

Sending

POST /v1/campaigns/:id/send on a draft returns 409:

{
  "error": "channel_unavailable",
  "message": "Sending campaigns is not available yet. Nothing was sent or charged."
}

The campaign stays a draft. Any campaign that is not draft or paused gets a 400 instead.

The status values scheduled, sending, sent and paused exist in the schema, but nothing in the API moves a campaign into them today.

Sources

  • Routes and permissions: apps/api/src/modules/campaigns/campaigns.controller.ts
  • Behaviour, list limits, audience resolution, send refusal: apps/api/src/modules/campaigns/campaigns.service.ts (SENDABLE_CHANNELS is empty)
  • Request schema and enums: packages/shared-types/src/campaigns.ts
  • Default status: model Campaign in packages/db/prisma/schema.prisma
  • 409 checked against a running API on 2026-10-20 (draft created, send refused, draft deleted)