Email Automations

An automation is a sequence of emails sent to a recipient over time, triggered by an event. Think: “when someone signs up, send a welcome email immediately, then a tips email 2 days later, then an upgrade prompt 7 days later.”

How Automations Work

Trigger fires (webhook POST)
    │
    ▼
┌─────────────────────────────────────────────┐
│  Automation Run                              │
│  recipient: alice@example.com                │
│  merge data: {name: "Alice", plan: "pro"}    │
│                                              │
│  Step 0 (0s delay):   "Welcome, Alice!"  ──► sent
│  Step 1 (2d delay):   "Getting started"  ──► scheduled
│  Step 2 (5d delay):   "Go pro?"          ──► queued
│                                              │
│  Status: running  |  Current step: 1         │
└─────────────────────────────────────────────┘

Each step has a delay, a subject template, and a body template. Forge’s scheduler picks up due runs every 5 seconds and sends the next step.

Trigger Types

Trigger	How it fires	Best for
Webhook	Your app POSTs to a unique webhook URL	User signups, purchases, form submissions
Manual	You add recipients from the dashboard	Testing, one-off sequences
Scheduled	Cron-based recurring trigger	Weekly digests, renewal reminders

Creating an Automation

1. Create the automation

Go to System Settings → Email → Automations → Create Automation.

Name:          User Onboarding
Trigger Type:  Webhook
Webhook Slug:  user-onboarding  (auto-generated from name)

2. Add steps

Each step defines when and what to send:

Step 1
  Delay:    0 seconds (immediate)
  Subject:  Welcome to {{app_name}}, {{name}}!
  Text:     Hey {{name}},\n\nThanks for joining the {{plan}} plan!
  HTML:     <h1>Welcome {{name}}!</h1><p>Thanks for joining <strong>{{plan}}</strong>.</p>

Step 2
  Delay:    2 days
  Subject:  Getting started tips for {{name}}
  Text:     Hey {{name}},\n\nHere are 3 tips to get the most out of {{app_name}}...

Step 3
  Delay:    5 days
  Subject:  Ready to upgrade, {{name}}?
  Text:     Hey {{name}},\n\nYou've been on the {{plan}} plan for a week...

3. Activate

Change status from Draft to Active. The webhook URL is now live.

Triggering via Webhook

POST /api/v1/email/automations/webhook/user-onboarding
Content-Type: application/json

{
  "email": "alice@example.com",
  "name": "Alice",
  "app_name": "My SaaS",
  "plan": "pro"
}

Response (202):

{
  "run_id": "run_a1b2c3d4",
  "automation_id": "auto_xyz",
  "status": "running"
}

All fields except email become merge variables available in your templates.

Merge Templates

Use {{variable_name}} in subject and body templates. Supports dot-path for nested JSON:

{{name}}              → "Alice"
{{plan}}              → "pro"
{{metadata.company}}  → "Acme Inc"

Missing variables render as empty string. No conditional logic ({{#if}}) in the current version.

Managing Runs

The Runs tab for each automation shows:

• Recipient email
• Current step number
• Status (running, completed, paused, failed)
• Started at / completed at
• Next send scheduled time

You can pause individual runs (they stop at the current step) or resume them. Completed runs are retained for the log retention period.

Limits

Limit	Value
Max automations per identity	10
Max steps per automation	20
Max concurrent runs per identity	50
Scheduler tick interval	5 seconds (configurable)

Example: Full Welcome Drip

Trigger: Your signup endpoint calls the webhook after creating the user.

# In your signup handler:
await httpx.post(
    "https://forge.yourdomain.com/api/v1/email/automations/webhook/welcome",
    json={
        "email": user.email,
        "name": user.name,
        "plan": user.plan,
        "app_name": "My SaaS"
    }
)

Steps configured in Forge:

Step	Delay	Subject
0	0s	Welcome to My SaaS, {{name}}!
1	2 days	3 tips to get started
2	5 days	Your first week recap
3	14 days	Ready to upgrade from {{plan}}?

Result: Alice gets 4 emails over 2 weeks, each personalized with her name and plan, without any scheduling code in your application.