Leads

Bulk mutate leads

Apply one operation (set_status, add_tags, remove_tags, or delete) across many leads. Target them by ids; delete also accepts a filter, or all: true to remove every lead. Reply-based statuses can only be set on leads that have already replied.

Requires one of the following scopes: leads:write, leads:all, all:all.

post/v1/campaigns/{cid}/leads/mutate

Request

  • Base URL: https://api.mailbeast.ai
  • URL: https://api.mailbeast.ai/v1/campaigns/{cid}/leads/mutate
  • Auth: HTTP bearer

Path parameters

cidstring uuid required
Example:a7d4e2f1-08b3-4c65-9e7a-1b2c3d4e5f60

Headers

Idempotency-Keystring
Example:a1b2c3d4-e5f6-7890-abcd-ef1234567890

Optional. A unique key you generate (max 255 chars, such as a UUID) that makes this request safe to retry. Retrying with the same key replays the original response instead of repeating the operation. Reusing a key with a different body returns 422.

Request body

operation'set_status' | 'add_tags' | 'remove_tags' | 'delete' required
idsstring[]

Target lead ids. Required for every operation except a filter-based delete.

allboolean

Delete EVERY lead in the campaign. Only valid for delete, and mutually exclusive with ids / filter. Required as an explicit opt-in for mass deletion - an empty filter will NOT delete all.

status'lead_replied_interested' | 'lead_replied_meeting_request' | 'lead_replied_out_of_office' | 'lead_replied_wrong_person' | 'lead_replied_not_interested' | 'lead_replied_unsubscribed' | 'lead_replied_uncategorized' | 'lead_converted' | 'lead_lost' | 'blacklisted'

Required for set_status. Only user-settable statuses are allowed; platform-managed ones such as email_sent or scheduled are rejected. Reply-based statuses (lead_replied_*, lead_converted) require the lead to have already replied. lead_lost and blacklisted can be set at any time.

tagsstring[]

Required for add_tags / remove_tags.

Example request

{
  "ids": [
    "c9e5b1a3-7f24-4d80-a6b9-2e4f8c0d1a37",
    "d1a8f4c6-2b93-4e70-8c15-9f0e3a7d6b52"
  ],
  "filter": {
    "search": "acme",
    "tags": [
      "vip",
      "q4"
    ]
  },
  "tags": [
    "vip",
    "q4"
  ]
}

Response

operation'set_status' | 'add_tags' | 'remove_tags' | 'delete' required
affectednumber required

Number of leads successfully affected.

failednumber required

Number of leads that could not be processed.

errorsstring[]

Per-lead error messages, if any.

Example response

{
  "affected": 42,
  "errors": [
    "2 lead(s) not found in this campaign"
  ]
}

Changes

No recorded changes to this operation across all 1 revision of this API.