Workspace events

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 (c:<name>) instead. Workspace events and custom events are included with Pro, Business and Custom plans.

Define a workspace event

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:

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

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 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 and Delete a workspace event.

• 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: 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