> ## Documentation Index
> Fetch the complete documentation index at: https://developer.folk.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Campaigns

A campaign sends emails to a list of people or companies, from one of the workspace's senders. It is the API equivalent of the campaigns of the app: a campaign created through the API opens in the app like one created there, and the other way round.

> [!NOTE]
>
> The campaign endpoints are in beta: through the API, you can read campaigns
> and create, edit and delete drafts. Review and launch them in the app.

## Campaign, step and message

* A **campaign** is what the app calls a campaign: its recipients, its steps and its status.
* A **step** is one email of the campaign: a template, written once with `{{variables}}`, and sent to every recipient. The first step is the first email; the next ones are follow-ups, sent a number of days after the previous step, in the same email thread or not. A campaign with more than one step is what the app calls a sequence.
* A **message** is the version of a step for one recipient, with the variables filled in. There is one message per recipient and per step.

For example, a campaign to 50 people with a first email and one follow-up has 2 steps and 100 messages. The first step reads `Hi {{firstName}}`, and the message to Alice reads `Hi Alice`.

## Writing a step

The subject is plain text and the body is HTML, with variables written `{{key}}`, such as `{{firstName}}`. The [create endpoint](https://developer.folk.app/api-reference/campaigns/create-a-campaign.md) lists every variable. 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.

Set `bodyFormat: "text"` to write the body as plain text: a blank line starts a new paragraph, and a single newline is a line break. Bodies always read back as HTML.

To sign a step with the sender's signature, end its body with `<p>{{signature}}</p>`, and don't write the signature yourself. A body without `{{signature}}` is sent unsigned. When you write back a body you read, the token keeps the step's signature as it is, even if it was edited in the app.

## Recipients

A campaign sends to people or to companies, never both. Pick its recipients from a list of ids, or from the contacts of a group, optionally filtered with the [filter syntax](https://developer.folk.app/api-reference/people/list-people.md) of the people and companies endpoints. Recipients you can't access are skipped, and recipients without an email address get no message: both are listed in the `warnings` of the response.

## Senders

Every step is sent from a sender of the workspace, set up in the app. Write it as `{ "id": "snd_…" }` or `{ "email": "…" }`, either once for every step, or on every step. Without one, the campaign uses the sender you last used. Gmail senders can only send campaigns with a single step.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.