FOfolk
Campaigns

Stop a campaign

Changed on

Stop a scheduled or sending campaign, or only some of its recipients. Messages already sent stay sent; those not sent yet are not sent, with notSentReason: "stopped".

Without a body, the whole campaign becomes cancelled: a scheduled campaign sends nothing, and a sending one sends none of its next steps. Stopping a cancelled campaign again leaves it unchanged. A campaign whose last step is already sending can only be stopped for some recipients.

With recipientIds, only their messages not sent yet are stopped and the other recipients still receive theirs. Once no recipient is left to send to, the campaign becomes cancelled, and a scheduled one sends nothing; a campaign whose last step is already sending isn't cancelled: that step ends with the messages already sent. Merged contacts are resolved, and ids that are not recipients of the campaign or have nothing left to send are listed in warnings.

A campaign still processing its messages answers 409 with a Retry-After header. A campaign that is not launched, finished or failed answers 409: delete a draft or in_review campaign instead, or remove recipients from an in_review one with DELETE /v1/campaigns/:campaignId/recipients/:contactId.<br/><Warning>This endpoint is currently in open beta. The API surface may change as we iterate based on feedback.</Warning>

post/v1/campaigns/{campaignId}/stop

Request

  • Base URL
    https://api.folk.app
  • URL
    https://api.folk.app/v1/campaigns/{campaignId}/stop
  • Auth
    HTTP bearer

Path parameters

campaignIdstring required

The ID of the campaign.

Headers

Idempotency-Keystring

A unique key, such as a UUID, that makes retrying this request safe: a retry with the same key and body returns the original response without running the operation again. Keys are kept for 24 hours after the request completes.

Example:8e03978e-40d5-43e8-bc93-6894a57f9324

Request body

recipientIdsstring[]

Stop only these people or companies, at most 100: every message of theirs not sent yet, in every step, is not sent. The other recipients still receive their messages; once no recipient is left to send to, the campaign becomes cancelled, unless its last step is already sending. In review, remove recipients with DELETE /v1/campaigns/:campaignId/recipients/:contactId instead. Omit to stop the whole campaign.

Example request

{
  "recipientIds": [
    "per_55175e81-9a52-4ac3-930e-82792c23499b"
  ]
}

Response

The campaign, once stopped.

deprecationsstring[]

Example response

{
  "data": {
    "id": "cmp_9b2f1c1e-2b8a-4d1e-8f5a-3c2d1e0f9a8b",
    "name": "Q3 outreach",
    "status": "draft",
    "groupId": "grp_bc984b3f-0386-434d-82d7-a91eb6badd71",
    "entityType": "person",
    "steps": [
      {
        "position": 1,
        "sender": {
          "id": "snd_4c3b2a19-8f7e-4d6c-9b5a-1e2f3d4c5b6a",
          "email": "john.doe@example.com",
          "displayName": "John Doe"
        },
        "subject": "Quick question, {{firstName}}",
        "body": "<p>Hi {{firstName}},</p><p>{{signature}}</p>",
        "cc": [],
        "bcc": [],
        "delayDays": 0,
        "sameThread": false,
        "status": "draft",
        "messageCount": 0,
        "sentCount": 0,
        "notSentCount": 0
      },
      {
        "position": 2,
        "sender": {
          "id": "snd_4c3b2a19-8f7e-4d6c-9b5a-1e2f3d4c5b6a",
          "email": "john.doe@example.com",
          "displayName": "John Doe"
        },
        "subject": "",
        "body": "<p>Following up on my last email, {{firstName}}.</p><p>{{signature}}</p>",
        "cc": [],
        "bcc": [],
        "delayDays": 3,
        "sameThread": true,
        "status": "draft",
        "messageCount": 0,
        "sentCount": 0,
        "notSentCount": 0
      }
    ],
    "stopOnReply": true,
    "recipientCount": 12,
    "createdBy": "usr_bc984b3f-0386-434d-82d7-a91eb6badd71",
    "createdAt": "2025-07-17T09:00:00.000Z",
    "updatedAt": "2025-07-17T09:00:00.000Z",
    "scheduledAt": null,
    "startedAt": null,
    "finishedAt": null,
    "error": null
  },
  "deprecations": [
    "This field is deprecated"
  ]
}

Changes