# Eventos de espacio de trabajo API

> Define eventos de espacio de trabajo y los tipos de sus propiedades, para que los eventos w: que envías se comprueben.

URL base: `https://api.emailit.com/v2`. Autentícate con `Authorization: Bearer <API key>`.

## Crear un evento de espacio de trabajo — POST /workspace/events

> Define un evento de espacio de trabajo y sus propiedades con tipo. Los eventos de este tipo se envían después con el prefijo w: y se comprueban con la definición.

# Crear un evento de espacio de trabajo

Define un evento de espacio de trabajo: un nombre y las propiedades que lleva cada evento de ese tipo, cada una con su tipo. Después lo envías como `w:<name>`, y Emailit rechaza los eventos que no coinciden con la definición. Requiere una clave de API con el permiso `full`.

Los eventos de espacio de trabajo están incluidos en los planes Pro, Business y Custom. Un espacio de trabajo puede definir tantos como tipos de eventos tenga su plan: 100 en Pro y 1000 en Business, sin límite en Custom. Los eventos personalizados (`c:<name>`) no necesitan definición. Consulta [Eventos de espacio de trabajo](/es/docs/events/workspace-events/).

`POST /workspace/events`

## Parámetros del cuerpo

- `name` (string, obligatorio): El nombre del evento, por ejemplo `customer.type`: de 1 a 100 letras, dígitos, `.`, `-` o `_`, empezando por una letra o un dígito. También puedes enviarlo con el prefijo (`w:customer.type`); el prefijo se quita. Tiene que ser único en el espacio de trabajo.

- `title` (string | null): Un nombre legible que se muestra en el panel, de hasta 120 caracteres.

- `description` (string | null): Una nota para tu equipo, de hasta 1000 caracteres.

- `properties` (object[]): Hasta 50 definiciones de propiedades. Por defecto, `[]`, que significa que los eventos de este tipo no llevan propiedades. Cada una tiene: - `name` (obligatorio): de 1 a 64 letras, dígitos, `-` o `_`, empezando por una letra o un dígito. No se admiten puntos, porque los filtros de webhook y las plantillas usan los puntos para acceder a valores anidados. Los nombres tienen que ser únicos dentro de la definición. - `type` (obligatorio): `string`, `number`, `date` o `boolean`, con cualquier combinación de mayúsculas y minúsculas. - `title`: una etiqueta, de hasta 120 caracteres. - `description`: de hasta 1000 caracteres. - `required`: `true` si todos los eventos tienen que incluir la propiedad. Por defecto, `false`.

## Devuelve

Devuelve `201 Created` con el [objeto de evento de espacio de trabajo](/es/docs/api-reference/workspace-events/get/).

| Código | Cuándo |
| --- | --- |
| `403` | La clave de API no tiene el permiso `full`, o el espacio de trabajo está en Pay as you go: `error` es `plan_required` y `required_plan` es `pro`. |
| `409` | Ya existe un evento de espacio de trabajo con este nombre. `errors.name` lo indica. |
| `422` | Un campo no es válido: `errors` usa su ruta como clave, por ejemplo `name` o `properties.1.type`, y `message` repite el primer problema. También se devuelve con `code: "workspace_events_limit"` cuando el espacio de trabajo ya tiene tantos eventos de espacio de trabajo como permite su plan, y para un nombre que empieza por `c:`. |

**Petición** `POST /workspace/events`

**cURL**

```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",
    "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" }
    ]
  }'
```

**Node.js**

```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**

```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**

```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);
```

**201**

```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"
}
```

**403**

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

**409**

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

**422**

```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"]
  }
}
```

---
Fuente: https://emailit.com/es/docs/api-reference/workspace-events/create/

## Obtener un evento de espacio de trabajo — GET /workspace/events/{id}

> Obtén la definición de un evento de espacio de trabajo por su ID o su nombre, con sus propiedades con tipo.

# Obtener un evento de espacio de trabajo

Obtiene la definición de un evento de espacio de trabajo: su nombre, su título y las propiedades que tienen que respetar quienes lo envían. Requiere una clave de API con el permiso `full`.

`GET /workspace/events/{id}`

## Parámetros de ruta

- `id` (string, obligatorio): El ID de la definición (`etp_…`), su nombre (`customer.type`) o su tipo de evento (`w:customer.type`). Codifica los `:` para URL si tu cliente no lo hace.

## Devuelve

Devuelve el objeto de evento de espacio de trabajo.

- `object` (string): Siempre `workspace_event`.

- `id` (string): El ID de la definición, con el prefijo `etp_`.

- `name` (string): El nombre del evento, sin el prefijo.

- `type` (string): El tipo que se usa para enviar y filtrar: `w:` seguido del nombre.

- `title` (string | null): Un nombre legible que el panel muestra en lugar del tipo, por ejemplo en la actividad de un contacto.

- `description` (string | null): Una nota para tu equipo.

- `properties` (object[]): Las propiedades que puede llevar un evento de este tipo, cada una con: - `name`: la clave en las `properties` del evento. - `type`: `string`, `number`, `date` o `boolean`. Consulta [Tipos de propiedades](/es/docs/events/workspace-events/#property-types). - `title`, `description`: etiquetas opcionales, o `null`. - `required`: si todos los eventos tienen que incluirla.

- `created_at, updated_at` (string): Las marcas de tiempo en UTC.

Devuelve `404` con `error: "Workspace event not found"` si ninguna definición coincide.

**Petición** `GET /workspace/events/{id}`

**cURL**

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

**Node.js**

```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**

```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**

```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);
```

**200**

```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"
}
```

**404**

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

---
Fuente: https://emailit.com/es/docs/api-reference/workspace-events/get/

## Actualizar un evento de espacio de trabajo — POST /workspace/events/{id}

> Cambia el nombre de un evento de espacio de trabajo o su título, su descripción o sus propiedades. Los eventos ya guardados no cambian.

# Actualizar un evento de espacio de trabajo

Actualiza los campos que pasas y deja los demás sin cambios. Requiere una clave de API con el permiso `full`.

La definición solo comprueba los eventos nuevos. Los eventos ya guardados conservan su tipo y sus propiedades, así que, después de un cambio, los eventos anteriores pueden tener propiedades que la definición ya no incluye.

- `properties` sustituye la lista completa. Para añadir una propiedad, envía la lista actual más la nueva.
- Cambiar el nombre cambia el tipo que hay que enviar. Los eventos guardados con el nombre anterior lo conservan, y los eventos nuevos con el nombre anterior se rechazan, salvo que vuelvas a definirlo.

`POST /workspace/events/{id}`

## Parámetros de ruta

- `id` (string, obligatorio): El ID de la definición (`etp_…`), su nombre o su tipo de evento (`w:…`).

## Parámetros del cuerpo

- `name` (string): Un nombre nuevo, con las mismas reglas que al [crearlo](/es/docs/api-reference/workspace-events/create/#body-parameters).

- `title` (string | null): De hasta 120 caracteres. `null` o una cadena vacía lo borran.

- `description` (string | null): De hasta 1000 caracteres. `null` o una cadena vacía la borran.

- `properties` (object[]): La nueva lista de propiedades, hasta 50, como al [crearlo](/es/docs/api-reference/workspace-events/create/#body-parameters). `[]` elimina todas las propiedades.

## Devuelve

Devuelve el [objeto de evento de espacio de trabajo](/es/docs/api-reference/workspace-events/get/) actualizado.

| Código | Cuándo |
| --- | --- |
| `404` | Ninguna definición coincide con `id`. |
| `409` | Otro evento de espacio de trabajo ya tiene el nombre nuevo. |
| `422` | Un campo no es válido: `errors` usa su ruta como clave, y `message` repite el primer problema. |

**Petición** `POST /workspace/events/{id}`

**cURL**

```bash
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" }
    ]
  }'
```

**Node.js**

```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**

```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**

```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);
```

**200**

```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"
}
```

**409**

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

---
Fuente: https://emailit.com/es/docs/api-reference/workspace-events/update/

## Listar eventos de espacio de trabajo — GET /workspace/events

> Lista las definiciones de eventos del espacio de trabajo por orden de nombre, con sus propiedades con tipo, búsqueda y filtros.

# Listar eventos de espacio de trabajo

Devuelve las definiciones de eventos del espacio de trabajo, ordenadas por nombre. Requiere una clave de API con el permiso `full`.

`GET /workspace/events`

## Parámetros de consulta

- `page` (integer): El número de página, empezando por 1.

- `limit` (integer): Las definiciones por página, de 1 a 250.

- `search` (string): Una búsqueda sin distinguir mayúsculas y minúsculas en una parte del nombre o del título.

- `match`, `order`, `direction`: consulta [Filtrado](https://emailit.com/es/docs/api-reference/filtering/).

### Claves de filtro

Los filtros usan parámetros de consulta `key.condition=value`, por ejemplo `name.starts_with=order.` o `created_at.after=2026-10-01`. Para las condiciones de cada tipo, consulta [Filtrado y ordenación](/es/docs/api-reference/filtering/).

| Clave | Tipo | Notas |
| --- | --- | --- |
| `name` | string | El nombre sin el prefijo `w:`. |
| `title` | string | |
| `created_at` | date | |
| `updated_at` | date | |

Claves de orden para `order`: `name`, `title`, `created_at`, `updated_at`. Por defecto, `name`, en orden ascendente.

## Devuelve

- `data` (object[]): Los [objetos de evento de espacio de trabajo](/es/docs/api-reference/workspace-events/get/) de esta página.

- `total_records` (integer): El número de definiciones que coinciden con la consulta.

- `next_page_url` (string | null): La ruta de la página siguiente, o `null` en la última página. Solo lleva `page` y `limit`; vuelve a añadir tu búsqueda y tus filtros cuando la sigas.

- `previous_page_url` (string | null): La ruta de la página anterior, o `null` en la primera página.

**Petición** `GET /workspace/events`

**cURL**

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

**Node.js**

```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**

```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**

```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'];
```

**200**

```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
}
```

---
Fuente: https://emailit.com/es/docs/api-reference/workspace-events/list/

## Eliminar un evento de espacio de trabajo — DELETE /workspace/events/{id}

> Elimina la definición de un evento de espacio de trabajo. Los eventos guardados se conservan, y los eventos nuevos de ese tipo se rechazan.

# Eliminar un evento de espacio de trabajo

Elimina la definición de un evento de espacio de trabajo. Requiere una clave de API con el permiso `full`.

Los eventos ya guardados con este tipo se conservan, en el registro de eventos y en los contactos. Los eventos nuevos de este tipo se rechazan con `422` hasta que vuelvas a definirlo. Los webhooks suscritos al tipo mantienen la suscripción.

`DELETE /workspace/events/{id}`

## Parámetros de ruta

- `id` (string, obligatorio): El ID de la definición (`etp_…`), su nombre o su tipo de evento (`w:…`).

## Devuelve

- `object` (string): Siempre `workspace_event`.

- `id` (string): El ID de la definición eliminada.

- `name` (string): Su nombre.

- `type` (string): Su tipo de evento, `w:` seguido del nombre.

- `deleted` (boolean): Siempre `true`.

Devuelve `404` si ninguna definición coincide.

**Petición** `DELETE /workspace/events/{id}`

**cURL**

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

**Node.js**

```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**

```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**

```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);
```

**200**

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

---
Fuente: https://emailit.com/es/docs/api-reference/workspace-events/delete/