FOfolk
Campaigns

Create a campaign

Changed on

Create a draft campaign: one or more steps (the first email, then its follow-ups), each a template with {{variables}} sent to every recipient. A draft opens in the app like one created there, to be reviewed and launched, or edited with PATCH /v1/campaigns/:campaignId.

Variables: For people: {{fullName}}, {{firstName}}, {{lastName}}, {{jobTitle}}, {{description}}, {{urls}}, {{companies.name}}, {{companies.urls}}. For companies: {{name}}, {{description}}, {{fundingRaised}}, {{lastFundingDate}}, {{foundationYear}}, {{industry}}, {{employeeRange}}. Array fields use their first value. A text or numeric custom field of the campaign's group is {{customFieldValues.grp_<uuid>.<field name>}}. A variable without a value for a recipient is removed. Write \{{ for literal braces.

End a body with <p>{{signature}}</p> to sign it with the sender's signature; a body without it is sent unsigned.

With target: "review", the campaign is created, then the messages of every recipient are generated from the steps: it answers 202 with the campaign processing, and the campaign becomes in_review within seconds, to poll with GET /v1/campaigns/:campaignId. If generation fails, it is in_review with an error. A campaign that can't be reviewed, such as one whose first step has no subject, is not created.

Recipients the request names but that you can't access, and recipients without an email address, are listed in warnings. target: "launch" and messages are not supported yet.<br/><Warning>This endpoint is currently in open beta. The API surface may change as we iterate based on feedback.</Warning>

post/v1/campaigns

Request

  • Base URL
    https://api.folk.app
  • URL
    https://api.folk.app/v1/campaigns
  • Auth
    HTTP bearer

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

target'draft' | 'review' | 'launch' required

What to do once the campaign is created. draft stores it, to be finished in the app or edited with PATCH /v1/campaigns/:campaignId. review and launch are not supported yet.

groupIdstring

The group to create the campaign in. Its text and numeric custom fields can be used as variables. Leave it out to send to a list of contacts.

stopOnReplyboolean

Whether the remaining steps stop for a recipient who replied. Defaults to true.

scheduledAtstring date-time

When to send, with launch. Not supported yet.

Example request

{
  "target": "draft",
  "groupId": "grp_bc984b3f-0386-434d-82d7-a91eb6badd71",
  "recipients": {
    "type": "contacts",
    "ids": [
      "per_55175e81-9a52-4ac3-930e-82792c23499b"
    ]
  },
  "steps": [
    {
      "subject": "Quick question, {{firstName}}",
      "body": "<p>Hi {{firstName}},</p><p>{{signature}}</p>"
    },
    {
      "body": "<p>Following up on my last email, {{firstName}}.</p><p>{{signature}}</p>",
      "delayDays": 3,
      "sameThread": true
    }
  ]
}

Response

The campaign created, with its steps.

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