c5728da3037f

latestOpenAPI 3.0.32026-08-10601779.8 KB
Contacts

Apply a tag or list change to every contact matching a filter

Queues one action against every contact the filter matches, applied in chunks in the background. Returns immediately with an id to poll.

Run with dry_run: true first. A dry run reports how many contacts match and changes nothing — it is the only way to catch a filter that matches more than intended, and a bulk write is not undoable. An empty filter (which would match the whole account) is rejected unless it is a dry run.

Per-campaign conditions (opened_campaign_id, not_opened_campaign_id, clicked_campaign_id) are available here but not on GET /contacts, because they are resolved in the background rather than inside a request.

Bulk delete and bulk unsubscribe are deliberately not offered.

post/contacts/bulk-actions

Request body

action'apply_tag' | 'remove_tag' | 'add_to_list' | 'remove_from_list' required
target_idinteger required

The tag id (apply_tag/remove_tag) or list id (add_to_list/remove_from_list)

dry_runboolean

When true, only count the matches — nothing is modified

Response

Queued

idinteger
status'pending' | 'processing' | 'completed' | 'failed'
action'apply_tag' | 'remove_tag' | 'add_to_list' | 'remove_from_list'
target_idinteger
dry_runboolean
filterstring

Human-readable rendering of the filter that was applied

matched_countinteger nullable

Number of contacts the filter matched; null until counted

processed_countinteger
errorstring nullable
started_atstring date-time nullable
completed_atstring date-time nullable