Marketing Journeys

Journeys (also called flows) are multi-step automations: a trigger enrolls a contact, then the contact moves from step to step over time. You manage them with the journeys tRPC router on the Platform API, called at /api/trpc/journeys.<procedure> using the tRPC conventions. The procedures (except tick) act on the current site of your session.

Procedures

Input parameters

Common errors:

Triggers

A journey starts when its trigger occurs for a contact:

Steps and timing

Each step has a name (1 to 120 characters), a stepType, a delayMinutes value (an integer from 0 to 525,600, i.e. one year) and, depending on the type, an actionData object. The delay is counted from when the previous step ran: a step with delayMinutes: 4320 runs three days after the one before it. The first step's delay is counted from enrollment.

The status column describes each step type's current behaviour:

A "no effect" step is traversed (the enrollment moves on to the next step), but it changes nothing and sends nothing. Do not rely on it for a business action. When the last step has run, the enrollment is completed.

EMAIL step

The actionData of an EMAIL step accepts:

The email goes to the contact's address; unsubscribed recipients are filtered out. If the send fails (contact without an address, no content), the failure is recorded and the enrollment still moves on to the next step.

updateSteps replaces the whole list: array order becomes step order. A step sent with its existing id is updated in place (in-flight enrollments keep it); a step without an id is created; a step missing from the array is deleted, and enrollments sitting on it are completed.

curl -X POST "https://manage.inklura.fr/api/trpc/journeys.updateSteps" \
  -H "Authorization: Bearer $INKLURA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"json":{"id":"<journey-id>","steps":[
        {"name":"Welcome","stepType":"EMAIL","delayMinutes":0,
         "actionData":{"emailType":"journey.welcome.intro",
                       "fallbackSubject":"Welcome",
                       "fallbackHtml":"<p>Hello,</p>"}},
        {"name":"Follow-up","stepType":"EMAIL","delayMinutes":4320,
         "actionData":{"fallbackSubject":"Getting started",
                       "fallbackHtml":"<p>A few resources to get started.</p>"}}
      ]}}'

Maximum duration

maxDurationDays (on create, or set by the template) caps an enrollment's lifetime: once that many days have passed since enrollment, it is completed without running the remaining steps.

Ready-made templates

listTemplates exposes ready-made journeys; createFromTemplate creates one:

Template emails carry an emailType and French fallback content; configure an email template for that type, or replace the steps with updateSteps, to adapt the text.

How enrollment happens

Automatic enrollment only targets an active journey with the matching trigger (if several match, the one with the lowest priority value). A contact is enrolled only once per journey.

With enroll, clientId wins, then leadId; with only email, the matching lead is found or created. enroll does not check that the journey is active. The response (under result.data.json) reports the outcome:

{ "enrolled": true, "enrollmentId": "<enrollment-id>", "journeyId": "<journey-id>" }

When nothing happens, enrolled is false and reason says why: already-enrolled (the contact is already in this journey) or journey-has-no-steps.

Once a contact is enrolled, the platform advances due enrollments with a scheduled task that calls journeys.tick. You do not need to call it yourself.

Defining and activating a journey

journeys.createFromTemplate         (or: journeys.create + journeys.updateSteps)
        │
        ▼
journeys.activate

To change the steps of an active journey: pause, then updateSteps, then activate.

After activate:

• enrollment happens automatically according to the trigger (see the table above);
• or you enroll contacts manually with journeys.enroll (the MANUAL trigger).

Related

• Scheduled Jobs
• Email & MJML
• tRPC Procedures: how to call journeys.*