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.
| Parameter | Type | Description |
|---|---|---|
eventRequired | string | Event name (max 200 chars), e.g. user.signed_up. It is against this name that automations' `triggerEvent` is matched. |
contactIdOptional | string | ID of the event's target contact. Alternative to email. |
emailOptional | string | Email of the target contact (max 320 chars) — resolves the existing contact by email. Alternative to contactId. |
payloadOptional | 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, 0contactId 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).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.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.
| Parameter | Type | Description |
|---|---|---|
eventsRequired | 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);
}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).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.