Skip to main content
This workflow separates saved configuration, content generation, message approval, and campaign launch. Use a matching 0.8.0 API host, check workspace capabilities, and treat 503 feature_unavailable as unavailable on that host. Host availability is not guaranteed.

​
Configure an inactive draft

Create an email draft, attach subscribed contacts, then read its configuration. Set an explicitly authorized sender, a supported schedule, and up to ten existing template steps. Use the latest configuration revision as expected_revision for changes. A saved template prompt is configuration; it does not generate or approve personalized content. The legacy direct contact endpoint still requires an email address.

​
Prepare local tasks

Call POST /workspaces/{workspace_id}/campaigns/email/{campaign_id}/preparation with the current expected_revision and campaigns:generate. A 202 response returns an operation. Preparation creates isolated api_prepared task rows for at most 500 contact-step messages before any charge. It does not call AI, approve content, or schedule email. Poll the operation with operations:read and campaigns:read. Continue only while progress can advance. Stop and inspect saved state at awaiting_user_action, needs_reconciliation, or a terminal status. A timeout or unknown outcome is not permission to submit another command; read the original operation and reuse its idempotency key and exact body only to replay that same logical request.

​
Generate only selected previews

List tasks with messages:read, select 1–10 prepared task IDs, and call POST .../generations with the current campaign revision, those IDs, and confirm_credit_use: true. This consumes AI credits. Generation creates reviewable previews; it does not approve or send them. The operation write needs campaigns:generate.

​
Review each exact message

Use GET .../messages/{task_id} to inspect the saved preview. To edit it, send its preview_id and current message expected_revision with messages:write. Re-read and reconcile after stale_revision. Approve an exact preview separately with messages:approve; approval does not launch the campaign. Rejecting a preview can cancel later draft steps and cannot be undone through this API.

​
Review and launch

Read campaign configuration and use its current revision to create POST .../reviews with campaigns:launch-email. A ready review is valid for five minutes; use expires_at as authoritative. If it expires or configuration changes, fetch the latest revision and create a fresh review. Launch only after explicit operator confirmation. Submit the ready review_id and confirm_launch: true to POST .../launch. The 202 operation schedules approved messages through native sending within the configured windows; it does not start an immediate batch or prove delivery. Review creation and launch writes require campaigns:launch-email; polling launch receipts also needs operations:read and campaigns:read. Poll the original operation and stop at awaiting_user_action, needs_reconciliation, or a terminal state. Inspect error_code, operation result, and campaign progress. Resolve the reported issue, reconcile local state, and create a fresh review before a new launch decision. Never automatically retry an unknown outcome. active means scheduled for native dispatch, not delivered; saved progress does not verify provider acceptance or delivery.

​
Limits and access

The HTTP request body is limited to 256 KiB. Durable commands are limited to 64 KiB, except People imports, which allow 128 KiB. Generation accepts 1–10 task IDs per request. Email preparation stops at 500 contact-step messages. API execution is gated by host configuration and workspace authorization. See email setup, campaign setup, idempotency and recovery, and API coverage.