Marketing Campaigns

Create email campaigns, select subscriber or Customer Group audiences, and interpret delivery outcomes.

Use Marketing Campaigns to compose one-off promotional emails for active subscribers. Campaign reads require read_marketing; creating, editing, launching, cancelling, and deleting require write_marketing. Customer Group selection also requires customer read access. Preview the audience before launch, use the limits and supported channels returned by the API, and preserve ambiguous delivery outcomes during reconciliation.

Choose and preview the audience#

A campaign can target every active email subscriber or one Customer Group. Omit audience_group_id, or send it as null, to target all subscribers. Send a Customer Group UUID to target only customers in that group who are also active email subscribers. Selecting a group requires read_customers in addition to the campaign's marketing scope.

Task	Endpoint	Required scope
List campaigns, limits and available channels	`GET /marketing-campaigns`	`read_marketing`
Preview the current eligible audience	`GET /marketing-campaigns/audience`	`read_marketing`; add `read_customers` when `audience_group_id` is supplied
Create a draft	`POST /marketing-campaigns`	`write_marketing`; add `read_customers` when selecting a group
Update a draft	`PUT /marketing-campaigns/{id}`	`write_marketing`; add `read_customers` when selecting a group
Launch or cancel	`POST /marketing-campaigns/{id}/launch` / `POST /marketing-campaigns/{id}/cancel`	`write_marketing`; launching a group campaign also requires `read_customers`
Delete an eligible campaign	`DELETE /marketing-campaigns/{id}`	`write_marketing`

http

GET /api/2025-01/marketing-campaigns/audience?audience_group_id=58ee109f-64f7-4a51-8d48-b0ca62c4236a

{
  "success": true,
  "data": {
    "group_id": "58ee109f-64f7-4a51-8d48-b0ca62c4236a",
    "group_name": "Recent customers",
    "matching_customers": 148,
    "eligible_email_recipients": 121,
    "ready": true,
    "evaluated_at": "2026-09-12T14:20:00Z",
    "previewed_at": "2026-09-12T14:21:00Z"
  }
}

A preview is a current estimate. matching_customers counts active customer profiles in the selected group, while eligible_email_recipients counts those customers who currently have an active email subscription. For the all-subscribers audience, group_id is null and matching_customers is null. If ready is false, wait for the group to refresh and preview it again before launching. A deleted or cross-store group returns MARKETING_AUDIENCE_NOT_FOUND; a group that is still refreshing at launch returns MARKETING_AUDIENCE_REFRESHING.

Create and update a draft#

Create an email campaign with name, channel, subject, preheader, email_document, and an optional audience_group_id. Read limits and supported_channels from the list response instead of hard-coding field lengths or channel availability. Although campaign records can represent other channels, the current supported_channels response is authoritative and launching currently supports email only.

json

// POST /api/2025-01/marketing-campaigns
{
  "name": "September customers",
  "channel": "email",
  "subject": "A thank-you for shopping with us",
  "preheader": "Your subscriber offer is inside",
  "email_document": {
    "root": { "type": "EmailLayout", "data": {} }
  },
  "audience_group_id": "58ee109f-64f7-4a51-8d48-b0ca62c4236a"
}

Only drafts can be edited. On update, omitting audience_group_id preserves the current audience; sending null changes it to all subscribers. The selected audience membership freezes when launch succeeds. The resolved sender and rendered delivery content freeze when processing reaches the first recipient who is still eligible to receive the campaign; subsequent recipients and retries reuse that delivery snapshot. A concurrent draft edit can make launch stale, in which case review the latest draft before retrying.

Interpret delivery outcomes#

Campaign responses return recipient_count, sent_count, failed_count, suppressed_count, and uncertain_count as integer counts. Recipient membership stays frozen after launch. The resolved sender and rendered delivery content use the delivery snapshot described above. Tringify still checks each recipient's current email consent before provider submission, so a recipient who unsubscribes after launch is suppressed instead of sent.

Field	Meaning
`sent_count`	The email provider accepted the submission. This does not prove inbox delivery.
`failed_count`	The submission ended with a confirmed failure.
`suppressed_count`	Tringify did not submit the message, for example because consent was no longer active or cancellation stopped a pending recipient.
`uncertain_count`	The provider outcome is not yet known, including a timeout after submission began or a cancellation racing an in-flight attempt.