# Workspace events

> Define workspace events and the type of each property, so every system that sends them stays consistent. Covers property types, validation and changing a definition.

A workspace event is an event your workspace declares before anyone sends it: its name, an optional title and the properties it carries, each with a type. Events of that type are sent as `w:<name>`, and Emailit rejects the ones that don't match. This page explains how to define them and how validation works.

If you don't want to declare a structure, send a [custom event](/docs/events/#three-scopes-of-events) (`c:<name>`) instead. Workspace events and custom events are included with Pro, Business and Custom plans.

## Define a workspace event

**Dashboard**

  1. **Open Workspace events.** Go to **Email API → Events** and select the **Workspace events** tab, then **Define workspace event**.

  2. **Name the event.** Enter a **Name** such as `customer.type`. It's sent as `w:customer.type`. Add a **Title**, shown in timelines and pickers, and a **Description** for your team if you like.

  3. **Add properties.** Select **Add property** for each value senders must or may include. Give it a name, choose its **Type**, and turn on **Required** if every event must have it. A title and a description are optional.

  4. **Create it.** Select **Create**. To check it, select **Send test** on the definition: it opens **Send event** with the event already chosen.

**API**

  Call [Create a workspace event](/docs/api-reference/workspace-events/create/) with an API key with **Full Access**:

```bash
curl -X POST https://api.emailit.com/v2/workspace/events \
  -H "Authorization: Bearer $EMAILIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "customer.type",
    "title": "Customer type",
    "properties": [
      { "name": "segment", "type": "string", "required": true },
      { "name": "since", "type": "date" }
    ]
  }'
```

Then send it like any other event, with the tracking script or the API:

```bash
curl -X POST https://api.emailit.com/v2/events \
  -H "Authorization: Bearer $EMAILIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "type": "w:customer.type", "email": "jane@example.com", "properties": { "segment": "b2b", "since": "2026-10-01" } }'
```

## Property types

| Type | Accepts | Stored as |
| --- | --- | --- |
| `string` | A JSON string, up to 2,000 characters. | The string |
| `number` | A JSON number. Numbers in quotes, such as `"42"`, are rejected. | The number |
| `date` | An ISO 8601 date (`2026-10-01`) or date-time (`2026-10-01T12:00:00Z`), or a timestamp in milliseconds. Years before 1900 are rejected. | An ISO 8601 date-time in UTC |
| `boolean` | `true` or `false`. | The boolean |

## How events are checked

When a `w:` event arrives, Emailit compares its `properties` with the definition:

- Every property must be in the definition. Unknown properties are rejected, so a typo doesn't go unnoticed.
- Required properties must be present and not `null`.
- An optional property can be left out, or sent as `null` to say it's empty.
- Each value must match its type.

A `w:` event whose name isn't defined is rejected too. The API answers with `422` and every problem keyed by its path, such as `properties.since`. The tracking script drops invalid events and, with [debug](/docs/events/tracking-script/#debug) on, logs why.

## Change or delete a definition

On the **Workspace events** tab, select **Edit** or **Delete** on a definition. With the API, use [Update a workspace event](/docs/api-reference/workspace-events/update/) and [Delete a workspace event](/docs/api-reference/workspace-events/delete/).

- A definition only checks new events. Events already stored keep the properties they had.
- Changing the properties replaces the whole list. Senders that still send a removed property get errors, so update them first or at the same time.
- Renaming changes the type to send. Stored events keep the old type, and new events with the old name are rejected.
- Deleting keeps the stored events, and new events of the type are rejected until you define it again.

## Limits

A workspace can define as many workspace events as its plan has [event types](/docs/events/#limits): 100 on Pro and 1,000 on Business, with no limit on Custom. One more returns `422` with `code` `workspace_events_limit`. Each workspace event has up to 50 properties. Names have up to 100 characters, property names up to 64, titles up to 120 and descriptions up to 1,000.

## Related

  - [Event tracking](/docs/events/): Scopes, names and where events go.
  - [Workspace events API](/docs/api-reference/workspace-events/): Create, list, update and delete definitions.

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