# Eventos do workspace API

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

URL base: `https://api.emailit.com/v2`. Autentique-se com `Authorization: Bearer <API key>`.

## Criar um evento do workspace — POST /workspace/events

> Defina um evento do workspace e as propriedades tipadas dele. Os eventos desse tipo passam a ser enviados com o prefixo w: e verificados em relação à definição.

# 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](/pt/docs/events/workspace-events/).

`POST /workspace/events`

## Parâmetros do corpo

- `name` (string, obrigató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.

- `title` (string | null): Um nome legível exibido no painel, com até 120 caracteres.

- `description` (string | null): Observação para a sua equipe, com até 1.000 caracteres.

- `properties` (object[]): 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](/pt/docs/api-reference/workspace-events/get/).

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

**Requisição** `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"]
  }
}
```

---
Fonte: https://emailit.com/pt/docs/api-reference/workspace-events/create/

## Obter um evento do workspace — GET /workspace/events/{id}

> Obtenha a definição de um evento do workspace pelo ID ou pelo nome, com as propriedades tipadas dela.

# 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

- `id` (string, obrigató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.

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

- `id` (string): ID da definição, com o prefixo `etp_`.

- `name` (string): O nome do evento, sem o prefixo.

- `type` (string): O tipo a usar no envio e nos filtros: `w:` seguido do nome.

- `title` (string | null): Um nome legível, exibido no painel no lugar do tipo, por exemplo, na atividade de um contato.

- `description` (string | null): Observação para a sua equipe.

- `properties` (object[]): 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](/pt/docs/events/workspace-events/#property-types). - `title`, `description`: rótulos opcionais, ou `null`. - `required`: se todo evento tem de incluí-la.

- `created_at, updated_at` (string): Timestamps em UTC.

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

**Requisição** `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"
}
```

---
Fonte: https://emailit.com/pt/docs/api-reference/workspace-events/get/

## Atualizar um evento do workspace — POST /workspace/events/{id}

> Renomeie um evento do workspace ou altere o título, a descrição ou as propriedades dele. Os eventos já armazenados não mudam.

# 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

- `id` (string, obrigatório): O ID da definição (`etp_…`), o nome dela ou o tipo de evento dela (`w:…`).

## Parâmetros do corpo

- `name` (string): Um novo nome, com as mesmas regras da [criação](/pt/docs/api-reference/workspace-events/create/#body-parameters).

- `title` (string | null): Até 120 caracteres. `null` ou uma string vazia o apaga.

- `description` (string | null): Até 1.000 caracteres. `null` ou uma string vazia a apaga.

- `properties` (object[]): A nova lista de propriedades, com até 50, como na [criação](/pt/docs/api-reference/workspace-events/create/#body-parameters). `[]` remove todas as propriedades.

## Retorno

Retorna o [objeto de evento do workspace](/pt/docs/api-reference/workspace-events/get/) 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. |

**Requisição** `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"]
  }
}
```

---
Fonte: https://emailit.com/pt/docs/api-reference/workspace-events/update/

## Listar eventos do workspace — GET /workspace/events

> Liste as definições de eventos do workspace em ordem de nome, com as propriedades tipadas, busca e filtros.

# 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

- `page` (integer): Número da página, a partir de 1.

- `limit` (integer): Definições por página, de 1 a 250.

- `search` (string): Busca sem diferenciar maiúsculas de minúsculas em parte do nome ou do título.

- `match`, `order`, `direction`: consulte [Filtragem](https://emailit.com/pt/docs/api-reference/filtering/).

### 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](/pt/docs/api-reference/filtering/) 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

- `data` (object[]): [Objetos de evento do workspace](/pt/docs/api-reference/workspace-events/get/) desta página.

- `total_records` (integer): Número de definições que correspondem à consulta.

- `next_page_url` (string | 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_url` (string | null): Caminho da página anterior, ou `null` na primeira página.

**Requisição** `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
}
```

---
Fonte: https://emailit.com/pt/docs/api-reference/workspace-events/list/

## Excluir um evento do workspace — DELETE /workspace/events/{id}

> Exclua a definição de um evento do workspace. Os eventos armazenados são mantidos, e os eventos novos desse tipo são rejeitados.

# 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

- `id` (string, obrigatório): O ID da definição (`etp_…`), o nome dela ou o tipo de evento dela (`w:…`).

## Retorno

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

- `id` (string): ID da definição excluída.

- `name` (string): O nome dela.

- `type` (string): O tipo de evento dela, `w:` seguido do nome.

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

Retorna `404` se nenhuma definição corresponder.

**Requisição** `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
}
```

---
Fonte: https://emailit.com/pt/docs/api-reference/workspace-events/delete/