Mensagens

Endpoints de observabilidade sobre e-mails enviados: status, linha do tempo de eventos e métricas agregadas.

Listar mensagens

GET /v1/messages

Query params (todos opcionais):

Param	Descrição
cursor	RFC3339 — veja Paginação
limit	Default 50
status	Filtra por status exato (ex.: delivered, bounced)
search	Busca por assunto, destinatário, rfc_message_id ou id
period	24h, 7d, 14d ou 30d
api_key_id	Filtra por chave usada no envio (UUID)

Resposta — 200:

{
  "messages": [
    {
      "id": "uuid",
      "status": "delivered",
      "stream": "transactional",
      "from_address": "noreply@meudominio.com",
      "to_address": "cliente@exemplo.com",
      "subject": "Confirmação de pedido",
      "recipient_domain": "exemplo.com",
      "api_key_id": "uuid",
      "created_at": "...",
      "queued_at": "...",
      "sent_at": "...",
      "delivered_at": "...",
      "failed_at": null,
      "first_opened_at": null,
      "first_clicked_at": null,
      "last_error": null
    }
  ]
}

Consultar uma mensagem

GET /v1/messages/{id}

Retorna o mesmo objeto acima. 404 se não encontrada ou pertencente a outro tenant.

Eventos de uma mensagem

GET /v1/messages/{id}/events

Linha do tempo cronológica de eventos (fila, envio, entrega, bounce, abertura, clique etc.):

{
  "events": [
    {
      "type": "hard_bounce",
      "occurred_at": "...",
      "recipient": "cliente@exemplo.com",
      "smtp_code": 550,
      "enhanced_code": "5.1.1",
      "diagnostic": "...",
      "mx_host": "...",
      "click_url": null
    }
  ]
}

Séries temporais

GET /v1/messages/timeseries?days=14

days: 1 a 90 (default 14). Retorna contagem diária por status:

{
  "since": "...",
  "days": [
    { "date": "2026-08-01", "queued": 0, "processing": 0, "sent": 10, "delivered": 9,
      "deferred": 0, "bounced": 1, "failed": 0, "rejected": 0, "complained": 0 }
  ]
}

Engajamento

GET /v1/messages/engagement?days=14

{ "since": "...", "delivered": 120, "opened": 80, "clicked": 30 }

Métricas consolidadas

GET /v1/messages/metrics?days=14&domain_id=<uuid opcional>

Retorna current/previous (totais do período e do período anterior, para comparação), timeseries (multi-série por tipo de evento) e by_domain (breakdown por domínio remetente).

Erros comuns

401 sem API Key, 400 parâmetro de query inválido (ex.: period/days fora do permitido), 429 rate limit.