ViaPost Docs

Appearance

Paginação e rate limiting ​

Paginação ​

Endpoints de listagem que suportam paginação usam cursor baseado em timestamp:

GET /v1/messages?cursor=2026-08-29T12:00:00Z&limit=50
  • cursor: RFC3339; retorna itens anteriores a esse instante. Se omitido, assume o momento atual + 24h (ou seja, retorna os mais recentes).
  • limit: quantidade máxima de itens (default 50).

Suportado em GET /v1/messages e GET /v1/inbound-messages. GET /v1/domains não expõe cursor/limit — retorna até 50 domínios do tenant.

Para paginar, use o timestamp do último item da página anterior como novo cursor.

Rate limiting ​

Cada tenant tem um orçamento de requisições por segundo. Ao excedê-lo, a API retorna:

HTTP/1.1 429 Too Many Requests
json
{ "error": { "code": "rate_limited", "message": "..." } }

Implemente backoff exponencial ao receber 429. O limite se aplica por tenant (todas as API Keys do mesmo tenant compartilham o mesmo orçamento), nas rotas de domínios, envio, mensagens, mensagens recebidas (inbound) e webhooks.

Idempotência ​

POST /v1/send aceita um header opcional Idempotency-Key:

Idempotency-Key: pedido-12345-tentativa-1

Reenviar a mesma chave para o mesmo tenant retorna 409 Conflict em vez de processar o envio novamente — use isso para evitar duplicidade em retries de rede.