Flows

This guide explains how Flows and Playbooks work, which types are available, and how to configure them through the API. Migrating from legacy Forms? See Migrating from Forms to Flows.

How Flows Work

A Flow is a configurable sequence that performs a task for a CleverReach customer, such as subscribing or unsubscribing contacts or updating their profiles. It has two levels:

• A Playbook is a template that defines the steps and the processes they run.
• A Flow is a customer-specific instance of a Playbook, with its own ID, name and settings.

When someone opens a Flow's public URL, the system loads and runs the processes for each step in order. These processes can display a form, validate input, send an email, or create a contact. In short, the Playbook defines the process, and the Flow is its customer-specific, executable instance.

Playbook Types

Playbook types select a Flow's predefined behavior:

Subscribe

Signup form that sends a confirmation email. The contact is activated after confirmation.

subscribe

Unsubscribe

Unsubscribe form with a confirmation step. The contact is deactivated after confirmation.

unsubscribe

Profile

Loads existing contact data into a form, saves changes, and includes an unsubscribe step.

profile

Landingpage

Displays a landing page without a signup or profile-update flow.

landingpage

Template Variants

These variants reuse a base playbook. The underlying process stays the same. Only the form template changes:

• subscribe_embedded reuses subscribe with a form template that can be embedded directly into a website.
• subscribe_popup reuses subscribe with a form template that displays the signup form in a popup on a website.
• unsubscribe_embedded reuses unsubscribe with a form template that can be embedded directly into a website.

There is no unsubscribe_popup template in the current set. The available unsubscribe variants are unsubscribe and unsubscribe_embedded.

Flow Object

To create a Flow, send POST /flow/flow with these fields:

Field	Type	Description
name	string	Flow name, for example subscribe for News.
description	string	Flow description, for example This Flow subscribes contacts to the newsletter.
playbook	string	Playbook type, for example subscribe. See Playbook Types.
setup	object	Playbook-specific settings. See Setup.

Setup

The setup fields depend on the Playbook. Embedded and popup variants use the setup of their base Playbook and change only the form template.

Sign-up (subscribe)

• upsert: Allows repeated sign-ups with the same email address. Existing recipient data is overwritten.
• tags: Tags assigned to the recipient after the final Flow step.
• domain: Domain used in the form URL.
• page_title: Title shown in the browser tab.
• groupid: Group where new recipients are stored.

New recipients are activated through Double Opt-In. See the Double Opt-In guide.

Unsubscribe (unsubscribe)

• blacklist: Adds unsubscribed recipients to the global blacklist.

  warning

  blacklist adds unsubscribed recipients to the global blacklist. They are excluded from future imports and mailings, and their data is removed from recipient lists and reports.

• domain: Domain used in the form URL.

• page_title: Title shown in the browser tab.

• groupid: Group from which recipients are unsubscribed.

• optouttype: Selects soo, coo, or doo. These correspond to Single Opt-Out, Confirmed Opt-Out, and Double Opt-Out. The selected value determines the step layout used for the process. Embedded forms and popups are limited to doo.

Profile Management (profile)

• domain: Domain used in the form URL.
• page_title: Title shown in the browser tab.
• tags: Tags assigned after the final Flow step.

Landing Page (landingpage)

• domain: Domain used in the landing page URL.
• page_title: Title shown in the browser tab.