Skip to main content
Events represent discrete actions taken by contacts — either tracked manually via the /v1/track endpoint or generated automatically by Plunk. These endpoints let you query event history and discover which event names exist in your project.
All event endpoints require a secret key (sk_*).

​
System (reserved) events

Plunk automatically tracks the following events. They appear in event listings but cannot be tracked manually via /v1/track and cannot be deleted.
EventDescription
email.sentAn email was sent to a contact
email.deliveryAn email was successfully delivered
email.openA contact opened an email
email.clickA contact clicked a link in an email
email.bounceAn email bounced (hard or soft)
email.complaintA contact marked an email as spam
email.receivedAn email was received at a verified domain
contact.subscribedA contact’s subscription status changed to true
contact.unsubscribedA contact’s subscription status changed to false
segment.<slug>.entryA contact entered a segment with membership tracking enabled
segment.<slug>.exitA contact left a segment with membership tracking enabled
These events can be used as workflow triggers and in segment filter conditions just like custom events.

​
List events

GET /events Returns a list of recent event records for the project. Optionally filter by event name.

​
Query parameters

​
eventName
string
Filter results to events with this exact name.
​
limit
number
default:"100"
Maximum number of events to return.

​
Response

​
events
array
Array of event records, ordered newest first.
Example
curl --request GET \
  --url 'https://next-api.useplunk.com/events?eventName=purchased&limit=50' \
  --header 'Authorization: Bearer sk_live_yourkey'
200
{
  "events": [
    {
      "id": "clx_evt_abc123",
      "name": "purchased",
      "contactId": "clx_contact_xyz789",
      "data": { "plan": "pro", "amount": 99 },
      "createdAt": "2024-01-15T10:30:00.000Z",
      "contact": { "email": "[email protected]" }
    }
  ]
}

​
List event names

GET /events/names Returns a deduplicated list of all event names that have been tracked for the project, ordered by frequency. This is useful for populating workflow trigger dropdowns or segment filter fields.

​
Response

​
eventNames
string[]
Array of unique event name strings, sorted by occurrence count descending.
Example
curl --request GET \
  --url https://next-api.useplunk.com/events/names \
  --header 'Authorization: Bearer sk_live_yourkey'
200
{
  "eventNames": [
    "signed_up",
    "purchased",
    "plan_upgraded",
    "email.sent",
    "email.open",
    "contact.subscribed"
  ]
}

​
Get event stats

GET /events/stats Returns aggregate event counts for the project, optionally filtered by date range.

​
Query parameters

​
startDate
string
ISO 8601 start date for the stats window.
​
endDate
string
ISO 8601 end date for the stats window.
Example
curl --request GET \
  --url 'https://next-api.useplunk.com/events/stats?startDate=2024-01-01&endDate=2024-01-31' \
  --header 'Authorization: Bearer sk_live_yourkey'

​
Get contact events

GET /events/contact/:contactId Returns recent events for a specific contact.

​
Path parameters

​
contactId
string
required
The contact ID.

​
Query parameters

​
limit
number
default:"50"
Maximum number of events to return.
Example
curl --request GET \
  --url https://next-api.useplunk.com/events/contact/clx_contact_abc123 \
  --header 'Authorization: Bearer sk_live_yourkey'

​
Delete events by name

DELETE /events/:eventName Deletes all event records with a specific name. Only works if the event is not used in any segments or workflows.

​
Path parameters

​
eventName
string
required
The event name to delete (e.g. old_event). URL-encode special characters.
Check event usage with GET /events/:eventName/usage before deleting. You cannot delete a system event or an event currently referenced by a workflow trigger or segment condition.
Example
curl --request DELETE \
  --url https://next-api.useplunk.com/events/old_test_event \
  --header 'Authorization: Bearer sk_live_yourkey'

Build docs developers (and LLMs) love

Get started for freeTalk to us