Eventos do workspace

Defina eventos do workspace e os tipos das propriedades deles, para que os eventos w: que você envia sejam verificados.

URL basehttps://api.emailit.com/v2Autenticação Erros Limites de requisições

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

Criar um evento do workspace

Define um evento do workspace: um nome e as propriedades que todo evento desse tipo leva, cada uma com um tipo. Depois, você o envia como w:<name>, e o Emailit rejeita os eventos que não correspondem à definição. Requer uma chave de API com escopo full.

Os eventos do workspace estão incluídos nos planos Pro, Business e Custom. Um workspace pode definir tantos quantos forem os tipos de evento do plano: 100 no Pro e 1.000 no Business, sem limite no Custom. Os eventos personalizados (c:<name>) não precisam de definição. Consulte Eventos do workspace.

POST/workspace/events

Parâmetros do corpo

namestringobrigatório

O nome do evento, por exemplo, customer.type: de 1 a 100 letras, dígitos, ., - ou _, começando com uma letra ou um dígito. Você também pode enviá-lo com o prefixo (w:customer.type); o prefixo é removido. Deve ser único no workspace.

titlestring | null

Um nome legível exibido no painel, com até 120 caracteres.

descriptionstring | null

Observação para a sua equipe, com até 1.000 caracteres.

propertiesobject[]

Até 50 definições de propriedade. Padrão [], o que significa que os eventos desse tipo não levam propriedades. Cada uma tem:

name (obrigatório): de 1 a 64 letras, dígitos, - ou _, começando com uma letra ou um dígito. Pontos não são permitidos, porque os filtros de webhook e os templates usam pontos para acessar valores aninhados. Os nomes devem ser únicos dentro da definição.
type (obrigatório): string, number, date ou boolean, em maiúsculas ou minúsculas.
title: um rótulo, com até 120 caracteres.
description: até 1.000 caracteres.
required: true se todo evento tiver de incluir a propriedade. Padrão false.

Retorno

Retorna 201 Created com o objeto de evento do workspace.

Status	Quando
`403`	A chave de API não tem o escopo `full`, ou o workspace está no Pay as you go: `error` é `plan_required` e `required_plan` é `pro`.
`409`	Já existe um evento do workspace com esse nome. `errors.name` informa isso.
`422`	Um campo é inválido: `errors` é indexado pelo caminho dele, como `name` ou `properties.1.type`, e `message` repete o primeiro problema. Também é retornado com `code: "workspace_events_limit"` quando o workspace já tem tantos eventos do workspace quanto o plano permite, e para um nome que começa com `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"]
  }
}

Obter um evento do workspace

Obtém a definição de um evento do workspace: o nome, o título e as propriedades que os sistemas que enviam o evento devem seguir. Requer uma chave de API com escopo full.

GET/workspace/events/{id}

Parâmetros de caminho

idstringobrigatório

O ID da definição (etp_…), o nome dela (customer.type) ou o tipo de evento dela (w:customer.type). Codifique o : para URL se o seu cliente não fizer isso.

Retorno

Retorna o objeto de evento do workspace.

objectstring

Sempre workspace_event.

idstring

ID da definição, com o prefixo etp_.

namestring

O nome do evento, sem o prefixo.

typestring

O tipo a usar no envio e nos filtros: w: seguido do nome.

titlestring | null

Um nome legível, exibido no painel no lugar do tipo, por exemplo, na atividade de um contato.

descriptionstring | null

Observação para a sua equipe.

propertiesobject[]

As propriedades que um evento desse tipo pode levar, cada uma com:

name: a chave em properties do evento.
type: string, number, date ou boolean. Consulte Tipos de propriedade.
title, description: rótulos opcionais, ou null.
required: se todo evento tem de incluí-la.

created_at, updated_atstring

Timestamps em UTC.

Retorna 404 com error: "Workspace event not found" se nenhuma definição corresponder.

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

Atualizar um evento do workspace

Atualiza os campos que você enviar e mantém os outros inalterados. Requer uma chave de API com escopo full.

A definição só verifica os eventos novos. Os eventos já armazenados mantêm o tipo e as propriedades deles, então, depois de uma alteração, os eventos mais antigos podem ter propriedades que a definição não lista mais.

properties substitui a lista inteira. Para adicionar uma propriedade, envie a lista atual mais a nova.
Renomear altera o tipo a enviar. Os eventos armazenados com o nome antigo o mantêm, e os eventos novos com o nome antigo são rejeitados, a menos que você o defina de novo.

POST/workspace/events/{id}

Parâmetros de caminho

idstringobrigatório

O ID da definição (etp_…), o nome dela ou o tipo de evento dela (w:…).

Parâmetros do corpo

namestring

Um novo nome, com as mesmas regras da criação.

titlestring | null

Até 120 caracteres. null ou uma string vazia o apaga.

descriptionstring | null

Até 1.000 caracteres. null ou uma string vazia a apaga.

propertiesobject[]

A nova lista de propriedades, com até 50, como na criação. [] remove todas as propriedades.

Retorno

Retorna o objeto de evento do workspace atualizado.

Status	Quando
`404`	Nenhuma definição corresponde a `id`.
`409`	Outro evento do workspace já tem o novo nome.
`422`	Um campo é inválido: `errors` é indexado pelo caminho dele, e `message` repete o primeiro 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 do workspace

Retorna as definições de eventos do workspace, ordenadas por nome. Requer uma chave de API com escopo full.

GET/workspace/events

Parâmetros de consulta

pageintegerpadrão: 1

Número da página, a partir de 1.

limitintegerpadrão: 100

Definições por página, de 1 a 250.

searchstring

Busca sem diferenciar maiúsculas de minúsculas em parte do nome ou do título.

matchstring

all (padrão) exige todos os filtros. or corresponde a qualquer filtro. Consulte Filtragem.

orderstring

Chave de ordenação desta lista. Consulte as chaves de ordenação abaixo.

directionstring

asc ou desc.

Chaves de filtro

Os filtros usam parâmetros de consulta key.condition=value, por exemplo, name.starts_with=order. ou created_at.after=2026-10-01. Consulte Filtragem para as condições de cada tipo.

Chave	Tipo	Observações
`name`	string	O nome sem o prefixo `w:`.
`title`	string
`created_at`	date
`updated_at`	date

Chaves de ordenação para order: name, title, created_at, updated_at. O padrão é name, em ordem crescente.

Retorno

dataobject[]

Objetos de evento do workspace desta página.

total_recordsinteger

Número de definições que correspondem à consulta.

next_page_urlstring | null

Caminho da próxima página, ou null na última página. Ele leva apenas page e limit; adicione de novo a sua busca e os seus filtros ao segui-lo.

previous_page_urlstring | null

Caminho da página anterior, ou null na primeira 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
}

Excluir um evento do workspace

Exclui a definição de um evento do workspace. Requer uma chave de API com escopo full.

Os eventos já armazenados com esse tipo são mantidos, no log de eventos e nos contatos. Os eventos novos desse tipo são rejeitados com 422 até você defini-lo de novo. Os webhooks inscritos nesse tipo mantêm a inscrição.

DELETE/workspace/events/{id}

Parâmetros de caminho

idstringobrigatório

O ID da definição (etp_…), o nome dela ou o tipo de evento dela (w:…).

Retorno

objectstring

Sempre workspace_event.

idstring

ID da definição excluída.

namestring

O nome dela.

typestring

O tipo de evento dela, w: seguido do nome.

deletedboolean

Sempre true.

Retorna 404 se nenhuma definição corresponder.

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
}