v1

latestOpenAPI 3.1.02026-07-1315527.8 KB

Public API

Track event

Track an event for a contact. Automatically creates or upserts the contact, then records the event. Tracked events can be used as workflow triggers, segment filters, and audience filters.

Reserved event names (rejected with VALIDATION_ERROR and code reserved_event): anything matching email.*, contact.subscribed, contact.unsubscribed, segment.<slug>.entry, segment.<slug>.exit. These are emitted by Plunk itself.

Idempotency: re-tracking the same event creates a new event record. Send an Idempotency-Key header to have a repeated request refused with 409 instead.

post/v1/track

Headers

Idempotency-Keystring

Optional key that guarantees this request runs at most once. If the key was already used by your project, the request is refused with 409 instead of being performed a second time. Keys are scoped to your project, expire after 24 hours (configurable when self-hosting), and must be 1-255 printable ASCII characters.

Request body

emailstring email required

Contact email. The contact is auto-created if it doesn't exist.

eventstring required

Event name. Cannot match the reserved patterns above.

subscribedboolean

Subscription state to apply to the contact. New contacts default to subscribed (true). Existing contacts keep their current state unless you pass an explicit value here. Pass false to track an event without resubscribing an unsubscribed contact.

dataobject

Contact data and one-off event variables. Persistent values (primitives, plain objects) are saved on the contact and become available as template variables. Pass { value, persistent: false } for one-shot variables that should not be stored on the contact (e.g. order IDs, transaction details). null deletes a field. Empty strings are ignored. Reserved keys are filtered out — see the contacts concept page.

Response

Event tracked successfully

successboolean