Events

Emit events that trigger automations; the payload becomes the variables (`publiq.events`).

The events resource is the bridge between your system and Automations: you emit an application event (e.g. user.signed_up) and Publiq starts (or resumes) any enabled automation whose triggerEvent matches that name, for the event's target contact.

Method reference

`events.emit`

events.emit(params) → Promise<{ accepted: true, started, resumed }>

Registers an application event for the target contact (by contactId or email). Returns 202 immediately: it starts enabled automations whose triggerEvent matches event, and resumes waiting runs that were waiting on that event.

Parameters

Parameter	Type	Description
`event`Required	`string`	Event name (max 200 chars), e.g. `user.signed_up`. It is against this name that automations' `triggerEvent` is matched.
`contactId`Optional	`string`	ID of the event's target contact. Alternative to `email`.
`email`Optional	`string`	Email of the target contact (max 320 chars) — resolves the existing contact by email. Alternative to `contactId`.
`payload`Optional	`object`	Free-form event data. Made available to the automation's steps and merged into the Variables at send time.

Returns: The dispatch result — { object: "event_dispatch", accepted: true, started, resumed }, where started is how many runs were started and resumed how many runs were resumed.

const result = await publiq.events.emit({
event: 'user.signed_up',
email: 'ana@example.com',
payload: { first_name: 'Ana', plan: 'Pro' },
});
console.log(result.started, result.resumed); // e.g. 1, 0

Provide contactId or email — without a subject for the event, no contact is resolved and no automation is started (started and resumed come back 0, even with 202).

The payload (merged with the contact's attributes) fills the template variables at the send step: payload: { first_name: "Ana", plan: "Pro" } becomes {{ first_name }} and {{ plan }} in the email. See How it works and Variables.

For an automation to actually run, first create and enable an Automation with the matching triggerEvent — only then does events.emit for that event fire it. In the example above, an automation with triggerEvent: "user.signed_up" would react to the dispatch, starting a run for ana@example.com with the payload available to its steps.

`events.emitBatch`

events.emitBatch(events) → Promise<{ object: "event_batch", accepted, failed, results }>

Emits a batch of events (up to 500) in one call — the efficient way to start an automation for many contacts at once, instead of one emit per contact. Each item is an independent event with the same shape as emit.

Parameters

Parameter	Type	Description
`events`Required	`DispatchEvent[]`	Array of events (min 1, max 500). Each item takes the same fields as `emit`: `event` (required), `contactId`/`email` and `payload`.

Returns: { object: "event_batch", accepted, failed, results }. Each results item has { index, status: "accepted" | "failed", started?, resumed?, error? } — the index matches the sent position.

const batch = await publiq.events.emitBatch([
{ event: 'user.signed_up', email: 'ana@example.com', payload: { first_name: 'Ana' } },
{ event: 'user.signed_up', email: 'bob@example.com', payload: { first_name: 'Bob' } },
]);
console.log(batch.accepted, batch.failed); // e.g. 2, 0
for (const r of batch.results) {
if (r.status === 'failed') console.warn(r.index, r.error);
}

Skip-and-continue: an invalid item does not fail the batch — it comes back with status: "failed" and an error, and the rest proceed. Always inspect results to handle failures. The same guarantees as emit apply per item (active-run dedup and per-cycle run limits).

To enroll a whole audience, page through `contacts.list(audienceId)` and send emails in batches of up to 500. For a one-shot send to a list (not an automation), prefer a broadcast.

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.