Campaigns Overview

A campaign is the unit MachFive generates from: it bundles a target audience, chosen assets (social proof, lead magnets, risk reversal, value propositions), and the resulting email instructions. Once a campaign is built (overall: ready), you generate personalized sequences against it for one lead or many.

This section groups everything about the Campaign resource:

• List campaigns — discover campaigns by name or ID.
• Create & build a campaign — the step-by-step HITL build flow.
• Build status — poll a campaign's per-stage readiness.
• Update, delete & branch — rename, delete (data-preserving), branch.
• Selections — read the campaign's chosen assets + target audience.
• Documents — campaign research/strategy documents (signed downloads).

Generation endpoints that run against a campaign — generate, generate batch, preview, and email signatures — live in the Generation section.

---

The campaign object

Field	Type	Description
id	string (UUID)	Campaign ID; use in generate, generate-batch, and all campaign sub-resources.
name	string	Display name (project_name).
status	string	Always "draft" (returned only by POST /api/v1/campaigns; not included in the list response). Build readiness is reported separately by build-status.overall, not this field.
created_at	string (ISO 8601)	Creation time.

---

Build lifecycle (HITL)

Campaigns are built the same way the in-app wizard does it — each step is its own API call, so you can keep a human in the loop. The expensive AI stages run asynchronously; you poll a job (or the derived build status) until the campaign is ready.

In the app, all five steps look and feel the same: pick from a dropdown (or enter your own), then submit. The API follows the same mental model — list options, then submit your choice — even though target audience uses different endpoint names (see Why target audience is shaped differently below).

The five steps (uniform pattern)

Step	In the app	List options	Submit choice
1. Target audience	Pick a segment	GET /api/v1/target-audiences	POST /api/v1/campaigns/:id/target-audience
2. Social proof	Pick checkboxes	GET .../assets/social_proof/options	PUT .../assets/social_proof/selection
3. Lead magnet	Pick checkboxes	GET .../assets/lead_magnet/options	PUT .../assets/lead_magnet/selection
4. Risk reversal	Pick checkboxes	GET .../assets/risk_reversal/options	PUT .../assets/risk_reversal/selection
5. Value proposition	Pick checkboxes	POST .../assets/value_proposition/generate then GET .../options	PUT .../assets/value_proposition/selection

After step 5, poll GET /api/v1/campaigns/:id/build-status until overall is ready.

Full endpoint sequence

POST /api/v1/campaigns                                          → create shell
GET  /api/v1/target-audiences                                  → list TA options (workspace)
POST /api/v1/campaigns/:id/target-audience                      → submit TA (kicks background research)
GET  /api/v1/campaigns/:id/assets/social_proof/options
PUT  /api/v1/campaigns/:id/assets/social_proof/selection
GET  /api/v1/campaigns/:id/assets/lead_magnet/options
PUT  /api/v1/campaigns/:id/assets/lead_magnet/selection
GET  /api/v1/campaigns/:id/assets/risk_reversal/options
PUT  /api/v1/campaigns/:id/assets/risk_reversal/selection
POST /api/v1/campaigns/:id/assets/value_proposition/generate    → generate VP options
GET  /api/v1/campaigns/:id/assets/value_proposition/options
PUT  /api/v1/campaigns/:id/assets/value_proposition/selection   → submit VPs (kicks build chain)
GET  /api/v1/campaigns/:id/build-status                         → poll until overall = ready

Ordering: create → target-audience → (social_proof, lead_magnet, risk_reversal) → value_proposition/generate → value_proposition/selection → poll build-status. The SP/LM/RR steps can be submitted while target-audience research runs in the background (their options are workspace-level and don't depend on it). Value-proposition generation's enforced precondition is that the social_proof, lead_magnet, and risk_reversal selections are submitted (it returns 409 NOT_READY otherwise); submit the target audience earlier in the flow as shown.

Why target audience is shaped differently

Target audience is not a campaign asset checkbox — it is a reusable workspace segment (firmographics, decision-makers, source) stored in its own table and populated during onboarding market research. A campaign links one segment and then runs campaign-specific background research for that choice.

That is why step 1 uses different endpoints than steps 2–5:

	Target audience (step 1)	Assets (steps 2–5)
What you pick from	Workspace segments (GET /api/v1/target-audiences)	Generated checkbox inventories (GET .../assets/:type/options)
What submit does	Creates or updates a segment entity, links it to the campaign, kicks the background research	Idempotent upsert of chosen checkbox ids into the campaign's selection
HTTP verb	POST — submit a segment definition and start async research	PUT — replace the selection for this step (safe to retry)

There is no PUT .../assets/target_audience/selection because a target audience is not a per-campaign checkbox pick — it is a first-class segment you reuse across campaigns. The API shape reflects the data model, not an arbitrary split.

Value propositions are the only asset step that adds an extra generate call (POST .../value_proposition/generate) because VP options are synthesized per campaign from your TA + SP/LM/RR choices, whereas SP/LM/RR options are pre-generated at workspace onboarding.

No credits are charged for building a campaign; builds are gated by your plan's campaign build limit. Credits are only charged later, at email generation / preview time.

See Create & build a campaign for the full request/response of each step.