Workspace events

Define workspace events and the types of their properties, so the w: events you send are checked.

Base URLhttps://api.emailit.com/v2Authentication Errors Rate limits

POST/workspace/events
GET/workspace/events/{id}
POST/workspace/events/{id}
GET/workspace/events
DEL/workspace/events/{id}

Create a workspace event

Defines a workspace event: a name and the properties every event of that type carries, each with a type. You then send it as w:<name>, and Emailit rejects events that don’t match. Requires an API key with the full scope.

Workspace events are included with Pro, Business and Custom plans. A workspace can define as many as its plan has event types: 100 on Pro and 1,000 on Business, with no limit on Custom. Custom events (c:<name>) need no definition. See Workspace events.

POST/workspace/events

Body parameters

namestringrequired

The event name, for example customer.type: 1 to 100 letters, digits, ., - or _, starting with a letter or digit. You can also send it with the prefix (w:customer.type); the prefix is removed. Must be unique in the workspace.

titlestring | null

A readable name shown in the dashboard, up to 120 characters.

descriptionstring | null

Note for your team, up to 1,000 characters.

propertiesobject[]

Up to 50 property definitions. Default [], which means events of this type carry no properties. Each one has:

name (required): 1 to 64 letters, digits, - or _, starting with a letter or digit. Dots aren’t allowed, because webhook filters and templates use dots to reach nested values. Names must be unique within the definition.
type (required): string, number, date or boolean, in any letter case.
title: a label, up to 120 characters.
description: up to 1,000 characters.
required: true if every event must include the property. Default false.

Returns

Returns 201 Created with the workspace event object.

Status	When
`403`	The API key doesn’t have the `full` scope, or the workspace is on Pay as you go: `error` is `plan_required` and `required_plan` is `pro`.
`409`	A workspace event with this name exists. `errors.name` says so.
`422`	A field is invalid: `errors` is keyed by its path, such as `name` or `properties.1.type`, and `message` repeats the first problem. Also returned with `code: "workspace_events_limit"` when the workspace already has as many workspace events as its plan allows, and for a name that starts with `c:`.

POST/workspace/events

Terminal

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",
    "description": "Set when a customer'\''s account type changes in the shop.",
    "properties": [
      { "name": "segment", "type": "string", "title": "Segment", "description": "b2b or b2c", "required": true },
      { "name": "since", "type": "date" }
    ]
  }'

JavaScript

const res = await fetch('https://api.emailit.com/v2/workspace/events', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.EMAILIT_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    name: 'customer.type',
    title: 'Customer type',
    description: "Set when a customer's account type changes in the shop.",
    properties: [
      { name: 'segment', type: 'string', title: 'Segment', description: 'b2b or b2c', required: true },
      { name: 'since', type: 'date' },
    ],
  }),
});
const definition = await res.json();

Python

import os, requests

r = requests.post(
    "https://api.emailit.com/v2/workspace/events",
    headers={"Authorization": f"Bearer {os.environ['EMAILIT_API_KEY']}"},
    json={
        "name": "customer.type",
        "title": "Customer type",
        "description": "Set when a customer's account type changes in the shop.",
        "properties": [
            {"name": "segment", "type": "string", "title": "Segment", "description": "b2b or b2c", "required": True},
            {"name": "since", "type": "date"},
        ],
    },
)
definition = r.json()

PHP

$client = new GuzzleHttp\Client(['base_uri' => 'https://api.emailit.com/v2/']);

$response = $client->post('workspace/events', [
    'headers' => ['Authorization' => 'Bearer ' . getenv('EMAILIT_API_KEY')],
    'json' => [
        'name' => 'customer.type',
        'title' => 'Customer type',
        'description' => "Set when a customer's account type changes in the shop.",
        'properties' => [
            ['name' => 'segment', 'type' => 'string', 'title' => 'Segment', 'description' => 'b2b or b2c', 'required' => true],
            ['name' => 'since', 'type' => 'date'],
        ],
    ],
]);
$definition = json_decode($response->getBody(), true);

JSON

{
  "object": "workspace_event",
  "id": "etp_2yHn4Kd8QwE1rT6vBx9LmZ3sPf0",
  "name": "customer.type",
  "type": "w:customer.type",
  "title": "Customer type",
  "description": "Set when a customer's account type changes in the shop.",
  "properties": [
    { "name": "segment", "type": "string", "title": "Segment", "description": "b2b or b2c", "required": true },
    { "name": "since", "type": "date", "title": null, "description": null, "required": false }
  ],
  "created_at": "2026-10-19T08:00:00.000000+00:00",
  "updated_at": "2026-10-19T08:00:00.000000+00:00"
}

JSON

{
  "error": "plan_required",
  "required_plan": "pro",
  "message": "Workspace and custom events are included with Pro and Business."
}

JSON

{
  "error": "w:customer.type is already defined",
  "errors": {
    "name": ["is already defined"]
  }
}

JSON

{
  "error": "properties.1.type must be one of string, number, date, boolean",
  "message": "properties.1.type must be one of string, number, date, boolean",
  "errors": {
    "properties.1.type": ["must be one of string, number, date, boolean"]
  }
}

Retrieve a workspace event

Retrieves the definition of a workspace event: its name, title and the properties senders must follow. Requires an API key with the full scope.

GET/workspace/events/{id}

Path parameters

idstringrequired

The definition ID (etp_…), its name (customer.type) or its event type (w:customer.type). URL-encode the : if your client doesn’t.

Returns

Returns the workspace event object.

objectstring

Always workspace_event.

idstring

Definition ID, prefixed etp_.

namestring

The event name, without the prefix.

typestring

The type to send and filter by: w: followed by the name.

titlestring | null

A readable name, shown in the dashboard instead of the type, for example on a contact’s activity.

descriptionstring | null

Note for your team.

propertiesobject[]

The properties an event of this type can carry, each with:

name: the key in the event’s properties.
type: string, number, date or boolean. See Property types.
title, description: optional labels, or null.
required: whether every event must include it.

created_at, updated_atstring

Timestamps in UTC.

Returns 404 with error: "Workspace event not found" if no definition matches.

GET/workspace/events/{id}

Terminal

curl https://api.emailit.com/v2/workspace/events/w%3Acustomer.type \
  -H "Authorization: Bearer $EMAILIT_API_KEY"

JavaScript

const res = await fetch('https://api.emailit.com/v2/workspace/events/customer.type', {
  headers: { Authorization: `Bearer ${process.env.EMAILIT_API_KEY}` },
});
const definition = await res.json();

Python

import os, requests

r = requests.get(
    "https://api.emailit.com/v2/workspace/events/customer.type",
    headers={"Authorization": f"Bearer {os.environ['EMAILIT_API_KEY']}"},
)
definition = r.json()

PHP

$client = new GuzzleHttp\Client(['base_uri' => 'https://api.emailit.com/v2/']);

$response = $client->get('workspace/events/customer.type', [
    'headers' => ['Authorization' => 'Bearer ' . getenv('EMAILIT_API_KEY')],
]);
$definition = json_decode($response->getBody(), true);

JSON

{
  "object": "workspace_event",
  "id": "etp_2yHn4Kd8QwE1rT6vBx9LmZ3sPf0",
  "name": "customer.type",
  "type": "w:customer.type",
  "title": "Customer type",
  "description": "Set when a customer's account type changes in the shop.",
  "properties": [
    { "name": "segment", "type": "string", "title": "Segment", "description": "b2b or b2c", "required": true },
    { "name": "since", "type": "date", "title": null, "description": null, "required": false }
  ],
  "created_at": "2026-10-19T08:00:00.000000+00:00",
  "updated_at": "2026-10-19T08:00:00.000000+00:00"
}

JSON

{
  "error": "Workspace event not found"
}

Update a workspace event

Updates the fields you pass and leaves the others unchanged. Requires an API key with the full scope.

The definition only checks new events. Events already stored keep their type and properties, so after a change, older events may have properties the definition no longer lists.

properties replaces the whole list. To add a property, send the current list plus the new one.
Renaming changes the type to send. Events stored under the old name keep it, and new events with the old name are rejected, unless you define it again.

POST/workspace/events/{id}

Path parameters

idstringrequired

The definition ID (etp_…), its name or its event type (w:…).

Body parameters

namestring

A new name, with the same rules as on create.

titlestring | null

Up to 120 characters. null or an empty string clears it.

descriptionstring | null

Up to 1,000 characters. null or an empty string clears it.

propertiesobject[]

The new property list, up to 50, as on create. [] removes every property.

Returns

Returns the updated workspace event object.

Status	When
`404`	No definition matches `id`.
`409`	Another workspace event already has the new name.
`422`	A field is invalid: `errors` is keyed by its path, and `message` repeats the first problem.

POST/workspace/events/{id}

Terminal

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

JavaScript

const res = await fetch('https://api.emailit.com/v2/workspace/events/customer.type', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.EMAILIT_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    properties: [
      { name: 'segment', type: 'string', title: 'Segment', required: true },
      { name: 'since', type: 'date' },
      { name: 'vat_exempt', type: 'boolean' },
    ],
  }),
});
const definition = await res.json();

Python

import os, requests

r = requests.post(
    "https://api.emailit.com/v2/workspace/events/customer.type",
    headers={"Authorization": f"Bearer {os.environ['EMAILIT_API_KEY']}"},
    json={
        "properties": [
            {"name": "segment", "type": "string", "title": "Segment", "required": True},
            {"name": "since", "type": "date"},
            {"name": "vat_exempt", "type": "boolean"},
        ]
    },
)
definition = r.json()

PHP

$client = new GuzzleHttp\Client(['base_uri' => 'https://api.emailit.com/v2/']);

$response = $client->post('workspace/events/customer.type', [
    'headers' => ['Authorization' => 'Bearer ' . getenv('EMAILIT_API_KEY')],
    'json' => [
        'properties' => [
            ['name' => 'segment', 'type' => 'string', 'title' => 'Segment', 'required' => true],
            ['name' => 'since', 'type' => 'date'],
            ['name' => 'vat_exempt', 'type' => 'boolean'],
        ],
    ],
]);
$definition = json_decode($response->getBody(), true);

JSON

{
  "object": "workspace_event",
  "id": "etp_2yHn4Kd8QwE1rT6vBx9LmZ3sPf0",
  "name": "customer.type",
  "type": "w:customer.type",
  "title": "Customer type",
  "description": "Set when a customer's account type changes in the shop.",
  "properties": [
    { "name": "segment", "type": "string", "title": "Segment", "description": null, "required": true },
    { "name": "since", "type": "date", "title": null, "description": null, "required": false },
    { "name": "vat_exempt", "type": "boolean", "title": null, "description": null, "required": false }
  ],
  "created_at": "2026-10-19T08:00:00.000000+00:00",
  "updated_at": "2026-10-19T10:12:45.000000+00:00"
}

JSON

{
  "error": "w:customer.segment is already defined",
  "errors": {
    "name": ["is already defined"]
  }
}

List workspace events

Returns the workspace’s event definitions, sorted by name. Requires an API key with the full scope.

GET/workspace/events

Query parameters

pageintegerdefault: 1

Page number, starting at 1.

limitintegerdefault: 100

Definitions per page, from 1 to 250.

searchstring

Case-insensitive match on part of the name or the title.

matchstring

all (default) requires every filter. or matches any filter. See Filtering.

orderstring

Sort key for this list. See the sort keys below.

directionstring

asc or desc.

Filter keys

Filters use key.condition=value query parameters, for example name.starts_with=order. or created_at.after=2026-10-01. See Filtering for the conditions per type.

Key	Type	Notes
`name`	string	The name without the `w:` prefix.
`title`	string
`created_at`	date
`updated_at`	date

Sort keys for order: name, title, created_at, updated_at. The default is name, ascending.

Returns

dataobject[]

Workspace event objects on this page.

total_recordsinteger

Number of definitions that match the query.

next_page_urlstring | null

Path of the next page, or null on the last page. It carries only page and limit; add your search and filters again when you follow it.

previous_page_urlstring | null

Path of the previous page, or null on the first page.

GET/workspace/events

Terminal

curl -G https://api.emailit.com/v2/workspace/events \
  -H "Authorization: Bearer $EMAILIT_API_KEY" \
  --data-urlencode "search=customer"

JavaScript

const res = await fetch('https://api.emailit.com/v2/workspace/events?search=customer', {
  headers: { Authorization: `Bearer ${process.env.EMAILIT_API_KEY}` },
});
const { data, total_records } = await res.json();

Python

import os, requests

r = requests.get(
    "https://api.emailit.com/v2/workspace/events",
    headers={"Authorization": f"Bearer {os.environ['EMAILIT_API_KEY']}"},
    params={"search": "customer"},
)
definitions = r.json()["data"]

PHP

$client = new GuzzleHttp\Client(['base_uri' => 'https://api.emailit.com/v2/']);

$response = $client->get('workspace/events', [
    'headers' => ['Authorization' => 'Bearer ' . getenv('EMAILIT_API_KEY')],
    'query' => ['search' => 'customer'],
]);
$definitions = json_decode($response->getBody(), true)['data'];

JSON

{
  "data": [
    {
      "object": "workspace_event",
      "id": "etp_2yHn4Kd8QwE1rT6vBx9LmZ3sPf0",
      "name": "customer.type",
      "type": "w:customer.type",
      "title": "Customer type",
      "description": "Set when a customer's account type changes in the shop.",
      "properties": [
        { "name": "segment", "type": "string", "title": "Segment", "description": "b2b or b2c", "required": true },
        { "name": "since", "type": "date", "title": null, "description": null, "required": false }
      ],
      "created_at": "2026-10-19T08:00:00.000000+00:00",
      "updated_at": "2026-10-19T08:00:00.000000+00:00"
    }
  ],
  "total_records": 1,
  "next_page_url": null,
  "previous_page_url": null
}

Delete a workspace event

Deletes a workspace event definition. Requires an API key with the full scope.

Events already stored with this type are kept, in the event log and on contacts. New events of the type are rejected with 422 until you define it again. Webhooks subscribed to the type keep the subscription.

DELETE/workspace/events/{id}

Path parameters

idstringrequired

The definition ID (etp_…), its name or its event type (w:…).

Returns

objectstring

Always workspace_event.

idstring

ID of the deleted definition.

namestring

Its name.

typestring

Its event type, w: followed by the name.

deletedboolean

Always true.

Returns 404 if no definition matches.

DELETE/workspace/events/{id}

Terminal

curl -X DELETE https://api.emailit.com/v2/workspace/events/etp_2yHn4Kd8QwE1rT6vBx9LmZ3sPf0 \
  -H "Authorization: Bearer $EMAILIT_API_KEY"

JavaScript

const res = await fetch('https://api.emailit.com/v2/workspace/events/etp_2yHn4Kd8QwE1rT6vBx9LmZ3sPf0', {
  method: 'DELETE',
  headers: { Authorization: `Bearer ${process.env.EMAILIT_API_KEY}` },
});
const result = await res.json();

Python

import os, requests

r = requests.delete(
    "https://api.emailit.com/v2/workspace/events/etp_2yHn4Kd8QwE1rT6vBx9LmZ3sPf0",
    headers={"Authorization": f"Bearer {os.environ['EMAILIT_API_KEY']}"},
)
result = r.json()

PHP

$client = new GuzzleHttp\Client(['base_uri' => 'https://api.emailit.com/v2/']);

$response = $client->delete('workspace/events/etp_2yHn4Kd8QwE1rT6vBx9LmZ3sPf0', [
    'headers' => ['Authorization' => 'Bearer ' . getenv('EMAILIT_API_KEY')],
]);
$result = json_decode($response->getBody(), true);

JSON

{
  "object": "workspace_event",
  "id": "etp_2yHn4Kd8QwE1rT6vBx9LmZ3sPf0",
  "name": "customer.type",
  "type": "w:customer.type",
  "deleted": true
}