Eventos de espacio de trabajo

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

URL basehttps://api.emailit.com/v2Autenticación Errores Límites de velocidad

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

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.

POST/workspace/events

Parámetros del cuerpo

namestringobligatorio

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.

titlestring | null

Un nombre legible que se muestra en el panel, de hasta 120 caracteres.

descriptionstring | null

Una nota para tu equipo, de hasta 1000 caracteres.

propertiesobject[]

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.

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:`.

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

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

idstringobligatorio

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.

objectstring

Siempre workspace_event.

idstring

El ID de la definición, con el prefijo etp_.

namestring

El nombre del evento, sin el prefijo.

typestring

El tipo que se usa para enviar y filtrar: w: seguido del nombre.

titlestring | null

Un nombre legible que el panel muestra en lugar del tipo, por ejemplo en la actividad de un contacto.

descriptionstring | null

Una nota para tu equipo.

propertiesobject[]

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.
title, description: etiquetas opcionales, o null.
required: si todos los eventos tienen que incluirla.

created_at, updated_atstring

Las marcas de tiempo en UTC.

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

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

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

idstringobligatorio

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

Parámetros del cuerpo

namestring

Un nombre nuevo, con las mismas reglas que al crearlo.

titlestring | null

De hasta 120 caracteres. null o una cadena vacía lo borran.

descriptionstring | null

De hasta 1000 caracteres. null o una cadena vacía la borran.

propertiesobject[]

La nueva lista de propiedades, hasta 50, como al crearlo. [] elimina todas las propiedades.

Devuelve

Devuelve el objeto de evento de espacio de trabajo 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.

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

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

pageintegerpor defecto: 1

El número de página, empezando por 1.

limitintegerpor defecto: 100

Las definiciones por página, de 1 a 250.

searchstring

Una búsqueda sin distinguir mayúsculas y minúsculas en una parte del nombre o del título.

matchstring

all (por defecto) exige que se cumplan todos los filtros. or coincide con cualquier filtro. Consulta Filtrado.

orderstring

Clave de ordenación de esta lista. Consulta las claves de ordenación más abajo.

directionstring

asc o desc.

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.

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

dataobject[]

Los objetos de evento de espacio de trabajo de esta página.

total_recordsinteger

El número de definiciones que coinciden con la consulta.

next_page_urlstring | 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_urlstring | null

La ruta de la página anterior, o null en la primera página.

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
}

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

idstringobligatorio

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

Devuelve

objectstring

Siempre workspace_event.

idstring

El ID de la definición eliminada.

namestring

Su nombre.

typestring

Su tipo de evento, w: seguido del nombre.

deletedboolean

Siempre true.

Devuelve 404 si ninguna definición coincide.

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
}