Skip to main content
The campaign tools let an agent read your campaigns, preview how many contacts an audience would reach, and prepare a campaign — but never fire the blast. All five tools require the campaigns:draft scope.
Draft-only, by construction. Every campaign an agent creates or edits is forced server-side into a non-sending draft state (enabled: false). The agent prepares the blast and reports the reach; a human clicks Send in the dashboard. This is an enforced boundary, not a failure — see Safety & Boundaries.

​
Tools

​
list_campaigns

List the account’s campaigns. Takes no arguments. Returns a list of campaigns, each with id (display id), title, message, inbox, campaign_type, campaign_status (scheduled / sending / completed / draft), enabled, audience, audience_count, sent_count, reply_count, and scheduled_at.

​
get_campaign

Fetch one campaign by its display id. Returns the full campaign object.

​
preview_campaign_audience

Preview how many contacts a label-based audience would reach — call this before drafting so you can report the real number. Returns {count: N}.
Audience is numeric label ids, not titles. Resolve ids first with list_labels (scope contacts:manage). Passing a title string yields a zero-reach audience.

​
draft_campaign

Create a campaign in a non-sending draft state. Returns the created draft campaign (campaign_status will be "draft").
A one-off blast goes to a label audience. Preview the reach first, then draft with the label ids.

​
update_campaign_draft

Edit a draft. Only the fields you pass are changed, and the campaign stays a draft. Returns the updated draft campaign.
An agent can edit only its own drafts. Editing a non-draft campaign (scheduled, sending, or completed) returns 403 — surfaced verbatim, e.g. can only edit draft campaigns. This is what prevents an agent from pulling a live campaign back out of the queue or forcing it to send.

​
The send loop

1

Resolve the audience

list_labels → take the numeric ids of the audience labels (contacts are tagged by these).
2

Report the reach

preview_campaign_audience(label_ids=[…]) → show the human the real contact count before anything is drafted.
3

Draft it

draft_campaign(title, message, inbox_id, audience_label_ids=[…]) → the campaign is saved as a non-sending draft.
4

Hand off to a human

Tell the user: “Draft ready — open Campaigns and click Send to blast to N contacts.” The agent stops here; only a human’s dashboard action promotes the draft to a live send.
Never imply the blast was sent. A drafted campaign never auto-sends, no matter how it is scheduled.