# Contatos e eventos

> Contatos com atributos e eventos do seu app pela API do Couryo (POST /v1/contacts e POST /v1/events), idempotentes, que disparam e encerram sequências. Sem cobrança por contato.

Fonte: https://couryo.com/docs/contacts

Um **contato** é uma pessoa que recebe as suas [sequências](https://couryo.com/docs/sequences.md), com atributos para personalizar (`nome`, `plano`, `timezone`). Um **evento** é algo que aconteceu no seu app (`user.signed_up`, `order.paid`): ele coloca o contato nas sequências que começam por esse nome e encerra as que esperam essa conversão.

**Sem cobrança por contato.** Ter 100 ou 100 mil contatos custa o mesmo: só os e-mails enviados contam na cota do plano.

## Mandar um evento

```bash title="cURL"
curl https://api.couryo.com/v1/events \
  -H "Authorization: Bearer $COURYO_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: signup-ana-1042" \
  -d '{
    "contact": { "email": "ana@exemplo.com.br", "attributes": { "nome": "Ana", "plano": "free" } },
    "name": "user.signed_up",
    "properties": { "origem": "site" }
  }'
```

```json title="Resposta 201"
{
  "id": "cev_8k2m4q9w1x7z3abc",
  "contact_id": "con_3n5p7r9t1v2x4zab",
  "name": "user.signed_up",
  "enrolled": [{ "sequence_id": "seq_q8w2e4r6t8y0u1io", "enrollment_id": "enr_a1s3d5f7g9h2j4kl" }],
  "converted": [],
  "created_at": "2026-10-08T18:30:00Z"
}
```

- O contato é criado ou atualizado pelo e-mail (os atributos se juntam aos que já existem).
- `enrolled` lista as sequências ativas que este evento iniciou. Um contato entra numa sequência por evento **uma vez**; para colocar de novo, use a entrada manual.
- `converted` lista as inscrições encerradas porque este é o **evento de conversão** delas.
- `properties` ficam disponíveis nos e-mails da sequência como `{{event.origem}}`.
- Nome do evento: letras, números, `.`, `_`, `:` e `-`, até 100 caracteres.
- Escopo: chave `send` (ou `admin`). Uma chave `ck_test_` coloca o contato em modo de teste: os e-mails da sequência são capturados e nunca entregues.

### Idempotência

Mande `Idempotency-Key` em todo evento. A mesma chave com o mesmo corpo devolve a mesma resposta, com `Idempotent-Replayed: true`, e não cria outro evento nem outra inscrição. Corpo diferente com a mesma chave devolve `409 idempotency_conflict`. Além das 24 horas de sempre, o evento guarda a chave: repetir depois disso ainda devolve o mesmo evento.

## Contatos

```bash title="Criar ou atualizar (upsert)"
curl https://api.couryo.com/v1/contacts \
  -H "Authorization: Bearer $COURYO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "email": "ana@exemplo.com.br", "attributes": { "plano": "pro", "cidade": null } }'
```

- Responde `201` quando cria e `200` quando atualiza.
- Atributos são valores simples (texto, número, verdadeiro ou falso). `null` apaga o atributo.
- O atributo `timezone` (por exemplo, `America/Manaus`) é usado pelas esperas "até as HH:mm no fuso do contato".
- `subscribed` é `false` quando o endereço está na [lista de supressão](https://couryo.com/docs/suppressions.md) para marketing (descadastro, devolução, reclamação ou manual). O descadastro sempre vale: o contato não recebe sequências de marketing, e uma sequência em andamento termina na hora.

| Método e caminho | Escopo | O que faz |
|---|---|---|
| `POST /v1/contacts` | `send` | cria ou atualiza pelo e-mail |
| `GET /v1/contacts` | `read` | lista, do mais novo; `q` busca por parte do e-mail, `limit` e `starting_after` paginam |
| `GET /v1/contacts/{id}` | `read` | um contato, pelo `id` (`con_...`) ou pelo e-mail |
| `PATCH /v1/contacts/{id}` | `admin` | muda o e-mail ou os atributos |
| `DELETE /v1/contacts/{id}` | `admin` | apaga o contato e os eventos dele; ele sai das sequências (a supressão continua) |
| `POST /v1/events` | `send` | registra um evento do contato |

## Pelo MCP

As ferramentas `track_event` (escopo `send`, com `idempotency_key`) e `upsert_contact` (escopo `send`) fazem o mesmo pelo [servidor MCP](https://couryo.com/docs/mcp.md), para o seu agente de IA registrar cadastros e compras.