Docs Guides

Flow Builder

Learn how to use the visual flow builder to create email workflows.

Overview

The flow builder is a visual node-based editor for creating email workflows. Connect templates, variables, and outputs to define what happens when you call the API.

Flow Editor Interface

The flow editor shows:

  • Canvas - Drag and connect nodes
  • Node palette - Available node types
  • Minimap - Navigate large flows

Node Types

Variables Node

Displays all variables extracted from a connected template:

  • Shows variable names and defaults
  • Connected automatically when you add a template
  • Visual indicator of what data the template needs

Template Node

Represents an email template:

  • Shows template name and preview
  • Lists extracted variables
  • Connect to output nodes

Provider Output

Sends email via your configured provider:

  • Select which provider to use
  • Requires _to in the API request
  • Returns messageId on success

Callback Output

Returns rendered HTML without sending:

  • No provider needed
  • Returns html, text, and subject
  • Useful for preview or self-managed sending

Verification Node

Validates inputs before proceeding:

  • Email Domain - Validates recipient email
  • Required Fields - Ensures variables are provided
  • Custom Regex - Pattern matching on variables

Building a Flow

Basic Send Flow

  1. Your template appears as a node
  2. Variables are automatically extracted
  3. Add a Provider Output node
  4. Connect template → provider output
  5. Configure which provider to use
[Variables] → [Template] → [Provider Output]

Callback Flow

For rendering without sending:

  1. Add your template
  2. Add a Callback Output node
  3. Connect template → callback output
[Variables] → [Template] → [Callback Output]

Validated Flow

Add verification before sending:

  1. Add your template
  2. Add a Verification node
  3. Configure verification type
  4. Add Provider Output
  5. Connect: template → verification → provider
[Variables] → [Template] → [Verification] → [Provider Output]

Connecting Nodes

  1. Hover over a node’s handle (small circle)
  2. Click and drag to another node’s handle
  3. Release to create a connection

Connection Rules

  • Templates connect to outputs (provider, callback, verification)
  • Verification can chain to other outputs
  • Variables auto-connect to their template

Verification Types

Email Domain

Validates the _to address:

  • Checks email format
  • Verifies domain exists
  • Checks MX records

If validation fails:

{
  "success": false,
  "type": "validation_failed",
  "error": "Invalid email address",
  "field": "_to"
}

Required Fields

Ensures specific variables are provided:

  1. Add verification node
  2. Select “Required Fields”
  3. Choose which variables must be provided

If validation fails:

{
  "success": false,
  "type": "validation_failed",
  "error": "Missing required fields: firstName, orderNumber",
  "field": "firstName"
}

Custom Regex

Validate a variable against a pattern:

  1. Add verification node
  2. Select “Custom Regex”
  3. Enter the regex pattern
  4. Select which variable to validate

Example: Validate phone numbers match a pattern.

Execution Flow

When you call /execute:

  1. Locate template - Find the template node
  2. Hydrate variables - Replace {{var}} with values
  3. Run verifications - Execute any verification nodes
  4. Output - Send via provider or return HTML

Multiple Outputs

A template can connect to multiple outputs:

  • All verifications run first
  • First provider output sends the email
  • Callback outputs return HTML

Best Practices

Keep Flows Simple

  • One template per flow typically
  • Add verification when needed
  • Avoid complex branching

Use Verification Wisely

  • Validate user input (email addresses)
  • Require critical fields
  • Don’t over-verify (adds latency)

Test Your Flows

  1. Create the flow
  2. Use callback output first to test rendering
  3. Switch to provider output for production
  4. Test with real variables

Debugging Flows

Template not found in flow graph

  • Template must be added to the project’s flow
  • Check the flow editor shows the template node

Verification keeps failing

  • Check your verification configuration
  • Test with known-good inputs
  • Review the error message

No output node

  • Connect your template to an output
  • Without an output, the flow defaults to callback behavior