plunk/apps/wiki/content/docs/guides/events.mdx

---
title: Events
description: Track user actions and behavior
---

## What are events

Events track user actions in your application. Use them to:
- Trigger automated workflows
- Build behavior-based segments
- Analyze user engagement
- Track conversion funnels

Common events: signups, purchases, logins, feature usage, page views.

## Tracking events

Use your **public key** for event tracking:

```javascript
fetch('{{API_URL}}/v1/track', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer pk_your_public_key',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    email: 'user@example.com',
    event: 'button_clicked',
    data: {
      button: 'signup',
      page: '/pricing'
    }
  })
});
```

This creates or updates the contact and tracks the event.

### Persistent vs. Non-Persistent Data

Event data can be either **persistent** (saved to contact) or **non-persistent** (available only to workflows):

**Simple values are persistent** — Saved to contact profile:
```javascript
{
  email: 'user@example.com',
  event: 'subscription_created',
  data: {
    plan: 'premium',  // Saved to contact.data.plan
    mrr: 99.00        // Saved to contact.data.mrr
  }
}
```

**Non-persistent values** — Available only to triggered workflows:
```javascript
{
  email: 'user@example.com',
  event: 'order_placed',
  data: {
    totalSpent: 299.99,  // Persistent - saved to contact
    orderId: {value: 'order-12345', persistent: false},  // Non-persistent - workflows only
    receiptUrl: {value: 'https://...', persistent: false}  // Non-persistent - workflows only
  }
}
```

**Why use non-persistent data?**
- Temporary tokens/codes (password reset, verification)
- One-time URLs or session data
- Data that shouldn't pollute contact profiles
- Information needed only for a specific workflow

Non-persistent data is available throughout the entire workflow execution but never stored on the contact record.

## Event structure

Each event stores:

```json
{
  "id": "evt_abc123",
  "name": "purchase",
  "contactId": "contact_xyz",
  "data": {
    "product": "Premium Plan",
    "amount": 99.00
  },
  "createdAt": "2024-03-15T10:30:00Z"
}
```

## Using events
You can use events to trigger workflows, create segments, and analyze user behavior.

## Common event patterns

### Lifecycle events

```javascript
// User signs up
track({ email, event: 'signed_up', data: { source: 'homepage' } });

// User activates account
track({ email, event: 'account_activated' });

// User completes onboarding
track({ email, event: 'onboarding_completed', data: { steps: 5 } });
```

### Commerce events

```javascript
// Add to cart
track({ email, event: 'cart_added', data: { productId: '123', price: 49 } });

// Purchase
track({ email, event: 'purchase', data: { orderId: '456', total: 99 } });

// Subscription created
track({ email, event: 'subscription_created', data: { plan: 'pro', mrr: 29 } });
```

### Engagement events

```javascript
// Feature used
track({ email, event: 'feature_used', data: { feature: 'export' } });

// Page viewed
track({ email, event: 'page_view', data: { path: '/dashboard' } });

// Login
track({ email, event: 'logged_in' });
```

### Automatic events

Plunk sends these automatically:

**Email events:**
- `email.sent` — Email delivered to inbox
- `email.opened` — Email opened (first time)
- `email.clicked` — Link clicked in email
- `email.bounced` — Email bounced
- `email.complained` — Spam complaint

**Segment events** (if membership tracking enabled):
- `segment.entered` — Contact joined segment
- `segment.exited` — Contact left segment

## Event naming conventions

**Use lowercase with underscores:**
```
✓ user_signed_up
✓ purchase_completed
✗ UserSignedUp
✗ purchaseCompleted
```

**Be specific but concise:**
```
✓ trial_started
✓ subscription_cancelled
✗ user_started_a_trial
✗ sub_cancel
```

**Group related events:**
```
user_signed_up
user_logged_in
user_deleted_account

subscription_created
subscription_renewed
subscription_cancelled
```

## Managing events

### List events

```bash
curl -X GET "{{API_URL}}/events?limit=100" \
  -H "Authorization: Bearer sk_your_secret_key"
```

### List unique event names

```bash
curl -X GET {{API_URL}}/events/names \
  -H "Authorization: Bearer sk_your_secret_key"
```

Returns all event names tracked in your project.

### Get events for a contact

```bash
curl -X GET {{API_URL}}/events?contactId=contact_id \
  -H "Authorization: Bearer sk_your_secret_key"
```

## Best practices

**Track meaningful actions** — Focus on events that indicate intent or value (signups, purchases, key features).

**Include context** — Add relevant data to understand the event better (product, amount, source).

**Be consistent** — Use the same event names and data structure across your application.

**Don't over-track** — Tracking every click creates noise. Focus on conversion events and key milestones.

**Test your tracking** — Verify events appear in dashboard before building workflows around them.

## What's next

- [Build workflows](/guides/workflows) triggered by events
- [Create segments](/guides/segments) based on event data
- [Analyze events](/guides/analytics) to understand user behavior