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
| Route | Permission | What it does |
|---|---|---|
GET /v1/campaigns/summary | customers.view | Counts for the campaign dashboard |
GET /v1/campaigns | customers.view | The newest 100 campaigns. Optional status and channel filters. |
GET /v1/campaigns/:id | customers.view | One campaign, with its newest 50 recipients |
POST /v1/campaigns | customers.edit | Create a draft |
PATCH /v1/campaigns/:id | customers.edit | Edit any campaign that is not sent |
POST /v1/campaigns/:id/send | customers.edit | Always refused today (see below) |
POST /v1/campaigns/:id/cancel | customers.edit | Cancel a draft |
DELETE /v1/campaigns/:id | customers.edit | Delete 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:
| Field | Type |
|---|---|
description | string, up to 1,000 characters |
templateName | string, up to 120 characters |
messageBody | string, up to 4,096 characters |
quickReplies | up to 3 strings of up to 20 characters |
mediaUrl | URL |
audienceFilter | see below |
scheduledAt | ISO-8601 date-time. Stored only: nothing sends at that time. |
abEnabled, abVariantB | A/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_CHANNELSis empty) - Request schema and enums:
packages/shared-types/src/campaigns.ts - Default status:
model Campaigninpackages/db/prisma/schema.prisma - 409 checked against a running API on 2026-10-20 (draft created, send refused, draft deleted)