Contatos e eventos

Um contato é uma pessoa que recebe as suas sequências, 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#

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

{
  "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#

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

Pelo MCP#

As ferramentas track_event (escopo send, com idempotency_key) e upsert_contact (escopo send) fazem o mesmo pelo servidor MCP, para o seu agente de IA registrar cadastros e compras.