Automations

Event-triggered flows with cancelable runs (`publiq.automations`).

The automations resource models a flow as a step graph: an event (triggerEvent) fires the automation, which then walks through wait, condition and action steps (send email, update contact, webhook, etc.) down to an exit. Each trigger creates a trackable, cancelable run.

Starting an automation

Automations are per-contact and event-triggered — you don't "run" an automation directly. To start it for someone, emit the automation's triggerEvent for that contact (by email or contactId) with events.emit. The event payload becomes the variables used in the flow's emails. Remember: the automation must be enabled (enable).

// Start the 'user.signed_up' automation for ONE contact
await publiq.events.emit({
  event: 'user.signed_up',           // must match the automation's triggerEvent
  email: 'ana@example.com',          // or contactId: 'ct_123'
  payload: { first_name: 'Ana', plan: 'Pro' },
});

Contact vs. segment/audience: to start the automation for many contacts at once, use events.emitBatch (a batch of up to 500 events) — e.g. paging through contacts.list(audienceId). For a one-shot send to an entire list, use a broadcast (broadcasts.create with audienceId/segmentId) — that's the resource built for it. Rule of thumb: automation = per-contact, event-driven; broadcast = one-shot to a list.

Method reference

`automations.create`

automations.create(params) → Promise<Automation>

Creates an automation from a steps graph. The first item in the array must be the trigger step; the rest connect via next (linear) or onTrue/onFalse (out of a condition). The automation is created disabled — use automations.enable.

Parameters

Parameter	Type	Description
`name`Required	`string`	Automation name.
`triggerEvent`Required	`string`	Name of the event that starts the flow (e.g. `user.signed_up`). You fire it with `events.emit`.
`fromEmail`Optional	`string`	Sender used by the flow's `send_email` steps.
`steps`Required	`Step[]`	The graph. Each step: `ref` (local key, required), `type` (required — one of 13: `trigger`, `send_email`, `delay`, `wait_for_event`, `condition`, `contact_update`, `contact_delete`, `add_to_segment`, `remove_from_segment`, `split`, `wait_until`, `webhook`, `exit`), `config` (optional — step settings, e.g. `templateId`, `durationMs`, `rule`), `next` (optional — linear edge to another `ref`), `onTrue`/`onFalse` (optional — a `condition`'s branches), `position` (optional).

Returns: The created automation, disabled (enabled: false).

const automation = await publiq.automations.create({
name: 'Welcome flow',
triggerEvent: 'user.signed_up',
fromEmail: 'you@yourdomain.com',
steps: [
  { ref: 'trigger', type: 'trigger', next: 'wait' },
  { ref: 'wait', type: 'delay', config: { durationMs: 3600000 }, next: 'send' },
  { ref: 'send', type: 'send_email', config: { templateKey: 'welcome-email' } },
],
});
console.log(automation.id, automation.enabled); // "aut_...", false

The automation only reacts once its triggerEvent is fired (via `events.emit` — see Events) and only while it is enabled. Newly created, it starts disabled.

`automations.get`

automations.get(id) → Promise<Automation>

Fetch an automation by id, including its full step graph.

Parameters

Parameter	Type	Description
`id`Required	`string`	Automation ID.

Returns: The automation with its step graph. 404 if it does not exist in the organization.

const automation = await publiq.automations.get('aut_123');
console.log(automation.steps.length);

`automations.list`

automations.list({ limit?, after? }) → Promise<AutomationList>

List the organization automations, cursor-paginated.

Parameters

Parameter	Type	Description
`limit`Optional	`number`	Items per page (default 20, max 100).
`after`Optional	`string`	Cursor: `id` of the last item on the previous page.

Returns: List envelope { object: "list", data: Automation[] }.

const { data } = await publiq.automations.list({ limit: 50 });

`automations.enable`

automations.enable(id) → Promise<Automation>

Activates the automation — from then on it reacts to its triggerEvent.

Parameters

Parameter	Type	Description
`id`Required	`string`	ID of the automation to enable.

Returns: The automation with enabled: true.

await publiq.automations.enable('aut_123');

A newly created automation must be enabled to run — automations.create leaves it disabled by default.

`automations.disable`

automations.disable(id) → Promise<Automation>

Pauses the automation — it stops reacting to new triggerEvent fires. Runs already in progress are unaffected.

Parameters

Parameter	Type	Description
`id`Required	`string`	ID of the automation to disable.

Returns: The automation with enabled: false.

await publiq.automations.disable('aut_123');

`automations.runs`

automations.runs(id, { limit?, after? }) → Promise<AutomationRunList>

List an automation's runs, newest first, cursor-paginated. Each run has a state: running, waiting, completed, failed or canceled.

Parameters

Parameter	Type	Description
`id`Required	`string`	Automation ID.
`limit`Optional	`number`	Items per page (default 20, max 100).
`after`Optional	`string`	Cursor: `id` of the last item on the previous page.

Returns: List envelope { object: "list", data: AutomationRun[] }.

const { data } = await publiq.automations.runs('aut_123', { limit: 50 });

`automations.cancelRun`

automations.cancelRun(id, runId) → Promise<AutomationRun>

Cancels an in-flight run (running/waiting) — for example, to pull a contact out of a mid-flight nurture flow.

Parameters

Parameter	Type	Description
`id`Required	`string`	Automation ID (path).
`runId`Required	`string`	ID of the run to cancel (path).

Returns: The run with state: "canceled".

await publiq.automations.cancelRun('aut_123', 'run_456');

`automations.chat`

automations.chat(params) → Promise<{ reply, draft? }>

Conversational AI builder: describe the flow you want in natural language and get back a reply and, optionally, a draft — a proposed automation graph you can review and pass to automations.create. Requires the ai_builder plan feature.

Parameters

Parameter	Type	Description
`threadId`Required	`string`	Conversation id — keeps context across successive messages.
`message`Required	`string`	The user's request or a refinement on the previous reply.

Returns: { reply, draft? } — reply is the text response; draft, when present, is an automation graph ready for automations.create.

const { reply, draft } = await publiq.automations.chat({
threadId: 'thr_123',
message: 'Send a welcome email 1 hour after signup',
});
if (draft) {
await publiq.automations.create(draft);
}

Only available on plans with the ai_builder feature. Without it, the call returns 403 feature_not_available.

Examples show Node, Python and PHP. In Python methods are snake_case (e.g. cancel_run, from_spec) and take a dict; in PHP they are camelCase and take an associative array. Body keys are always camelCase (templateKey, firstName, scheduledAt) — API responses come back in snake_case.