Journeys

Build multi-step email sequences with delays, branching, and event-triggered execution.

Journeys are automated multi-step email sequences. Define a series of steps — sends, delays, branches — and Molted Email executes them when a trigger event fires.

Create a journey

POST https://api.molted.email/v1/journeys

curl

curl -X POST https://api.molted.email/v1/journeys \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "tenantId": "tenant_abc123",
    "name": "Onboarding sequence",
    "triggerEvent": "user_signed_up",
    "status": "draft"
  }'

Field	Type	Required	Description
`tenantId`	`string`	Yes	Your tenant identifier.
`name`	`string`	Yes	Journey name.
`triggerEvent`	`string`	Yes	Event that starts the journey for a contact.
`status`	`string`	No	Initial status: `draft` or `active`. Defaults to `draft`.

List journeys

GET https://api.molted.email/v1/journeys

curl

curl "https://api.molted.email/v1/journeys?tenantId=tenant_abc123" \
  -H "Authorization: Bearer YOUR_API_KEY"

Get journey details

GET https://api.molted.email/v1/journeys/:id

curl

curl https://api.molted.email/v1/journeys/JOURNEY_ID \
  -H "Authorization: Bearer YOUR_API_KEY"

Update a journey

PATCH https://api.molted.email/v1/journeys/:id

curl

curl -X PATCH https://api.molted.email/v1/journeys/JOURNEY_ID \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Updated onboarding",
    "status": "active"
  }'

Add a step

POST https://api.molted.email/v1/journeys/:id/steps

curl

curl -X POST https://api.molted.email/v1/journeys/JOURNEY_ID/steps \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "send",
    "config": {
      "templateId": "welcome-email",
      "payload": { "subject": "Welcome!", "html": "<h1>Welcome</h1>" }
    },
    "position": 1
  }'

Step types

Type	Description	Config fields
`send`	Send an email using a template.	`templateId`, `payload`
`delay`	Wait before executing the next step.	`delayMinutes`
`branch`	Route to different paths based on conditions.	`conditions` (field, operator, value)
`end`	Mark the journey run as complete.	—

Branch conditions support these operators: eq, neq, gt, lt, contains, exists.

Branch step example

Branch step config

{
  "type": "branch",
  "config": {
    "conditions": [
      { "field": "lifecycleStage", "operator": "eq", "value": "customer" }
    ],
    "onMatch": { "nextStep": 3 },
    "onNoMatch": { "nextStep": 5 }
  },
  "position": 2
}

When the conditions match, the run advances to onMatch.nextStep; otherwise it follows onNoMatch.nextStep.

List journey runs

GET https://api.molted.email/v1/journeys/:id/runs

curl

curl "https://api.molted.email/v1/journeys/JOURNEY_ID/runs?tenantId=tenant_abc123" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

[
  {
    "id": "run_abc123",
    "journeyId": "JOURNEY_ID",
    "contactId": "contact_123",
    "currentStep": 2,
    "status": "active",
    "createdAt": "2026-03-01T12:00:00Z"
  }
]

How journeys execute

When a trigger event fires, a journey run is created for the matching contact.
Each contact is deduplicated per journey — a contact can only have one active run per journey.
Steps execute in order. delay steps schedule the next step after the configured wait time.
branch steps evaluate conditions and route to the appropriate path.
The run completes when it reaches an end step.

On this page