Projects & Flows

Projects

What Is a Project?

A project is a container for related templates and their flow configuration. Think of it as a workspace for a specific use case or application.

Project Structure

Project
├── Templates
│   ├── welcome-email
│   ├── password-reset
│   └── order-confirmation
└── Flow Graph
    ├── Nodes (templates, outputs, verification)
    └── Edges (connections)

When to Create Projects

Create separate projects for:

• Different applications
• Different email categories (transactional vs marketing)
• Different environments (if needed)

Project Properties

Flows

What Is a Flow?

A flow is a visual representation of what happens when you call the API. It’s a directed graph of nodes and edges that define:

1. Which template to render
2. What validations to run
3. Where to send the output

Flow Graph Model

Flows are stored as nodes and edges:

type ProjectNode = {
  id: string
  type: FlowNodeType
  position: { x: number; y: number }
  data: FlowNodeData
}

type ProjectEdge = {
  id: string
  source: string
  target: string
}

Node Types

Edge Connections

Edges define the flow of data:

• Template → Provider Output (send the email)
• Template → Callback Output (return HTML)
• Template → Verification → Output (validate first)

Flow Execution

When you call /execute:

1. Find template node by templateId
2. Render template with variables
3. Follow edges to output nodes
4. Run verifications (if any)
5. Execute output (send or return)

Execution Order

1. Verifications first - All connected verification nodes run
2. Stop on failure - If verification fails, return error
3. Then outputs - Provider sends, callback returns

Multiple Outputs

If a template connects to multiple outputs:

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

Flow States

No Output Node

If template has no connected output:

• Defaults to callback behavior
• Returns { html, text, subject }

Provider Output

When connected to provider:

• Requires _to in request
• Sends email
• Returns { messageId }

Callback Output

When connected to callback:

• No _to required
• Returns rendered HTML
• You handle sending

Project vs Flow Relationship

Each project has exactly one flow graph that can reference multiple templates.

API Relationship

When calling the API:

{
  "templateId": "tmpl_abc123"
}

The API:

1. Finds the template
2. Gets the template’s project
3. Loads the project’s flow graph
4. Executes according to the flow

Best Practices

Flow Design

• Keep flows simple and linear
• Add verification for user-provided data
• Test with callback output first

Project Organization

• One project per application or use case
• Group related templates together
• Use descriptive project names

Template Placement

• Add templates to the flow when you create them
• Connect to appropriate outputs
• Configure verification as needed