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.
No idempotency: re-tracking the same event creates a new event record.
Authorization
ApiKeyAuth API Key authentication. Secret keys (sk_*) are required for all endpoints except /v1/track. Public keys (pk_*) only work with the /v1/track endpoint for client-side event tracking. The project is automatically derived from the key.
In: header
Request Body
application/json
Contact email. The contact is auto-created if it doesn't exist.
emailEvent name. Cannot match the reserved patterns above.
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.
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 Body
application/json
curl -X POST "https://next-api.useplunk.com/v1/track" \ -H "Content-Type: application/json" \ -d '{ "email": "user@example.com", "event": "purchase", "data": { "product": "Premium Plan", "amount": 99 } }'{
"success": true,
"data": {
"contact": "string",
"event": "string",
"timestamp": "2019-08-24T14:15:22Z"
}
}