# Event tracking

> Record what people do in your app and on your site as workspace or custom events, tie them to contacts, and receive them in webhooks.

Event tracking lets you record what people do in your own product: an order, a plan change, a sign-up, a product view. You send the events from your website with the tracking script or from your servers with the API. Emailit stores them next to the events it records itself, ties them to contacts, and can send them to your webhooks.

Event tracking is included with Pro, Business and Custom plans. On Pay as you go, sending events and defining workspace events return `403` with `"error": "plan_required"`, and the tracking script's requests are refused.

## Three scopes of events

Every event has a type, and its prefix tells you its **scope**:

| Scope | Type | Who defines it | Example |
| --- | --- | --- | --- |
| System | `<name>` | Emailit. These record what happens to your emails, contacts and other resources. You can't send them. | `email.delivered` |
| Workspace | `w:<name>` | Your workspace. You declare the event and the type of each property first, and Emailit rejects events that don't match. | `w:customer.type` |
| Custom | `c:<name>` | Nobody. Any name, with any JSON object as its properties. | `c:order.completed` |

Use a **workspace event** when several systems send the same event and you want them to stay consistent, or when people in your team rely on its fields. Use a **custom event** when you want to keep your own data structure, for example the order format of your shop, without declaring it first. You can start with a custom event and define it as a workspace event later; the two are separate types, so `c:order.completed` and `w:order.completed` don't mix.

## Event names

Names have 1 to 100 letters, digits, dots, dashes or underscores, and start with a letter or digit: `customer.type`, `order-completed`, `cart_updated`. Names are case-sensitive.

Property names of workspace events follow the same rules, without dots, because webhook filters and templates use dots to reach nested values.

## Ways to send events

| From | How | Credentials |
| --- | --- | --- |
| Your website | The [tracking script](/docs/events/tracking-script/) | A public tracking key, limited to your sites |
| Your servers | [Send an event](/docs/api-reference/events/send/) or [Send events in a batch](/docs/api-reference/events/batch/) | An API key with **Full Access** or **Events Only**. See [Send events from your backend](/docs/events/send-events/). |
| The dashboard | **Send event** on **Email API → Events** | Your login. Meant for testing a webhook or an integration. |

Events about money, such as orders and payments, are best sent from your servers. Browser events can be blocked, and anyone can send events with a public key.

## Events and contacts

An event can name the person it's about, by `email` or by `contact_id`.

- Contacts are looked up, never created. If no contact has the email, the address is still stored, and the event shows on the contact's activity once you create it.
- A `contact_id` must belong to a contact in the workspace.
- Events without a person can carry an `anonymous_id`. The tracking script adds one to every event it sends.

Events tied to a contact show in the contact's **Activity log**, next to the emails they received. Workspace events with a title show the title there.

## Where events go

- **The event log.** **Email API → Events** lists every event on the **Log** tab. Filter by **Scope** to see only system, workspace or custom events. With the API, use the `scope` parameter of [List events](/docs/api-reference/events/list/).
- **Webhooks.** Subscribe a webhook to a type such as `c:order.completed`, or to every workspace or custom event with `w:*` and `c:*`. A webhook with **All events** on doesn't get them unless you pick them too. See [Event types](/docs/webhooks/event-types/#workspace-and-custom-events).
- **Contacts.** See [Events and contacts](#events-and-contacts).
- **Automations.** A **Custom event** [trigger](/docs/automations/triggers/#custom-event) starts a run for the event's contact, optionally only when its properties match. The same events can end runs, reach goals and resume **Wait until** steps. Only events you send from your server with the [Events API](/docs/events/send-events/) do this: anyone with your public tracking key can name a visitor, so events from the [tracking script](/docs/events/tracking-script/#identify-visitors) are recorded and reach webhooks but don't start, end or advance runs. The **Custom event** trigger is included with Business and Custom plans, and exit conditions, goals and waits on these events with Pro, Business and Custom. See [Exit conditions and goals](/docs/automations/exits-and-goals/).

## Retention

Events are part of your workspace's **Logs**, so they're kept as long as your plan's logs retention, then deleted. See [Data retention](/docs/data-retention/). Keep orders and other records you need for longer in your own systems.

## Limits

| | Pay as you go | Pro | Business | Custom |
| --- | --- | --- | --- | --- |
| Workspace and custom event types | — | 100 | 1,000 | Unlimited |
| Website tracking script | — | Included | Included | Included |

- **Event types** are the distinct workspace and custom types a workspace sends, such as `c:order.completed` and `w:customer.type`. Types it has sent before keep working. Once it has used its plan's number of types, events of a new type are rejected with `422`.
- Workspace events: as many as the plan's event types, each with up to 50 properties.
- Custom event properties up to 32 KB of JSON, nested up to 8 levels.
- Up to 100 events per batch request.
- 25 tracking keys per workspace.

More in [Limits](/docs/limits/#other-limits).

## Related

  - [Workspace events](/docs/events/workspace-events/): Define events and the types of their properties.
  - [Send events from your backend](/docs/events/send-events/): Record events with the API.
  - [Tracking script](/docs/events/tracking-script/): Send events from your website.
  - [Events API](/docs/api-reference/events/): Send, list and retrieve events.

---
Source: https://emailit.com/docs/events/