Update wiki

This commit is contained in:
Dries Augustyns
2025-12-07 10:25:18 +01:00
parent b2ecf60a13
commit 0003e44db8
23 changed files with 3336 additions and 5 deletions
@@ -0,0 +1,135 @@
---
title: Conditional Branching
description: If/then logic in workflows
icon: GitBranch
---
## Overview
Conditions split workflows into two paths based on contact data.
```
[Condition: plan equals "premium"]
├─ True → [Send: Premium features]
└─ False → [Send: Upgrade offer]
```
Both paths required.
## Operators
| Operator | Use | Example |
|----------|-----|---------|
| `equals` | Exact match | `plan equals "pro"` |
| `notEquals` | Not matching | `plan notEquals "free"` |
| `contains` | Substring | `company contains "tech"` |
| `greaterThan` | Greater than | `mrr greaterThan 100` |
| `lessThan` | Less than | `loginCount lessThan 5` |
| `greaterThanOrEqual` | Greater than or equal | `age greaterThanOrEqual 18` |
| `lessThanOrEqual` | Less than or equal | `daysInactive lessThanOrEqual 30` |
| `exists` | Has value | `company exists` |
| `notExists` | Missing/null | `lastName notExists` |
| `startsWith` | Prefix | `coupon startsWith "SAVE"` |
| `endsWith` | Suffix | `email endsWith "@company.com"` |
**Important:** Numeric operators require field stored as number, not string.
## Common patterns
### Filter by plan
```
[Condition: plan equals "enterprise"]
├─ True → [Send: Enterprise onboarding]
└─ False → [Send: Standard onboarding]
```
### Activity check
```
[Condition: loginCount greaterThan 10]
├─ True → [Send: Power user tips]
└─ False → [Send: Getting started]
```
### Nested conditions
Chain for multi-tier logic:
```
[Condition: plan equals "enterprise"]
├─ True → [Send: Enterprise email]
└─ False ↓
[Condition: plan equals "pro"]
├─ True → [Send: Pro email]
└─ False → [Send: Free email]
```
### Multiple field checks (AND)
Nest conditions:
```
[Condition: plan equals "pro"]
├─ True ↓
│ [Condition: trialDaysLeft lessThan 3]
│ ├─ True → [Send: Trial ending]
│ └─ False → [Exit]
└─ False → [Exit]
```
Matches: `plan = "pro"` AND `trialDaysLeft < 3`
## Nested data
Access with dot notation:
```json
{
"field": "preferences.newsletter",
"operator": "equals",
"value": true
}
```
## Best practices
**Store correct types** — `99` (number) not `"99"` (string) for numeric comparisons.
**Check existence first** — If field might not exist:
```
[Condition: mrr exists]
├─ True → [Condition: mrr greaterThan 100]
└─ False → [Exit]
```
**Limit nesting** — More than 3 levels gets hard to maintain. Use separate workflows.
**Test both paths** — Verify true and false outcomes work.
**Use segments when filtering many** — Segment-based triggers more efficient than in-workflow conditions for large audiences.
## Common mistakes
**Case sensitivity** — `equals "Pro"` doesn't match `"pro"`
**Type mismatch** — `"100" greaterThan 50` fails (string vs number)
**Missing both paths** — Every condition needs true AND false connections
## Debugging
Check contact data first:
```bash
curl -X GET {{API_URL}}/contacts/contact_id \
-H "Authorization: Bearer sk_your_secret_key"
```
Verify field names and types match your condition.
## Next steps
- [See workflow patterns](/automation-patterns/workflow-patterns)
- [Build segments](/guides/segments) for trigger filtering
@@ -0,0 +1,53 @@
---
title: Automation Patterns
description: Workflow patterns and examples
icon: Zap
---
## Learn workflows
<Cards>
<Card icon="Workflow" title="Visual Builder Guide" href="/automation-patterns/visual-builder-guide">
Use the drag-and-drop workflow editor
</Card>
<Card icon="Layers" title="Workflow Patterns" href="/automation-patterns/workflow-patterns">
Common workflow examples
</Card>
</Cards>
## By use case
<Cards>
<Card icon="Users" title="Onboarding" href="/automation-patterns/onboarding-sequences">
Welcome and activate new users
</Card>
<Card icon="Lightbulb" title="Engagement" href="/automation-patterns/engagement-campaigns">
Drive feature adoption
</Card>
<Card icon="RefreshCw" title="Retention" href="/automation-patterns/retention-automation">
Prevent churn and win back users
</Card>
<Card icon="CreditCard" title="Transactional" href="/automation-patterns/transactional-workflows">
Order confirmations and receipts
</Card>
</Cards>
## Advanced
<Cards>
<Card icon="GitBranch" title="Conditional Branching" href="/automation-patterns/conditional-branching">
If/then logic in workflows
</Card>
<Card icon="Database" title="Execution Context" href="/automation-patterns/advanced-execution-context">
Pass event data through workflows
</Card>
<Card icon="Bug" title="Troubleshooting" href="/automation-patterns/troubleshooting-workflows">
Debug workflow issues
</Card>
</Cards>
@@ -0,0 +1,15 @@
{
"title": "Automation Patterns",
"pages": [
"index",
"visual-builder-guide",
"workflow-patterns",
"onboarding-sequences",
"engagement-campaigns",
"retention-automation",
"transactional-workflows",
"conditional-branching",
"advanced-execution-context",
"troubleshooting-workflows"
]
}
@@ -0,0 +1,258 @@
---
title: Visual Workflow Builder
description: Build workflows with drag-and-drop
icon: Workflow
---
## Overview
The workflow builder is a node-based visual editor for creating email automation. Each node is a step (send email, delay, condition, etc.) and connections define the flow.
## Canvas controls
- **-** / **+** - Zoom out/in
- **Fit** - Center and zoom to show entire workflow
- **Auto-Layout** - Automatically arrange nodes
- **Minimap** - Toggle overview map (bottom right)
## Step types
### Trigger
The starting point. Every workflow has one trigger.
**Types:**
- Event (e.g., `user_signed_up`)
- Segment entry/exit
- Schedule (cron)
Cannot be deleted.
### Send Email
Sends an email to the contact.
**Configuration:**
- Template (required)
- Variables (optional overrides)
Contact must be subscribed for marketing templates. Transactional templates send regardless.
### Delay
Pauses execution for a specified time.
**Configuration:**
- Duration: Number
- Unit: Minutes, Hours, or Days
**Example:** Delay 24 hours before next email.
### Wait for Event
Pauses until an event occurs or timeout is reached.
**Configuration:**
- Event name
- Timeout duration (optional)
**Requires two outgoing connections:**
- Event triggered path
- Timeout path
**Example:**
```
[Wait for: purchase_completed, timeout: 48h]
├─ Purchased → Send thank you
└─ Timeout → Send discount reminder
```
### Condition
Branches workflow based on contact data.
**Configuration:**
- Field to check
- Operator (equals, contains, greaterThan, etc.)
- Value to compare
**Requires two outgoing connections:**
- True path
- False path
**Example:**
```
[Condition: plan equals "premium"]
├─ True → Send premium features
└─ False → Send upgrade offer
```
### Webhook
Sends HTTP request to external URL.
**Configuration:**
- URL
- Method (GET, POST, PUT, DELETE)
- Headers (optional)
- Body (JSON, optional)
**Example:** Update CRM when workflow completes.
### Update Contact
Updates contact data fields.
**Configuration:**
- Fields: Key-value pairs
**Example:**
```
Fields:
onboardingCompleted: true
lastWorkflowStep: "welcome_series_done"
```
### Exit
Ends workflow execution. Can have multiple exit points for different paths.
## Building a workflow
### Add a step
**Method 1:** Click **+** button below any node
**Method 2:** Drag step type from sidebar onto canvas
### Configure a step
1. Click node to select
2. Right panel opens
3. Fill required fields
4. Save
### Connect steps
Connections auto-create when using + button. To manually connect:
1. Drag from node's bottom handle
2. Drop on another node's top handle
### Arrange layout
Click **Auto-Layout** for automatic top-to-bottom arrangement.
## Example workflows
### Linear sequence
```
[Trigger: user_signed_up]
[Send: Welcome]
[Delay: 24h]
[Send: Feature tour]
[Exit]
```
### With condition
```
[Trigger: trial_started]
[Send: Welcome]
[Condition: plan equals "enterprise"]
├─ True → [Send: Enterprise onboarding]
└─ False → [Send: Standard onboarding]
```
### With event wait
```
[Trigger: cart_abandoned]
[Delay: 1h]
[Send: First reminder]
[Wait for: purchase_completed, timeout: 23h]
├─ Purchased → [Exit]
└─ Timeout → [Send: Discount offer] → [Exit]
```
## Validation
The builder validates in real-time. Red border = error.
**Common errors:**
- "No outgoing connections" → Add connection to next step
- "Wait for Event requires two paths" → Add event + timeout paths
- "Condition requires true and false paths" → Add both paths
- "Template not found" → Select valid template
## Testing
### Manual execution
1. **Workflows** → Your workflow → **Executions**
2. **Create Execution**
3. Select test contact
4. Provide test data (JSON)
5. **Start**
Watch execution progress in real-time.
### Faster testing
For testing delays:
- Temporarily change to 5 minutes instead of days
- Test the flow
- Change back to real durations
## Keyboard shortcuts
| Key | Action |
|-----|--------|
| Delete | Delete selected node |
| Cmd/Ctrl + Z | Undo |
| Cmd/Ctrl + Shift + Z | Redo |
| + / - | Zoom |
| F | Fit to screen |
| Esc | Deselect |
## Troubleshooting
**Workflow not triggering**
- Workflow is enabled (toggle ON)
- Event name matches exactly (case-sensitive)
- Contact exists and is subscribed
**Execution stuck**
- Check delay configuration
- Verify wait timeout hasn't expired
- No circular references
**Email not sending**
- Template exists
- Contact is subscribed
- Variables in data match template
## Best practices
**Keep it simple** - 5-10 steps per workflow. Break complex flows into multiple workflows.
**Descriptive names** - "Send Welcome Email - Day 0" not "Email 1"
**Test first** - Always test with a test contact before enabling.
**Space emails** - Minimum 12-24 hours between emails to avoid fatigue.
## Next steps
- [Build your first workflow](/tutorials/welcome-series-workflow)
- [Workflow patterns](/automation-patterns/workflow-patterns)
- [Conditional branching](/automation-patterns/conditional-branching)
@@ -0,0 +1,294 @@
---
title: Common Workflow Patterns
description: Reusable workflow templates
icon: Layers
---
## Linear sequence
Send a series of emails with delays between them.
```
[Trigger: event]
[Send Email 1]
[Delay]
[Send Email 2]
[Delay]
[Send Email 3]
[Exit]
```
**Use for:**
- Onboarding series
- Educational drip campaigns
- Feature introduction sequences
**Example timing:**
- Day 0: Welcome
- Day 1: Getting started guide
- Day 3: Tips and tricks
- Day 7: Feature deep dive
## Wait and branch
Pause for an event, then branch based on outcome.
```
[Trigger: event]
[Wait for Event: timeout X days]
├─ Event occurred → [Send success email] → [Exit]
└─ Timeout → [Send reminder email] → [Exit]
```
**Use for:**
- Trial conversion (waiting for subscription)
- Activation campaigns (waiting for key action)
- Re-engagement (waiting for login)
**Example:**
```
[Trigger: trial_started]
[Send: Welcome to trial]
[Wait for: subscription_created, timeout: 7 days]
├─ Subscribed → [Send: Thanks for subscribing] → [Exit]
└─ Timeout → [Send: Last chance offer] → [Exit]
```
## Conditional branch
Split workflow based on contact data.
```
[Trigger: event]
[Condition: check contact field]
├─ True → [Send email A] → [Exit]
└─ False → [Send email B] → [Exit]
```
**Use for:**
- Personalization by plan/tier
- Segmented messaging
- Feature availability checks
**Example:**
```
[Trigger: signed_up]
[Condition: plan equals "enterprise"]
├─ True → [Send: Enterprise onboarding] → [Exit]
└─ False → [Send: Standard onboarding] → [Exit]
```
## Multi-condition cascade
Chain multiple conditions for complex logic.
```
[Trigger: event]
[Condition: is premium?]
├─ True → [Send: Premium content] → [Exit]
└─ False ↓
[Condition: trial active?]
├─ True → [Send: Trial content] → [Exit]
└─ False → [Send: Free content] → [Exit]
```
**Use for:**
- Tiered content delivery
- Progressive feature reveals
- Access-based messaging
## Wait chain
Multiple wait steps with progressive urgency.
```
[Trigger: cart_abandoned]
[Delay: 1 hour]
[Send: Gentle reminder]
[Wait for: purchase, timeout: 23 hours]
├─ Purchased → [Exit]
└─ Timeout ↓
[Send: Discount offer]
[Wait for: purchase, timeout: 48 hours]
├─ Purchased → [Exit]
└─ Timeout → [Send: Final reminder] → [Exit]
```
**Use for:**
- Cart abandonment
- Multi-touch re-engagement
- Escalating incentives
## Segment entry drip
Triggered when contact joins segment.
```
[Trigger: enters "Inactive Users" segment]
[Send: We miss you]
[Delay: 3 days]
[Condition: still in segment?]
├─ Yes → [Send: Special offer] → [Exit]
└─ No → [Exit]
```
**Use for:**
- Churn prevention
- Win-back campaigns
- Behavior-based sequences
**Important:** Segment must have `trackMembership: true` enabled.
## Schedule with filter
Runs on schedule, filtered by conditions.
```
[Trigger: daily at 9am]
[Condition: trial expires in 3 days]
├─ True → [Send: Trial expiring] → [Exit]
└─ False → [Exit]
```
**Use for:**
- Trial expiration reminders
- Subscription renewal notices
- Scheduled checks with conditional sends
## Update and continue
Modify contact data mid-workflow.
```
[Trigger: signed_up]
[Send: Welcome]
[Update Contact: onboardingStep = 1]
[Delay: 1 day]
[Send: Getting started]
[Update Contact: onboardingStep = 2]
[Exit]
```
**Use for:**
- Tracking workflow progress
- Triggering other systems via segment changes
- Marking completion milestones
## Webhook integration
Call external API during workflow.
```
[Trigger: purchase_completed]
[Send: Order confirmation]
[Delay: 7 days]
[Webhook: Create review request in external system]
[Send: Review request]
[Exit]
```
**Use for:**
- Syncing with CRM
- Triggering other automation tools
- Logging workflow events
## Complex multi-path
Combine patterns for sophisticated flows.
```
[Trigger: trial_started]
[Send: Welcome]
[Delay: 1 day]
[Send: Feature tour]
[Wait for: feature_used, timeout: 3 days]
├─ Used ↓
│ [Send: Great job]
│ ↓
│ [Delay: 3 days]
│ ↓
│ [Condition: trial ending in 1 day]
│ ├─ True → [Send: Upgrade reminder] → [Exit]
│ └─ False → [Exit]
└─ Timeout ↓
[Send: Help offer]
[Wait for: feature_used, timeout: 3 days]
├─ Used → [Send: Nice work] → [Exit]
└─ Timeout → [Update Contact: needs_help = true] → [Exit]
```
**Use for:**
- Advanced onboarding
- Complex user journeys
- Adaptive content delivery
## Best practices
**Keep it simple** — Start with 3-5 steps. Add complexity only when needed.
**Exit explicitly** — Every path should end at an Exit step.
**Handle both outcomes** — Conditions and waits need success + failure paths.
**Test incrementally** — Build and test each section before adding more.
**Use meaningful delays** — Don't spam. Minimum 12-24 hours between emails.
**Name clearly** — "Send Welcome Email - Day 0" not "Email 1".
**Monitor drop-off** — Check execution stats to see where contacts exit.
**Prevent loops** — Never create circular paths. Workflow should always progress forward.
## Performance tips
**Batch schedule triggers** — If using schedules, run at off-peak hours to spread load.
**Limit concurrent waits** — Long waits (weeks/months) keep executions in memory. Use scheduled workflows for very long delays.
**Avoid deep nesting** — More than 3-4 condition levels becomes hard to maintain.
**Use segments over conditions** — If filtering many contacts, segment-based triggers are more efficient than in-workflow conditions.
## Next steps
- [Build conditional logic](/automation-patterns/conditional-branching)
- [Understand execution context](/automation-patterns/advanced-execution-context)
- [Troubleshoot workflows](/automation-patterns/troubleshooting-workflows)