RaviMail
Recursos
Email transacional Campanhas Sequências automáticas Caixa de entrada + IA Funil de vendas Alertas WhatsApp Ver todos os recursos →
Mais
Preços Desenvolvedores API Documentação
Entrar Criar Conta
Referência da API

155 endpoints REST. Clique pra expandir.

Cada endpoint mostra descrição, parâmetros, exemplo cURL pronto e códigos de resposta. Base URL: https://api.ravimail.com.br

Quickstart pra devs OpenAPI 3.0 spec
155
Endpoints totais
26
Grupos de recursos
107
Paths únicos
OpenAPI 3.0
Spec ↗ Postman/Insomnia

Nenhum endpoint encontrado

Tente outros termos ou .

Account

9 endpoints

GET
/v1/account/balance

Saldo atual + total gasto

O que faz

Retorna saldo em créditos disponíveis, total já gasto histórico e estimativa de quanto tempo o saldo dura no ritmo atual. Use pra alertas de saldo baixo e dashboards financeiros.

Exemplo

curl 'https://api.ravimail.com.br/v1/account/balance' \ -H 'Authorization: Bearer rvm_live_xxxxxxxx'
// composer require ravisystems/ravimail-php use Ravimail\Client; $rm = new Client('rvm_live_xxxxxxxx'); $result = $rm->account->list();

Códigos de resposta

200 Saldo

Exemplo de resposta

{ "data": { "credits": 12500, "currency": "BRL", "total_spent": 47230.5, "estimated_runway_days": 28 } }

Headers: X-Request-Id, X-RateLimit-Limit, X-RateLimit-Remaining

GET
/v1/account/usage

Uso por categoria

O que faz

Uso detalhado por categoria (transactional, campaigns, verifications, AI tokens) no período selecionado via `period` query param (current_month / last_30d / all_time). Útil pra cobrança interna em SaaS multi-tenant ou análise de custos.

Exemplo

curl 'https://api.ravimail.com.br/v1/account/usage' \ -H 'Authorization: Bearer rvm_live_xxxxxxxx'
// composer require ravisystems/ravimail-php use Ravimail\Client; $rm = new Client('rvm_live_xxxxxxxx'); $result = $rm->account->list();

Códigos de resposta

200 Uso agregado

Exemplo de resposta

{ "data": { "period": "current_month", "sent": 4321, "verifications": 87, "ai_tokens": 12000, "cost_brl": 234.5 } }

Headers: X-Request-Id, X-RateLimit-Limit, X-RateLimit-Remaining

GET
/v1/account/transactions

Histórico de débitos/créditos

O que faz

Histórico completo de movimentações de saldo: cada envio que debitou créditos, cada recarga que creditou, ajustes manuais. Cursor-paginated. Útil pra reconciliação financeira e auditoria.

Exemplo

curl 'https://api.ravimail.com.br/v1/account/transactions' \ -H 'Authorization: Bearer rvm_live_xxxxxxxx'
// composer require ravisystems/ravimail-php use Ravimail\Client; $rm = new Client('rvm_live_xxxxxxxx'); $result = $rm->account->list();

Códigos de resposta

200 Transações cursor-paginated

Exemplo de resposta

{ "data": [ { "id": "tx_8901", "type": "debit", "amount": -0.05, "description": "Envio msg_abc", "at": "2026-05-19T14:30:00Z" } ], "meta": { "has_more": true, "next_cursor": "eyJpZCI6MTAwMH0=" } }

Headers: X-Request-Id, X-RateLimit-Limit, X-RateLimit-Remaining

GET
/v1/account/packages

Pacotes de crédito disponíveis pra top-up

O que faz

Lista os pacotes pré-definidos de recarga (com descontos por volume). Cada item: nome, valor BRL, créditos inclusos, vantagens. Use pra exibir opções de top-up no seu próprio app/dashboard.

Exemplo

curl 'https://api.ravimail.com.br/v1/account/packages' \ -H 'Authorization: Bearer rvm_live_xxxxxxxx'
// composer require ravisystems/ravimail-php use Ravimail\Client; $rm = new Client('rvm_live_xxxxxxxx'); $result = $rm->account->list();

Códigos de resposta

200 Lista

Exemplo de resposta

{ "data": [ { "id": "pkg_5k", "name": "5.000 emails", "price_brl": 50, "credits": 5000 } ], "meta": { "has_more": true, "next_cursor": "eyJpZCI6MTAwMH0=" } }

Headers: X-Request-Id, X-RateLimit-Limit, X-RateLimit-Remaining

POST
/v1/account/top-up

Cria PIX pra adicionar saldo

O que faz

Cria uma cobrança PIX pro pacote selecionado. Retorna QR code, copia-e-cola e link de pagamento. Após pagamento confirmado (webhook do gateway), os créditos são adicionados automaticamente ao saldo do user. Tempo médio de confirmação: 30s. Use no fluxo de top-up automático em SaaS.

Exemplo

curl -X POST 'https://api.ravimail.com.br/v1/account/top-up' \ -H 'Authorization: Bearer rvm_live_xxxxxxxx' \ -H 'Content-Type: application/json' \ -d '{ ... }'
// composer require ravisystems/ravimail-php use Ravimail\Client; $rm = new Client('rvm_live_xxxxxxxx'); $result = $rm->account->create([...]);

Códigos de resposta

201 PIX criado

Exemplo de resposta

{ "data": { "payment_id": "pay_xx99", "pix_code": "00020126...5204000053039865802BR...", "qr_code_url": "https://...", "amount_brl": 100, "credits": 10000, "expires_at": "2026-05-19T15:00:00Z" } }

Headers: X-Request-Id, X-RateLimit-Limit, X-RateLimit-Remaining

GET
/v1/account/payments

Histórico de pagamentos

O que faz

Histórico de pagamentos realizados (PIX/boleto/cartão), incluindo status, valor, método e nota fiscal vinculada quando emitida. Cursor-paginated.

Exemplo

curl 'https://api.ravimail.com.br/v1/account/payments' \ -H 'Authorization: Bearer rvm_live_xxxxxxxx'
// composer require ravisystems/ravimail-php use Ravimail\Client; $rm = new Client('rvm_live_xxxxxxxx'); $result = $rm->account->list();

Códigos de resposta

200 Pagamentos cursor-paginated

Exemplo de resposta

{ "data": [ { "id": "pay_xx99", "method": "PIX", "amount_brl": 100, "status": "confirmed", "paid_at": "2026-05-15T10:00:00Z" } ], "meta": { "has_more": true, "next_cursor": "eyJpZCI6MTAwMH0=" } }

Headers: X-Request-Id, X-RateLimit-Limit, X-RateLimit-Remaining

GET
/v1/account/subscription

Plano de assinatura ativo (ou null se free)

O que faz

Detalhe do plano de assinatura ativo: nome, valor mensal, limites inclusos, próxima cobrança. Retorna `null` se o user está no plano gratuito (paga apenas via créditos top-up).

Exemplo

curl 'https://api.ravimail.com.br/v1/account/subscription' \ -H 'Authorization: Bearer rvm_live_xxxxxxxx'
// composer require ravisystems/ravimail-php use Ravimail\Client; $rm = new Client('rvm_live_xxxxxxxx'); $result = $rm->account->list();

Códigos de resposta

200 Plano

Exemplo de resposta

{ "data": { "plan": "Pro", "price_monthly": 247, "next_charge_at": "2026-06-01T00:00:00Z", "included_emails": 100000 } }

Headers: X-Request-Id, X-RateLimit-Limit, X-RateLimit-Remaining

GET
/v1/account/suppression-attributes

Lê toggles de auto-suppression (bounce/complaint)

O que faz

Lê o estado dos toggles que controlam adição automática à suppression list. Por padrão: hard bounce = auto-suprime, complaint = auto-suprime. Você pode desabilitar em casos específicos (ex: ambiente de teste onde quer reenviar pra emails inválidos).

Exemplo

curl 'https://api.ravimail.com.br/v1/account/suppression-attributes' \ -H 'Authorization: Bearer rvm_live_xxxxxxxx'
// composer require ravisystems/ravimail-php use Ravimail\Client; $rm = new Client('rvm_live_xxxxxxxx'); $result = $rm->account->list();

Códigos de resposta

200 Toggles

Exemplo de resposta

{ "data": { "auto_suppress_bounce": true, "auto_suppress_complaint": true, "auto_suppress_unsubscribe": true } }

Headers: X-Request-Id, X-RateLimit-Limit, X-RateLimit-Remaining

PUT
/v1/account/suppression-attributes

Atualiza toggles de auto-suppression

O que faz

Atualiza os toggles de auto-suppression. **Cuidado:** desabilitar auto-suppress de complaints viola compliance — só faça em ambientes controlados e por janela curta.

Exemplo

curl -X PUT 'https://api.ravimail.com.br/v1/account/suppression-attributes' \ -H 'Authorization: Bearer rvm_live_xxxxxxxx' \ -H 'Content-Type: application/json' \ -d '{ ... }'
// composer require ravisystems/ravimail-php use Ravimail\Client; $rm = new Client('rvm_live_xxxxxxxx'); $result = $rm->account->request('put', '/v1/account/suppression-attributes');

Códigos de resposta

200 Atualizado

Exemplo de resposta

{ "data": { "auto_suppress_bounce": true, "auto_suppress_complaint": true, "auto_suppress_unsubscribe": true } }

Headers: X-Request-Id, X-RateLimit-Limit, X-RateLimit-Remaining

Analytics

9 endpoints

GET
/v1/analytics/summary

Resumo de números (range=24h|7d|30d)

O que faz

Resumo agregado de métricas (sent, delivered, bounced, opened, clicked, complained, unsubscribed + rates calculadas) na janela selecionada via `?range=24h|7d|30d`. Inclui comparação com período anterior pra ver tendência. Use em dashboards principais.

Exemplo

curl 'https://api.ravimail.com.br/v1/analytics/summary' \ -H 'Authorization: Bearer rvm_live_xxxxxxxx'
// composer require ravisystems/ravimail-php use Ravimail\Client; $rm = new Client('rvm_live_xxxxxxxx'); $result = $rm->analytics->list();

Códigos de resposta

200 Resumo

Exemplo de resposta

{ "data": { "range": "24h", "sent": 12450, "delivered": 12180, "bounced": 187, "opened": 4350, "clicked": 612, "complained": 3, "unsubscribed": 18, "delivery_rate": 97.83, "open_rate": 35.71, "click_rate": 14.07 } }

Headers: X-Request-Id, X-RateLimit-Limit, X-RateLimit-Remaining

GET
/v1/analytics/timeseries

Série temporal (metric=volume|errors|latency|sends)

O que faz

Série temporal de uma métrica específica com granularidade automática (hora pra 24h, dia pra 7d/30d). Use pra gráficos de linha. Aceita `?metric=` + `?range=` na query.

Exemplo

curl 'https://api.ravimail.com.br/v1/analytics/timeseries' \ -H 'Authorization: Bearer rvm_live_xxxxxxxx'
// composer require ravisystems/ravimail-php use Ravimail\Client; $rm = new Client('rvm_live_xxxxxxxx'); $result = $rm->analytics->list();

Códigos de resposta

200 Série

Exemplo de resposta

{ "data": { "data": [ { "t": "2026-05-19T13:00:00Z", "v": 287 }, { "t": "2026-05-19T14:00:00Z", "v": 412 } ] } }

Headers: X-Request-Id, X-RateLimit-Limit, X-RateLimit-Remaining

GET
/v1/analytics/by-domain

Split por domínio FROM

O que faz

Quebra métricas por domínio remetente. Use pra identificar qual domínio está performando melhor/pior em entregabilidade quando você usa múltiplos remetentes.

Exemplo

curl 'https://api.ravimail.com.br/v1/analytics/by-domain' \ -H 'Authorization: Bearer rvm_live_xxxxxxxx'
// composer require ravisystems/ravimail-php use Ravimail\Client; $rm = new Client('rvm_live_xxxxxxxx'); $result = $rm->analytics->list();

Códigos de resposta

200 Rows

Exemplo de resposta

{ "data": { "data": [ { "key": "gmail.com", "sent": 4521, "opened": 1623 }, { "key": "outlook.com", "sent": 2104, "opened": 678 } ] } }

Headers: X-Request-Id, X-RateLimit-Limit, X-RateLimit-Remaining

GET
/v1/analytics/by-ip

Split por IP do nó

O que faz

Quebra métricas por IP de envio. Útil pra ver qual IP tem mais bounces/complaints — pausa o IP problemático antes que afete reputação dos outros.

Exemplo

curl 'https://api.ravimail.com.br/v1/analytics/by-ip' \ -H 'Authorization: Bearer rvm_live_xxxxxxxx'
// composer require ravisystems/ravimail-php use Ravimail\Client; $rm = new Client('rvm_live_xxxxxxxx'); $result = $rm->analytics->list();

Códigos de resposta

200 Rows

Exemplo de resposta

{ "data": { "data": [ { "key": "gmail.com", "sent": 4521, "opened": 1623 }, { "key": "outlook.com", "sent": 2104, "opened": 678 } ] } }

Headers: X-Request-Id, X-RateLimit-Limit, X-RateLimit-Remaining

GET
/v1/analytics/by-node

Split por nó

O que faz

Quebra métricas por nó (servidor SMTP). Útil quando você tem múltiplos nós e quer comparar saúde agregada de cada servidor físico.

Exemplo

curl 'https://api.ravimail.com.br/v1/analytics/by-node' \ -H 'Authorization: Bearer rvm_live_xxxxxxxx'
// composer require ravisystems/ravimail-php use Ravimail\Client; $rm = new Client('rvm_live_xxxxxxxx'); $result = $rm->analytics->list();

Códigos de resposta

200 Rows

Exemplo de resposta

{ "data": { "data": [ { "key": "gmail.com", "sent": 4521, "opened": 1623 }, { "key": "outlook.com", "sent": 2104, "opened": 678 } ] } }

Headers: X-Request-Id, X-RateLimit-Limit, X-RateLimit-Remaining

GET
/v1/analytics/by-isp

Split por bucket ISP (gmail/microsoft/yahoo/...)

O que faz

Quebra métricas por bucket de ISP destino: gmail, microsoft (outlook/hotmail/live), yahoo, uol, terra, locaweb, outros. Crítico pra deliverability — bucket gmail e MS exigem reputação alta, outros toleram mais.

Exemplo

curl 'https://api.ravimail.com.br/v1/analytics/by-isp' \ -H 'Authorization: Bearer rvm_live_xxxxxxxx'
// composer require ravisystems/ravimail-php use Ravimail\Client; $rm = new Client('rvm_live_xxxxxxxx'); $result = $rm->analytics->list();

Códigos de resposta

200 Rows

Exemplo de resposta

{ "data": { "data": [ { "key": "gmail.com", "sent": 4521, "opened": 1623 }, { "key": "outlook.com", "sent": 2104, "opened": 678 } ] } }

Headers: X-Request-Id, X-RateLimit-Limit, X-RateLimit-Remaining

GET
/v1/analytics/by-device

Split por device (iOS/Android/macOS/Windows)

O que faz

Quebra opens/clicks por device detectado via User-Agent. Use pra otimizar design (se 80% abre em mobile, foque em template responsivo) e priorização de testes A/B.

Exemplo

curl 'https://api.ravimail.com.br/v1/analytics/by-device' \ -H 'Authorization: Bearer rvm_live_xxxxxxxx'
// composer require ravisystems/ravimail-php use Ravimail\Client; $rm = new Client('rvm_live_xxxxxxxx'); $result = $rm->analytics->list();

Códigos de resposta

200 Rows

Exemplo de resposta

{ "data": { "data": [ { "key": "gmail.com", "sent": 4521, "opened": 1623 }, { "key": "outlook.com", "sent": 2104, "opened": 678 } ] } }

Headers: X-Request-Id, X-RateLimit-Limit, X-RateLimit-Remaining

GET
/v1/analytics/by-country

Split por país (GeoLite2)

O que faz

Quebra opens/clicks por país via GeoLite2 lookup do IP. Útil pra ver dispersão geográfica da base e ajustar horários de envio por timezone dominante.

Exemplo

curl 'https://api.ravimail.com.br/v1/analytics/by-country' \ -H 'Authorization: Bearer rvm_live_xxxxxxxx'
// composer require ravisystems/ravimail-php use Ravimail\Client; $rm = new Client('rvm_live_xxxxxxxx'); $result = $rm->analytics->list();

Códigos de resposta

200 Rows

Exemplo de resposta

{ "data": { "data": [ { "key": "gmail.com", "sent": 4521, "opened": 1623 }, { "key": "outlook.com", "sent": 2104, "opened": 678 } ] } }

Headers: X-Request-Id, X-RateLimit-Limit, X-RateLimit-Remaining

GET
/v1/analytics/clicks/heatmap

Heatmap de cliques por URL/geo

O que faz

Heatmap de cliques por URL clicada (qual link gerou mais conversão) e/ou por país. Use pra otimizar CTAs (links com 0 cliques podem ser removidos) e direcionar foco geográfico.

Exemplo

curl 'https://api.ravimail.com.br/v1/analytics/clicks/heatmap' \ -H 'Authorization: Bearer rvm_live_xxxxxxxx'
// composer require ravisystems/ravimail-php use Ravimail\Client; $rm = new Client('rvm_live_xxxxxxxx'); $result = $rm->analytics->list();

Códigos de resposta

200 Heatmap

Exemplo de resposta

{ "data": { "by_url": [ { "url": "https://app.exemplo.com/login", "clicks": 234 }, { "url": "https://app.exemplo.com/upgrade", "clicks": 87 } ], "by_country": [ { "country": "BR", "clicks": 290 }, { "country": "PT", "clicks": 31 } ] } }

Headers: X-Request-Id, X-RateLimit-Limit, X-RateLimit-Remaining

Campaigns

12 endpoints

GET
/v1/campaigns

Lista campanhas

O que faz

Lista campanhas do user com contadores de envio em tempo real (sent, delivered, opened, clicked, bounced, complained). Filtros por status (draft/scheduled/sending/sent/cancelled). Cursor-paginated, ordem decrescente por data de criação.

Exemplo

curl 'https://api.ravimail.com.br/v1/campaigns' \ -H 'Authorization: Bearer rvm_live_xxxxxxxx'
// composer require ravisystems/ravimail-php use Ravimail\Client; $rm = new Client('rvm_live_xxxxxxxx'); $result = $rm->campaigns->list();

Códigos de resposta

200 Lista cursor

Exemplo de resposta

{ "data": [ { "id": 42, "name": "Black Friday", "status": "sending", "sent": 891 } ], "meta": { "has_more": true, "next_cursor": "eyJpZCI6MTAwMH0=" } }

Headers: X-Request-Id, X-RateLimit-Limit, X-RateLimit-Remaining

POST
/v1/campaigns

Cria campanha (status=draft ou scheduled)

O que faz

Cria campanha em status `draft` (precisa /start pra iniciar) ou `scheduled` se passar `scheduled_for`. Body aceita: name, list_id, template_id, subject (override), from_domain_id, segment_id (opcional), ab_test (opcional). Disparo respeita warmup, horário comercial e throttle per-bucket de ISP.

Exemplo

curl -X POST 'https://api.ravimail.com.br/v1/campaigns' \ -H 'Authorization: Bearer rvm_live_xxxxxxxx' \ -H 'Content-Type: application/json' \ -d '{ ... }'
// composer require ravisystems/ravimail-php use Ravimail\Client; $rm = new Client('rvm_live_xxxxxxxx'); $result = $rm->campaigns->create([...]);

Códigos de resposta

201 Criada

Exemplo de resposta

{ "data": [ { "id": 42, "name": "Black Friday", "status": "sending", "sent": 891 } ], "meta": { "has_more": true, "next_cursor": "eyJpZCI6MTAwMH0=" } }

Headers: X-Request-Id, X-RateLimit-Limit, X-RateLimit-Remaining

GET
/v1/campaigns/{id}

Detalhes da campanha

O que faz

Detalhe completo da campanha: configuração, status, counters (sent/delivered/opened/clicked/bounced/complained/unsubscribed), datas, info de A/B test quando aplicável, lista/segmento alvo.

Parâmetros

path
id string obrigatório

Exemplo

curl 'https://api.ravimail.com.br/v1/campaigns/123' \ -H 'Authorization: Bearer rvm_live_xxxxxxxx'
// composer require ravisystems/ravimail-php use Ravimail\Client; $rm = new Client('rvm_live_xxxxxxxx'); $result = $rm->campaigns->get(123);

Códigos de resposta

200 Detalhes

Exemplo de resposta

{ "data": { "id": 42, "name": "Black Friday", "status": "sending", "list_id": 7, "template_id": 17, "recipients_total": 1543, "sent": 891, "delivered": 855, "opened": 312, "clicked": 47, "bounced": 11, "created_at": "2026-05-19T09:00:00Z" } }

Headers: X-Request-Id, X-RateLimit-Limit, X-RateLimit-Remaining

DELETE
/v1/campaigns/{id}

Remove campanha (?force=1)

O que faz

Remove campanha. Em campanhas com histórico de envio, exige `?force=1` pra confirmar. Mensagens já entregues ficam no histórico (analytics agregado preservado). Campanha em andamento (`sending`) deve ser cancelada antes via /cancel.

Parâmetros

path
id string obrigatório

Exemplo

curl -X DELETE 'https://api.ravimail.com.br/v1/campaigns/123' \ -H 'Authorization: Bearer rvm_live_xxxxxxxx'
// composer require ravisystems/ravimail-php use Ravimail\Client; $rm = new Client('rvm_live_xxxxxxxx'); $result = $rm->campaigns->delete(123);

Códigos de resposta

204 Removida

Exemplo de resposta

# 204 No Content — body vazio HTTP/1.1 204 No Content X-Request-Id: req_a1b2c3d4e5f6
POST
/v1/campaigns/{id}/start

Promove draft → scheduled

O que faz

Move a campanha de `draft` pra `scheduled` (ou `sending` se já está na hora). Workers do dispatcher começam a processar a fila de destinatários respeitando warmup, throttle por bucket de ISP e horário comercial configurado. Idempotente: chamar de novo em campanha já iniciada retorna 200 sem efeito colateral.

Parâmetros

path
id string obrigatório

Exemplo

curl -X POST 'https://api.ravimail.com.br/v1/campaigns/123/start' \ -H 'Authorization: Bearer rvm_live_xxxxxxxx' \ -H 'Content-Type: application/json' \ -d '{ ... }'
// composer require ravisystems/ravimail-php use Ravimail\Client; $rm = new Client('rvm_live_xxxxxxxx'); $result = $rm->campaigns->create([...]);

Códigos de resposta

200 OK

Exemplo de resposta

{ "data": [ { "id": 42, "name": "Black Friday", "status": "sending", "sent": 891 } ], "meta": { "has_more": true, "next_cursor": "eyJpZCI6MTAwMH0=" } }

Headers: X-Request-Id, X-RateLimit-Limit, X-RateLimit-Remaining

POST
/v1/campaigns/{id}/pause

Pausa send

O que faz

Pausa imediatamente o envio em andamento. Mensagens já no Postfix são draiñadas (mantidas em hold, não deletadas). Use quando detectar problema mid-flight (template errado, lista contaminada, métrica de bounce subindo). Resume via /resume preserva o estado dos destinatários já processados — só os pending são retomados.

Parâmetros

path
id string obrigatório

Exemplo

curl -X POST 'https://api.ravimail.com.br/v1/campaigns/123/pause' \ -H 'Authorization: Bearer rvm_live_xxxxxxxx' \ -H 'Content-Type: application/json' \ -d '{ ... }'
// composer require ravisystems/ravimail-php use Ravimail\Client; $rm = new Client('rvm_live_xxxxxxxx'); $result = $rm->campaigns->create([...]);

Códigos de resposta

200 OK

Exemplo de resposta

{ "data": [ { "id": 42, "name": "Black Friday", "status": "sending", "sent": 891 } ], "meta": { "has_more": true, "next_cursor": "eyJpZCI6MTAwMH0=" } }

Headers: X-Request-Id, X-RateLimit-Limit, X-RateLimit-Remaining

POST
/v1/campaigns/{id}/resume

Retoma send

O que faz

Retoma envio de campanha pausada. Destinatários já enviados não recebem novamente — só os com status pending são processados. Libera as mensagens em hold no Postfix via `postsuper -H`. Se a campanha foi pausada por auto-pause (warmup throttle), valida que a condição foi resolvida antes de retomar.

Parâmetros

path
id string obrigatório

Exemplo

curl -X POST 'https://api.ravimail.com.br/v1/campaigns/123/resume' \ -H 'Authorization: Bearer rvm_live_xxxxxxxx' \ -H 'Content-Type: application/json' \ -d '{ ... }'
// composer require ravisystems/ravimail-php use Ravimail\Client; $rm = new Client('rvm_live_xxxxxxxx'); $result = $rm->campaigns->create([...]);

Códigos de resposta

200 OK

Exemplo de resposta

{ "data": [ { "id": 42, "name": "Black Friday", "status": "sending", "sent": 891 } ], "meta": { "has_more": true, "next_cursor": "eyJpZCI6MTAwMH0=" } }

Headers: X-Request-Id, X-RateLimit-Limit, X-RateLimit-Remaining

POST
/v1/campaigns/{id}/cancel

Cancela campanha

O que faz

Cancela definitivamente a campanha. Mensagens pending são marcadas como `suppressed_local` (preserved_for_reactivate=0) e deletadas do Postfix. Operação **irreversível** — não tem como retomar depois. Use quando descobrir um erro grave (envio acidental, template comprometido). Mensagens já entregues ficam intactas e contabilizadas.

Parâmetros

path
id string obrigatório

Exemplo

curl -X POST 'https://api.ravimail.com.br/v1/campaigns/123/cancel' \ -H 'Authorization: Bearer rvm_live_xxxxxxxx' \ -H 'Content-Type: application/json' \ -d '{ ... }'
// composer require ravisystems/ravimail-php use Ravimail\Client; $rm = new Client('rvm_live_xxxxxxxx'); $result = $rm->campaigns->create([...]);

Códigos de resposta

200 OK

Exemplo de resposta

{ "data": [ { "id": 42, "name": "Black Friday", "status": "sending", "sent": 891 } ], "meta": { "has_more": true, "next_cursor": "eyJpZCI6MTAwMH0=" } }

Headers: X-Request-Id, X-RateLimit-Limit, X-RateLimit-Remaining

POST
/v1/campaigns/{id}/duplicate

Clona config (counters zerados)

O que faz

Cria uma cópia da campanha mantendo configuração (subject, template, lista, segmento, A/B settings) mas com counters zerados e status `draft`. Útil pra re-enviar com pequenos ajustes, criar variações de uma base testada, ou recuperar campanha cancelada. Nome do clone vira `<original> (cópia)`.

Parâmetros

path
id string obrigatório

Exemplo

curl -X POST 'https://api.ravimail.com.br/v1/campaigns/123/duplicate' \ -H 'Authorization: Bearer rvm_live_xxxxxxxx' \ -H 'Content-Type: application/json' \ -d '{ ... }'
// composer require ravisystems/ravimail-php use Ravimail\Client; $rm = new Client('rvm_live_xxxxxxxx'); $result = $rm->campaigns->create([...]);

Códigos de resposta

201 Cópia criada

Exemplo de resposta

{ "data": { "id": 99, "name": "Black Friday (cópia)", "status": "draft", "list_id": 7, "created_at": "2026-05-19T14:30:00Z" } }

Headers: X-Request-Id, X-RateLimit-Limit, X-RateLimit-Remaining

GET
/v1/campaigns/{id}/ab-test

Status A/B + winner

O que faz

Retorna estado do teste A/B: porcentagem de split, métrica de decisão (open_rate / click_rate / reply_rate), volumes parciais por variante, e o `winner` quando já decidido. Use pra acompanhar testes em andamento e exibir resultados no seu dashboard.

Parâmetros

path
id string obrigatório

Exemplo

curl 'https://api.ravimail.com.br/v1/campaigns/123/ab-test' \ -H 'Authorization: Bearer rvm_live_xxxxxxxx'
// composer require ravisystems/ravimail-php use Ravimail\Client; $rm = new Client('rvm_live_xxxxxxxx'); $result = $rm->campaigns->get(123);

Códigos de resposta

200 Status

Exemplo de resposta

{ "data": { "campaign_id": 42, "split_percentage": 20, "winner_metric": "open_rate", "variant_a": { "subject": "Promo black friday", "sent": 200, "opens": 78 }, "variant_b": { "subject": "🔥 Só hoje: 50% OFF", "sent": 200, "opens": 112 }, "winner": "b", "decided_at": "2026-05-19T14:30:00Z" } }

Headers: X-Request-Id, X-RateLimit-Limit, X-RateLimit-Remaining

POST
/v1/campaigns/{id}/ab-test

Configura A/B (variant_b_subject, split_percentage, winner_metric)

O que faz

Configura teste A/B na campanha: variante B (subject ou template), split inicial (ex: 20% testa, 80% recebe winner), métrica de decisão e janela de avaliação. Quando a janela expira, o sistema escolhe automaticamente o vencedor e dispara o restante da lista com a variante vencedora. Deve ser chamado ANTES de /campaigns/{id}/start.

Parâmetros

path
id string obrigatório

Exemplo

curl -X POST 'https://api.ravimail.com.br/v1/campaigns/123/ab-test' \ -H 'Authorization: Bearer rvm_live_xxxxxxxx' \ -H 'Content-Type: application/json' \ -d '{ ... }'
// composer require ravisystems/ravimail-php use Ravimail\Client; $rm = new Client('rvm_live_xxxxxxxx'); $result = $rm->campaigns->create([...]);

Códigos de resposta

200 Configurado

Exemplo de resposta

{ "data": { "campaign_id": 42, "split_percentage": 20, "winner_metric": "open_rate", "variant_a": { "subject": "Promo black friday", "sent": 200, "opens": 78 }, "variant_b": { "subject": "🔥 Só hoje: 50% OFF", "sent": 200, "opens": 112 }, "winner": "b", "decided_at": "2026-05-19T14:30:00Z" } }

Headers: X-Request-Id, X-RateLimit-Limit, X-RateLimit-Remaining

POST
/v1/campaigns/{id}/ab-test/force-winner

Força winner manual (a|b)

O que faz

Sobrescreve a decisão automática e força A ou B como vencedor. Útil quando: (1) você precisa de resposta mais rápida antes da janela completar, (2) razões qualitativas fora da métrica (ex: variante B teve melhor click mas trazia leads ruins), (3) você quer testar rollback rápido.

Parâmetros

path
id string obrigatório

Exemplo

curl -X POST 'https://api.ravimail.com.br/v1/campaigns/123/ab-test/force-winner' \ -H 'Authorization: Bearer rvm_live_xxxxxxxx' \ -H 'Content-Type: application/json' \ -d '{ ... }'
// composer require ravisystems/ravimail-php use Ravimail\Client; $rm = new Client('rvm_live_xxxxxxxx'); $result = $rm->campaigns->create([...]);

Códigos de resposta

200 Forçado

Exemplo de resposta

{ "data": { "campaign_id": 42, "winner": "a", "forced": true, "remaining_recipients": 1200 } }

Headers: X-Request-Id, X-RateLimit-Limit, X-RateLimit-Remaining

Contacts

9 endpoints

GET
/v1/contacts

Lista contatos

O que faz

Lista contatos cadastrados nas listas do user. Filtros: `list_id` (limita a uma lista), `email` (busca exata), `status` (active/suppressed/bounced), cursor pagination. Inclui custom fields e tags em cada contato.

Parâmetros

query
list_id string
query
email string
query
status string
query
cursor string
query
limit string

Exemplo

curl 'https://api.ravimail.com.br/v1/contacts?list_id=valor&email=valor' \ -H 'Authorization: Bearer rvm_live_xxxxxxxx'
// composer require ravisystems/ravimail-php use Ravimail\Client; $rm = new Client('rvm_live_xxxxxxxx'); $result = $rm->contacts->list();

Códigos de resposta

200 Lista

Exemplo de resposta

{ "data": [ { "id": 123, "email": "a@b.com", "name": "João", "status": "active" } ], "meta": { "has_more": true, "next_cursor": "eyJpZCI6MTAwMH0=" } }

Headers: X-Request-Id, X-RateLimit-Limit, X-RateLimit-Remaining

POST
/v1/contacts

Cria contato

O que faz

Adiciona um único contato a uma lista. Idempotente por (list_id + email): se já existir, retorna 200 com o contato atualizado em vez de duplicar. Aceita `fields` (custom fields) e `tags`. Email é validado por sintaxe antes de inserir.

Request body

Content-Type: application/json obrigatório
Schema: Contact

Exemplo

curl -X POST 'https://api.ravimail.com.br/v1/contacts' \ -H 'Authorization: Bearer rvm_live_xxxxxxxx' \ -H 'Content-Type: application/json' \ -d '{ /* Contact */ }'
// composer require ravisystems/ravimail-php use Ravimail\Client; $rm = new Client('rvm_live_xxxxxxxx'); $result = $rm->contacts->create([...]);

Códigos de resposta

201 Criado

Exemplo de resposta

{ "data": [ { "id": 123, "email": "a@b.com", "name": "João", "status": "active" } ], "meta": { "has_more": true, "next_cursor": "eyJpZCI6MTAwMH0=" } }

Headers: X-Request-Id, X-RateLimit-Limit, X-RateLimit-Remaining

POST
/v1/contacts/import

Bulk import (até 1000)

O que faz

Importa até 1000 contatos em uma única chamada. Aceita array JSON ou CSV no body. Cada linha pode ter `email`, `name`, `fields` (custom fields), `tags`. Validação de email + dedup automático (emails existentes na lista são atualizados, não duplicados). Retorna sumário: inseridos, atualizados, inválidos com motivo de cada rejeição.

Exemplo

curl -X POST 'https://api.ravimail.com.br/v1/contacts/import' \ -H 'Authorization: Bearer rvm_live_xxxxxxxx' \ -H 'Content-Type: application/json' \ -d '{ ... }'
// composer require ravisystems/ravimail-php use Ravimail\Client; $rm = new Client('rvm_live_xxxxxxxx'); $result = $rm->contacts->create([...]);

Códigos de resposta

200 Sumário do import

Exemplo de resposta

{ "data": { "imported": 879, "updated": 100, "invalid": 21, "invalid_samples": [ { "line": 12, "email": "naoeemail", "reason": "invalid_syntax" } ] } }

Headers: X-Request-Id, X-RateLimit-Limit, X-RateLimit-Remaining

GET
/v1/contacts/{id}

Show

O que faz

Detalhe completo do contato: campos padrão, custom fields, tags, histórico resumido de envios (last_sent_at, total_opens, total_clicks).

Parâmetros

path
id string obrigatório

Exemplo

curl 'https://api.ravimail.com.br/v1/contacts/123' \ -H 'Authorization: Bearer rvm_live_xxxxxxxx'
// composer require ravisystems/ravimail-php use Ravimail\Client; $rm = new Client('rvm_live_xxxxxxxx'); $result = $rm->contacts->get(123);

Códigos de resposta

200 Contato

Exemplo de resposta

{ "data": { "id": 123, "list_id": 7, "email": "usuario@dominio.com", "name": "João Silva", "status": "active", "fields": { "cidade": "São Paulo", "plano": "pro" }, "tags": [ "vip" ], "created_at": "2026-05-01T10:00:00Z" } }

Headers: X-Request-Id, X-RateLimit-Limit, X-RateLimit-Remaining

PUT
/v1/contacts/{id}

Update

O que faz

Atualiza campos do contato. Aceita apenas campos a modificar (PATCH-like). Custom fields são merged — pra remover um, envie `null`. Mudar `email` é permitido mas pode invalidar histórico de tracking — use com cautela.

Parâmetros

path
id string obrigatório

Exemplo

curl -X PUT 'https://api.ravimail.com.br/v1/contacts/123' \ -H 'Authorization: Bearer rvm_live_xxxxxxxx' \ -H 'Content-Type: application/json' \ -d '{ ... }'
// composer require ravisystems/ravimail-php use Ravimail\Client; $rm = new Client('rvm_live_xxxxxxxx'); $result = $rm->contacts->update(123, [...]);

Códigos de resposta

200 Atualizado

Exemplo de resposta

{ "data": { "id": 123, "list_id": 7, "email": "usuario@dominio.com", "name": "João Silva", "status": "active", "fields": { "cidade": "São Paulo", "plano": "pro" }, "tags": [ "vip" ], "created_at": "2026-05-01T10:00:00Z" } }

Headers: X-Request-Id, X-RateLimit-Limit, X-RateLimit-Remaining

DELETE
/v1/contacts/{id}

Delete

O que faz

Remove o contato da lista. **Não suprime** — o email pode ser re-adicionado posteriormente. Se quer evitar envios futuros, use POST /suppress em vez de DELETE.

Parâmetros

path
id string obrigatório

Exemplo

curl -X DELETE 'https://api.ravimail.com.br/v1/contacts/123' \ -H 'Authorization: Bearer rvm_live_xxxxxxxx'
// composer require ravisystems/ravimail-php use Ravimail\Client; $rm = new Client('rvm_live_xxxxxxxx'); $result = $rm->contacts->delete(123);

Códigos de resposta

204 Removido

Exemplo de resposta

# 204 No Content — body vazio HTTP/1.1 204 No Content X-Request-Id: req_a1b2c3d4e5f6
POST
/v1/contacts/{id}/tags

Add tags

O que faz

Adiciona uma ou mais tags ao contato. Tags inexistentes são criadas automaticamente. Idempotente — tags já presentes são ignoradas. Útil pra segmentação dinâmica posterior.

Parâmetros

path
id string obrigatório

Exemplo

curl -X POST 'https://api.ravimail.com.br/v1/contacts/123/tags' \ -H 'Authorization: Bearer rvm_live_xxxxxxxx' \ -H 'Content-Type: application/json' \ -d '{ ... }'
// composer require ravisystems/ravimail-php use Ravimail\Client; $rm = new Client('rvm_live_xxxxxxxx'); $result = $rm->contacts->create([...]);

Códigos de resposta

200 Tags atuais

Exemplo de resposta

{ "data": { "id": 123, "tags": [ "vip", "onboarding" ] } }

Headers: X-Request-Id, X-RateLimit-Limit, X-RateLimit-Remaining

DELETE
/v1/contacts/{id}/tags

Remove tags

O que faz

Remove tags específicas do contato. Outras tags permanecem. Tags que não estavam no contato são ignoradas silenciosamente.

Parâmetros

path
id string obrigatório

Exemplo

curl -X DELETE 'https://api.ravimail.com.br/v1/contacts/123/tags' \ -H 'Authorization: Bearer rvm_live_xxxxxxxx'
// composer require ravisystems/ravimail-php use Ravimail\Client; $rm = new Client('rvm_live_xxxxxxxx'); $result = $rm->contacts->delete(123);

Códigos de resposta

200 Tags atuais

Exemplo de resposta

# 204 No Content — body vazio HTTP/1.1 204 No Content X-Request-Id: req_a1b2c3d4e5f6
POST
/v1/contacts/{id}/suppress

Suprime contato

O que faz

Marca o contato como suprimido — nenhuma campanha ou disparo futuro vai entregar pra ele, mesmo que continue na lista. Use quando o user pede pra parar de receber emails (opt-out direto), quando você detecta sinais de risco (bounces consecutivos) ou compliance LGPD/CAN-SPAM. Diferente de DELETE: mantém histórico do contato.

Parâmetros

path
id string obrigatório

Exemplo

curl -X POST 'https://api.ravimail.com.br/v1/contacts/123/suppress' \ -H 'Authorization: Bearer rvm_live_xxxxxxxx' \ -H 'Content-Type: application/json' \ -d '{ ... }'
// composer require ravisystems/ravimail-php use Ravimail\Client; $rm = new Client('rvm_live_xxxxxxxx'); $result = $rm->contacts->create([...]);

Códigos de resposta

200 Status atualizado

Exemplo de resposta

{ "data": { "id": 123, "email": "usuario@dominio.com", "status": "suppressed", "suppressed_at": "2026-05-19T14:30:00Z", "reason": "manual" } }

Headers: X-Request-Id, X-RateLimit-Limit, X-RateLimit-Remaining

Custom Fields

3 endpoints

GET
/v1/custom-fields

Lista schema de campos

O que faz

Lista todos os custom fields do user (esquema). Cada field: key, type (string/number/date/boolean), required flag, descrição. Custom fields são usados em contatos (`fields` object) e podem ser referenciados em templates como `{{custom_fields.cidade}}`.

Exemplo

curl 'https://api.ravimail.com.br/v1/custom-fields' \ -H 'Authorization: Bearer rvm_live_xxxxxxxx'
// composer require ravisystems/ravimail-php use Ravimail\Client; $rm = new Client('rvm_live_xxxxxxxx'); $result = $rm->request->list();

Códigos de resposta

200 Lista

Exemplo de resposta

{ "data": [ { "id": 7, "field_key": "cidade", "type": "string" } ], "meta": { "has_more": true, "next_cursor": "eyJpZCI6MTAwMH0=" } }

Headers: X-Request-Id, X-RateLimit-Limit, X-RateLimit-Remaining

POST
/v1/custom-fields

Cria field (field_key, type, required)

O que faz

Adiciona um novo custom field ao schema. Após criar, todos os contatos podem armazenar valor pra esse field. Tipos permitidos: string, number, date, boolean. Field_key deve ser snake_case e único.

Exemplo

curl -X POST 'https://api.ravimail.com.br/v1/custom-fields' \ -H 'Authorization: Bearer rvm_live_xxxxxxxx' \ -H 'Content-Type: application/json' \ -d '{ ... }'
// composer require ravisystems/ravimail-php use Ravimail\Client; $rm = new Client('rvm_live_xxxxxxxx'); $result = $rm->request->create([...]);

Códigos de resposta

201 Criado

Exemplo de resposta

{ "data": { "id": 7, "field_key": "cidade", "type": "string", "required": false } }

Headers: X-Request-Id, X-RateLimit-Limit, X-RateLimit-Remaining

DELETE
/v1/custom-fields/{id}

Remove field do schema

O que faz

Remove o custom field do schema. Valores armazenados em contatos pra esse field são apagados (irreversível). Templates que referenciam o field passam a renderizar como vazio. **Use com cautela.**

Parâmetros

path
id string obrigatório

Exemplo

curl -X DELETE 'https://api.ravimail.com.br/v1/custom-fields/123' \ -H 'Authorization: Bearer rvm_live_xxxxxxxx'
// composer require ravisystems/ravimail-php use Ravimail\Client; $rm = new Client('rvm_live_xxxxxxxx'); $result = $rm->request->delete(123);

Códigos de resposta

204 Removido

Exemplo de resposta

# 204 No Content — body vazio HTTP/1.1 204 No Content X-Request-Id: req_a1b2c3d4e5f6

Domains

7 endpoints

GET
/v1/domains

Lista domínios do user

O que faz

Lista todos os domínios remetentes do user com status de verificação SPF/DKIM/DMARC. Inclui domínios API-only (gratuitos, só pra /transactional/*) e domínios upgraded pro painel (também aparecem no wizard de campanha).

Exemplo

curl 'https://api.ravimail.com.br/v1/domains' \ -H 'Authorization: Bearer rvm_live_xxxxxxxx'
// composer require ravisystems/ravimail-php use Ravimail\Client; $rm = new Client('rvm_live_xxxxxxxx'); $result = $rm->domains->list();

Códigos de resposta

200 Lista

Exemplo de resposta

{ "data": [ { "id": 7, "domain": "mail.suaempresa.com.br", "verified": true } ], "meta": { "has_more": true, "next_cursor": "eyJpZCI6MTAwMH0=" } }

Headers: X-Request-Id, X-RateLimit-Limit, X-RateLimit-Remaining

POST
/v1/domains

Cria domínio API-only (GRATUITO)

O que faz

Domínios criados via API são gratuitos e ficam disponíveis APENAS pra envio via /v1/transactional/*. Não aparecem no wizard de campanha do painel. Pra usar no painel também: POST /v1/domains/{id}/upgrade-to-panel (cria PIX R$ 97). Quota: 10 domínios API-only por user (separado do limite do painel).

Request body

Content-Type: application/json obrigatório

Exemplo

curl -X POST 'https://api.ravimail.com.br/v1/domains' \ -H 'Authorization: Bearer rvm_live_xxxxxxxx' \ -H 'Content-Type: application/json' \ -d '{ ... }'
// composer require ravisystems/ravimail-php use Ravimail\Client; $rm = new Client('rvm_live_xxxxxxxx'); $result = $rm->domains->create([...]);

Códigos de resposta

201 Criado + DNS records retornados
422 Erro RFC 7807

Exemplo de resposta

{ "data": [ { "id": 7, "domain": "mail.suaempresa.com.br", "verified": true } ], "meta": { "has_more": true, "next_cursor": "eyJpZCI6MTAwMH0=" } }

Headers: X-Request-Id, X-RateLimit-Limit, X-RateLimit-Remaining

GET
/v1/domains/{id}

Detalhe domínio + DNS records + nameservers

O que faz

Detalhe completo do domínio: status SPF/DKIM/DMARC, registros DNS esperados (com instruções pra copiar pro seu DNS provider), nameservers (se usando Ravi DNS gratuito), última verificação automática.

Parâmetros

path
id string obrigatório

Exemplo

curl 'https://api.ravimail.com.br/v1/domains/123' \ -H 'Authorization: Bearer rvm_live_xxxxxxxx'
// composer require ravisystems/ravimail-php use Ravimail\Client; $rm = new Client('rvm_live_xxxxxxxx'); $result = $rm->domains->get(123);

Códigos de resposta

200 Domínio

Exemplo de resposta

{ "data": { "id": 7, "domain": "mail.suaempresa.com.br", "verified": true, "panel_unlocked": false, "dns_records": [ { "type": "TXT", "name": "@", "value": "v=spf1 include:_spf.ravimail.com.br ~all" }, { "type": "TXT", "name": "rvm1._domainkey", "value": "v=DKIM1; k=rsa; p=MIGfMA0GCSq..." } ] } }

Headers: X-Request-Id, X-RateLimit-Limit, X-RateLimit-Remaining

DELETE
/v1/domains/{id}

Remove domínio

O que faz

Remove o domínio. Use `?force=1` se há histórico de envios. Campanhas/templates que referenciavam ficam órfãos. Em domínios usando Ravi DNS, os registros publicados são removidos automaticamente.

Parâmetros

path
id string obrigatório
query
force string

Exemplo

curl -X DELETE 'https://api.ravimail.com.br/v1/domains/123?force=valor' \ -H 'Authorization: Bearer rvm_live_xxxxxxxx'
// composer require ravisystems/ravimail-php use Ravimail\Client; $rm = new Client('rvm_live_xxxxxxxx'); $result = $rm->domains->delete(123);

Códigos de resposta

204 Removido

Exemplo de resposta

# 204 No Content — body vazio HTTP/1.1 204 No Content X-Request-Id: req_a1b2c3d4e5f6
POST
/v1/domains/{id}/verify

Trigger verify síncrono (multi-resolver)

O que faz

Dispara verificação imediata dos registros DNS (SPF/DKIM/DMARC) do domínio. Usa múltiplos resolvers DNS pra evitar falsos negativos por cache desatualizado. Retorna status atualizado e detalhes do que está OK/faltando. Útil quando você acabou de publicar os registros no seu DNS provider e quer confirmar propagação sem esperar o cron periódico.

Parâmetros

path
id string obrigatório

Exemplo

curl -X POST 'https://api.ravimail.com.br/v1/domains/123/verify' \ -H 'Authorization: Bearer rvm_live_xxxxxxxx' \ -H 'Content-Type: application/json' \ -d '{ ... }'
// composer require ravisystems/ravimail-php use Ravimail\Client; $rm = new Client('rvm_live_xxxxxxxx'); $result = $rm->domains->create([...]);

Códigos de resposta

200 Status atualizado

Exemplo de resposta

{ "data": { "id": 7, "domain": "mail.suaempresa.com.br", "status": "verified", "spf": "pass", "dkim": "pass", "dmarc": "pass", "verified_at": "2026-05-19T14:30:00Z" } }

Headers: X-Request-Id, X-RateLimit-Limit, X-RateLimit-Remaining

GET
/v1/domains/{id}/dns-check

Bateria de checks DNS ao vivo (SPF/DKIM/DMARC)

O que faz

Resolve em tempo real os registros DNS do domínio em vários servidores autoritativos e retorna análise detalhada por registro: presença, valor esperado vs encontrado, score de qualidade. Inclui flag de listagem em RBLs públicas e checks de PTR reverso. Use pra debug profundo de problemas de entregabilidade ligados a configuração de DNS.

Parâmetros

path
id string obrigatório

Exemplo

curl 'https://api.ravimail.com.br/v1/domains/123/dns-check' \ -H 'Authorization: Bearer rvm_live_xxxxxxxx'
// composer require ravisystems/ravimail-php use Ravimail\Client; $rm = new Client('rvm_live_xxxxxxxx'); $result = $rm->domains->get(123);

Códigos de resposta

200 Score + checks por registro

Exemplo de resposta

{ "data": { "domain": "mail.suaempresa.com.br", "score": 92, "checks": [ { "type": "SPF", "ok": true, "value": "v=spf1 include:_spf.ravimail.com.br ~all" }, { "type": "DKIM", "ok": true, "selector": "rvm1" }, { "type": "DMARC", "ok": true, "policy": "quarantine" }, { "type": "MX", "ok": true, "records": [ "10 mx.suaempresa.com.br" ] }, { "type": "RBL", "ok": true, "listed_in": [] } ] } }

Headers: X-Request-Id, X-RateLimit-Limit, X-RateLimit-Remaining

POST
/v1/domains/{id}/upgrade-to-panel

Upgrade API-only → painel (cria PIX R$ 97)

O que faz

Cria cobrança PIX (R$ 97 one-shot) pra upgrade do domínio API-only pra modo painel. Após pagamento confirmado, o domínio aparece também no wizard de campanha do painel + ganha dashboard de reputação. Retorna QR code, copia-e-cola e link de pagamento. Tempo médio de confirmação: 30s.

Parâmetros

path
id string obrigatório

Exemplo

curl -X POST 'https://api.ravimail.com.br/v1/domains/123/upgrade-to-panel' \ -H 'Authorization: Bearer rvm_live_xxxxxxxx' \ -H 'Content-Type: application/json' \ -d '{ ... }'
// composer require ravisystems/ravimail-php use Ravimail\Client; $rm = new Client('rvm_live_xxxxxxxx'); $result = $rm->domains->create([...]);

Códigos de resposta

201 PIX criado pra upgrade

Exemplo de resposta

{ "data": { "payment_id": "pay_xx99", "pix_code": "00020126...5204000053039865802BR...", "amount_brl": 97, "expires_at": "2026-05-19T15:00:00Z" } }

Headers: X-Request-Id, X-RateLimit-Limit, X-RateLimit-Remaining

Drips

10 endpoints

GET
/v1/drips

Lista drip campaigns

O que faz

Lista sequências automatizadas (drips). Cada drip: nome, trigger, total de steps, count de inscritos ativos.

Exemplo

curl 'https://api.ravimail.com.br/v1/drips' \ -H 'Authorization: Bearer rvm_live_xxxxxxxx'
// composer require ravisystems/ravimail-php use Ravimail\Client; $rm = new Client('rvm_live_xxxxxxxx'); $result = $rm->drips->list();

Códigos de resposta

200 Lista

Exemplo de resposta

{ "data": [ { "id": 3, "name": "Onboarding", "status": "active", "active_subscribers": 87 } ], "meta": { "has_more": true, "next_cursor": "eyJpZCI6MTAwMH0=" } }

Headers: X-Request-Id, X-RateLimit-Limit, X-RateLimit-Remaining

POST
/v1/drips

Cria drip (trigger_type + value)

O que faz

Cria nova sequência. Trigger: `segment_match` (entra quando contato entra no segmento), `manual` (você inscreve via API), `api_event` (dispara via evento custom). Após criar, adicione steps via POST /drips/{id}/steps.

Exemplo

curl -X POST 'https://api.ravimail.com.br/v1/drips' \ -H 'Authorization: Bearer rvm_live_xxxxxxxx' \ -H 'Content-Type: application/json' \ -d '{ ... }'
// composer require ravisystems/ravimail-php use Ravimail\Client; $rm = new Client('rvm_live_xxxxxxxx'); $result = $rm->drips->create([...]);

Códigos de resposta

201 Criado

Exemplo de resposta

{ "data": [ { "id": 3, "name": "Onboarding", "status": "active", "active_subscribers": 87 } ], "meta": { "has_more": true, "next_cursor": "eyJpZCI6MTAwMH0=" } }

Headers: X-Request-Id, X-RateLimit-Limit, X-RateLimit-Remaining

GET
/v1/drips/{id}

Detalhes do drip

O que faz

Detalhe completo: nome, trigger, lista de steps com delays, status (active/paused), contagem de inscritos ativos.

Parâmetros

path
id string obrigatório

Exemplo

curl 'https://api.ravimail.com.br/v1/drips/123' \ -H 'Authorization: Bearer rvm_live_xxxxxxxx'
// composer require ravisystems/ravimail-php use Ravimail\Client; $rm = new Client('rvm_live_xxxxxxxx'); $result = $rm->drips->get(123);

Códigos de resposta

200 Detalhes

Exemplo de resposta

{ "data": { "id": 3, "name": "Onboarding novo lead", "trigger_type": "segment_match", "trigger_value": "novos_leads", "status": "active", "steps_count": 5, "active_subscribers": 87 } }

Headers: X-Request-Id, X-RateLimit-Limit, X-RateLimit-Remaining

PUT
/v1/drips/{id}

Atualiza drip (trigger, status)

O que faz

Atualiza nome, trigger ou status. Pausar (status=paused) suspende disparos pra inscritos existentes mantendo estado pra retomar depois.

Parâmetros

path
id string obrigatório

Exemplo

curl -X PUT 'https://api.ravimail.com.br/v1/drips/123' \ -H 'Authorization: Bearer rvm_live_xxxxxxxx' \ -H 'Content-Type: application/json' \ -d '{ ... }'
// composer require ravisystems/ravimail-php use Ravimail\Client; $rm = new Client('rvm_live_xxxxxxxx'); $result = $rm->drips->update(123, [...]);

Códigos de resposta

200 Atualizado

Exemplo de resposta

{ "data": { "id": 3, "name": "Onboarding novo lead", "trigger_type": "segment_match", "trigger_value": "novos_leads", "status": "active", "steps_count": 5, "active_subscribers": 87 } }

Headers: X-Request-Id, X-RateLimit-Limit, X-RateLimit-Remaining

DELETE
/v1/drips/{id}

Remove drip

O que faz

Remove a drip e todos os steps. Inscritos atuais param de receber. Histórico de envios anteriores fica preservado em /events.

Parâmetros

path
id string obrigatório

Exemplo

curl -X DELETE 'https://api.ravimail.com.br/v1/drips/123' \ -H 'Authorization: Bearer rvm_live_xxxxxxxx'
// composer require ravisystems/ravimail-php use Ravimail\Client; $rm = new Client('rvm_live_xxxxxxxx'); $result = $rm->drips->delete(123);

Códigos de resposta

204 Removido

Exemplo de resposta

# 204 No Content — body vazio HTTP/1.1 204 No Content X-Request-Id: req_a1b2c3d4e5f6
GET
/v1/drips/{id}/steps

Lista steps

O que faz

Lista steps em ordem cronológica. Cada step: template_id, delay_minutes (tempo desde o anterior), ordem.

Parâmetros

path
id string obrigatório

Exemplo

curl 'https://api.ravimail.com.br/v1/drips/123/steps' \ -H 'Authorization: Bearer rvm_live_xxxxxxxx'
// composer require ravisystems/ravimail-php use Ravimail\Client; $rm = new Client('rvm_live_xxxxxxxx'); $result = $rm->drips->get(123);

Códigos de resposta

200 Steps

Exemplo de resposta

{ "data": [ { "id": "st_1", "template_id": 17, "delay_minutes": 1440, "order": 1 } ], "meta": { "has_more": true, "next_cursor": "eyJpZCI6MTAwMH0=" } }

Headers: X-Request-Id, X-RateLimit-Limit, X-RateLimit-Remaining

POST
/v1/drips/{id}/steps

Adiciona step (template_id, delay_minutes)

O que faz

Adiciona novo step no final da sequência. `delay_minutes` conta desde o step anterior. Steps adicionados não afetam inscritos antigos que já passaram daquele ponto — só inscritos novos.

Parâmetros

path
id string obrigatório

Exemplo

curl -X POST 'https://api.ravimail.com.br/v1/drips/123/steps' \ -H 'Authorization: Bearer rvm_live_xxxxxxxx' \ -H 'Content-Type: application/json' \ -d '{ ... }'
// composer require ravisystems/ravimail-php use Ravimail\Client; $rm = new Client('rvm_live_xxxxxxxx'); $result = $rm->drips->create([...]);

Códigos de resposta

201 Step adicionado

Exemplo de resposta

{ "data": [ { "id": "st_1", "template_id": 17, "delay_minutes": 1440, "order": 1 } ], "meta": { "has_more": true, "next_cursor": "eyJpZCI6MTAwMH0=" } }

Headers: X-Request-Id, X-RateLimit-Limit, X-RateLimit-Remaining

POST
/v1/drips/{id}/subscribe

Inscreve contact_id

O que faz

Inscreve um contato na sequência de drip. A partir desse momento o contato vai receber cada step conforme o `delay_minutes` configurado. Trigger pode ser manual (esta API) ou automático via segment match / form submission / API event. Se o contato já está inscrito, retorna 200 sem duplicar.

Parâmetros

path
id string obrigatório

Exemplo

curl -X POST 'https://api.ravimail.com.br/v1/drips/123/subscribe' \ -H 'Authorization: Bearer rvm_live_xxxxxxxx' \ -H 'Content-Type: application/json' \ -d '{ ... }'
// composer require ravisystems/ravimail-php use Ravimail\Client; $rm = new Client('rvm_live_xxxxxxxx'); $result = $rm->drips->create([...]);

Códigos de resposta

201 Inscrito

Exemplo de resposta

{ "data": { "drip_id": 3, "contact_id": 123, "status": "active", "subscribed_at": "2026-05-19T14:30:00Z", "next_step_at": "2026-05-20T14:30:00Z" } }

Headers: X-Request-Id, X-RateLimit-Limit, X-RateLimit-Remaining

POST
/v1/drips/{id}/unsubscribe

Cancela inscrição de contact_id

O que faz

Remove o contato da drip — steps futuros não serão enviados. Steps já entregues ficam intactos no histórico. Use quando o contato faz uma ação que o tira da fase (ex: comprou o produto que a drip está vendendo, ou pediu unsubscribe).

Parâmetros

path
id string obrigatório

Exemplo

curl -X POST 'https://api.ravimail.com.br/v1/drips/123/unsubscribe' \ -H 'Authorization: Bearer rvm_live_xxxxxxxx' \ -H 'Content-Type: application/json' \ -d '{ ... }'
// composer require ravisystems/ravimail-php use Ravimail\Client; $rm = new Client('rvm_live_xxxxxxxx'); $result = $rm->drips->create([...]);

Códigos de resposta

200 OK

Exemplo de resposta

{ "data": { "drip_id": 3, "contact_id": 123, "status": "unsubscribed" } }

Headers: X-Request-Id, X-RateLimit-Limit, X-RateLimit-Remaining

DELETE
/v1/drips/{id}/steps/{step_id}

Remove step específico

O que faz

Remove um step da sequência. Steps que vinham depois mantêm o `delay_minutes` original (não recalcula). Inscritos atuais que ainda não chegaram nesse step pulam ele. Inscritos que já passaram ficam intactos.

Parâmetros

path
id string obrigatório
path
step_id string obrigatório

Exemplo

curl -X DELETE 'https://api.ravimail.com.br/v1/drips/123/steps/step_42' \ -H 'Authorization: Bearer rvm_live_xxxxxxxx'
// composer require ravisystems/ravimail-php use Ravimail\Client; $rm = new Client('rvm_live_xxxxxxxx'); $result = $rm->drips->delete(123);

Códigos de resposta

204 Step removido

Exemplo de resposta

# 204 No Content — body vazio HTTP/1.1 204 No Content X-Request-Id: req_a1b2c3d4e5f6

Events

3 endpoints

GET
/v1/events

Lista unificada (transactional + webhook)

O que faz

Lista TODOS os eventos do user em um stream cursor-paginated: delivered, opened, clicked, bounced, complained, unsubscribed, suppressed, ab_test_winner, etc. Filtros por tipo, campanha, contato, range de datas. Alternativa polling-based ao /events/stream SSE. Útil pra dashboards offline ou ETL pra warehouse.

Exemplo

curl 'https://api.ravimail.com.br/v1/events' \ -H 'Authorization: Bearer rvm_live_xxxxxxxx'
// composer require ravisystems/ravimail-php use Ravimail\Client; $rm = new Client('rvm_live_xxxxxxxx'); $result = $rm->events->list();

Códigos de resposta

200 Eventos cursor-paginated

Exemplo de resposta

{ "data": [ { "id": "evt_001", "event": "opened", "message_id": "msg_aaa", "at": "2026-05-19T14:32:00Z" } ], "meta": { "has_more": true, "next_cursor": "eyJpZCI6MTAwMH0=" } }

Headers: X-Request-Id, X-RateLimit-Limit, X-RateLimit-Remaining

GET
/v1/events/stream

Server-Sent Events stream (heartbeat 30s, hardstop 5min)

O que faz

Server-Sent Events stream que faz push de eventos em tempo real assim que ocorrem. Use `EventSource` no JS (auto-reconect + last-event-id) ou `curl --no-buffer` no terminal. Heartbeat a cada 30s pra evitar timeout de proxies. Hardstop em 5min — seu cliente deve reconectar automaticamente. Filtros via query string. Ideal pra dashboards reativos sem polling.

Exemplo

curl 'https://api.ravimail.com.br/v1/events/stream' \ -H 'Authorization: Bearer rvm_live_xxxxxxxx'
// composer require ravisystems/ravimail-php use Ravimail\Client; $rm = new Client('rvm_live_xxxxxxxx'); $result = $rm->events->list();

Códigos de resposta

200 SSE stream

Exemplo de resposta

# Server-Sent Events stream (text/event-stream) event: delivered data: {"message_id":"msg_abc123","at":"2026-05-19T14:30:08Z"} event: opened data: {"message_id":"msg_abc123","at":"2026-05-19T14:31:42Z"} # Heartbeat a cada 30s : heartbeat
POST
/v1/sandbox/trigger-event

Dispara evento sintético em sandbox

O que faz

Em modo sandbox (token `rvm_test_*`), dispara um evento sintético específico pra uma mensagem que você enviou em sandbox. Use pra testar webhook handlers e SSE consumers em CI/CD sem depender de envios reais. Eventos suportados: delivered, opened, clicked, bounced, complained, unsubscribed.

Exemplo

curl -X POST 'https://api.ravimail.com.br/v1/sandbox/trigger-event' \ -H 'Authorization: Bearer rvm_live_xxxxxxxx' \ -H 'Content-Type: application/json' \ -d '{ ... }'
// composer require ravisystems/ravimail-php use Ravimail\Client; $rm = new Client('rvm_live_xxxxxxxx'); $result = $rm->events->create([...]);

Códigos de resposta

202 Evento disparado

Exemplo de resposta

{ "data": { "event_id": "evt_test_xx99", "message_id": "msg_sandbox_abc", "event": "bounced", "triggered_at": "2026-05-19T14:30:00Z" } }

Headers: X-Request-Id, X-RateLimit-Limit, X-RateLimit-Remaining

Exports

3 endpoints

GET
/v1/exports

Lista export jobs

O que faz

Lista todos os jobs de exportação do user (status, tipo, progresso, file_id quando completed). Filtros opcionais por status. Útil pra dashboards de administração.

Exemplo

curl 'https://api.ravimail.com.br/v1/exports' \ -H 'Authorization: Bearer rvm_live_xxxxxxxx'
// composer require ravisystems/ravimail-php use Ravimail\Client; $rm = new Client('rvm_live_xxxxxxxx'); $result = $rm->exports->list();

Códigos de resposta

200 Lista

Exemplo de resposta

{ "data": [ { "id": "exp_77", "type": "contacts", "status": "completed" } ], "meta": { "has_more": true, "next_cursor": "eyJpZCI6MTAwMH0=" } }

Headers: X-Request-Id, X-RateLimit-Limit, X-RateLimit-Remaining

POST
/v1/exports

Cria export job assíncrono (type, filters)

O que faz

Cria um job CSV assíncrono pra exportar grandes volumes sem timeout. Aceita `type` (contacts/events/messages/suppressions) + `filters`. Worker processa em background e gera arquivo CSV. Use GET /exports/{id} pra polar status — quando completed, retorna `file_id` que você baixa via GET /files/{id}/download. Arquivos expiram em 7 dias.

Exemplo

curl -X POST 'https://api.ravimail.com.br/v1/exports' \ -H 'Authorization: Bearer rvm_live_xxxxxxxx' \ -H 'Content-Type: application/json' \ -d '{ ... }'
// composer require ravisystems/ravimail-php use Ravimail\Client; $rm = new Client('rvm_live_xxxxxxxx'); $result = $rm->exports->create([...]);

Códigos de resposta

202 Aceito

Exemplo de resposta

{ "data": { "id": "exp_77", "type": "contacts", "status": "queued", "eta_seconds": 180 } }

Headers: X-Request-Id, X-RateLimit-Limit, X-RateLimit-Remaining

GET
/v1/exports/{id}

Status do job + file_id quando completed

O que faz

Retorna progresso do job: status (queued/processing/completed/failed), porcentagem, ETA estimado. Quando completed, inclui `file_id` pronto pra download. Recomendado polar a cada 5s pra jobs pequenos, 30s pra jobs grandes (>100k linhas).

Parâmetros

path
id string obrigatório

Exemplo

curl 'https://api.ravimail.com.br/v1/exports/123' \ -H 'Authorization: Bearer rvm_live_xxxxxxxx'
// composer require ravisystems/ravimail-php use Ravimail\Client; $rm = new Client('rvm_live_xxxxxxxx'); $result = $rm->exports->get(123);

Códigos de resposta

200 Status

Exemplo de resposta

{ "data": { "id": "exp_77", "type": "contacts", "status": "completed", "progress": 100, "file_id": "file_8a2b3c", "rows": 12450, "created_at": "2026-05-19T14:00:00Z", "completed_at": "2026-05-19T14:03:22Z" } }

Headers: X-Request-Id, X-RateLimit-Limit, X-RateLimit-Remaining

Files

5 endpoints

GET
/v1/files

Lista arquivos do user

O que faz

Lista arquivos uploadados (anexos pra emails + CSVs gerados por /exports). Cada item: id, filename, mime, size, expires_at (TTL default 7 dias). Cursor-paginated.

Exemplo

curl 'https://api.ravimail.com.br/v1/files' \ -H 'Authorization: Bearer rvm_live_xxxxxxxx'
// composer require ravisystems/ravimail-php use Ravimail\Client; $rm = new Client('rvm_live_xxxxxxxx'); $result = $rm->files->list();

Códigos de resposta

200 Lista cursor

Exemplo de resposta

{ "data": [ { "id": "file_8a2b3c", "filename": "fatura.pdf", "size": 25431 } ], "meta": { "has_more": true, "next_cursor": "eyJpZCI6MTAwMH0=" } }

Headers: X-Request-Id, X-RateLimit-Limit, X-RateLimit-Remaining

POST
/v1/files

Upload de arquivo (até 25MB)

O que faz

Aceita raw body com headers `X-Filename` + `Content-Type`, OU multipart/form-data com campo `file`. Retorna file_id pra usar em attachments de /v1/transactional/send (integração: S81.1). TTL default 7 dias.

Request body

Content-Type: application/octet-stream, multipart/form-data obrigatório

Exemplo

curl -X POST 'https://api.ravimail.com.br/v1/files' \ -H 'Authorization: Bearer rvm_live_xxxxxxxx' \ -H 'Content-Type: application/json' \ -d '{ ... }'
// composer require ravisystems/ravimail-php use Ravimail\Client; $rm = new Client('rvm_live_xxxxxxxx'); $result = $rm->files->create([...]);

Códigos de resposta

201 Arquivo salvo

Exemplo de resposta

{ "data": { "id": "file_8a2b3c", "filename": "fatura-1234.pdf", "size": 25431, "mime": "application/pdf", "expires_at": "2026-05-26T14:30:00Z" } }

Headers: X-Request-Id, X-RateLimit-Limit, X-RateLimit-Remaining

GET
/v1/files/{id}

Metadata do arquivo

O que faz

Metadata do arquivo (sem o conteúdo binário): filename, mime, size, hash SHA-256, expires_at. Use /files/{id}/download pra resgatar o binário.

Parâmetros

path
id string obrigatório

Exemplo

curl 'https://api.ravimail.com.br/v1/files/123' \ -H 'Authorization: Bearer rvm_live_xxxxxxxx'
// composer require ravisystems/ravimail-php use Ravimail\Client; $rm = new Client('rvm_live_xxxxxxxx'); $result = $rm->files->get(123);

Códigos de resposta

200 Metadata

Exemplo de resposta

{ "data": { "id": "file_8a2b3c", "filename": "fatura-1234.pdf", "size": 25431, "mime": "application/pdf", "created_at": "2026-05-19T14:30:00Z" } }

Headers: X-Request-Id, X-RateLimit-Limit, X-RateLimit-Remaining

DELETE
/v1/files/{id}

Soft-delete (GC remove em 1d)

O que faz

Marca o arquivo pra remoção. Garbage collector remove fisicamente em 24h (janela pra reverter caso necessário). Após essa janela, recuperação impossível.

Parâmetros

path
id string obrigatório

Exemplo

curl -X DELETE 'https://api.ravimail.com.br/v1/files/123' \ -H 'Authorization: Bearer rvm_live_xxxxxxxx'
// composer require ravisystems/ravimail-php use Ravimail\Client; $rm = new Client('rvm_live_xxxxxxxx'); $result = $rm->files->delete(123);

Códigos de resposta

204 Removido

Exemplo de resposta

# 204 No Content — body vazio HTTP/1.1 204 No Content X-Request-Id: req_a1b2c3d4e5f6
GET
/v1/files/{id}/download

Stream conteúdo binário

O que faz

Faz download do conteúdo binário do arquivo. Headers `Content-Type` e `Content-Disposition` corretos pra browsers tratarem como download. Use pra resgatar CSVs gerados por /exports ou anexos previamente uploadados. Token API obrigatório como em qualquer endpoint /v1/*.

Parâmetros

path
id string obrigatório

Exemplo

curl 'https://api.ravimail.com.br/v1/files/123/download' \ -H 'Authorization: Bearer rvm_live_xxxxxxxx'
// composer require ravisystems/ravimail-php use Ravimail\Client; $rm = new Client('rvm_live_xxxxxxxx'); $result = $rm->files->get(123);

Códigos de resposta

200 Binary stream

Exemplo de resposta

# Stream binário (Content-Type: application/octet-stream) # Headers retornados: Content-Type: application/pdf Content-Disposition: attachment; filename="fatura-1234.pdf" Content-Length: 25431 <binary content>

IP Pools

8 endpoints

GET
/v1/ip-pools

Lista pools de IP

O que faz

Lista pools de IP do user. Cada pool agrupa IPs por propósito (transacional, marketing, warmup, alta-reputação). Útil pra isolar reputação entre tipos de envio — assim um bounce em campanha não afeta entrega de email transacional crítico.

Exemplo

curl 'https://api.ravimail.com.br/v1/ip-pools' \ -H 'Authorization: Bearer rvm_live_xxxxxxxx'
// composer require ravisystems/ravimail-php use Ravimail\Client; $rm = new Client('rvm_live_xxxxxxxx'); $result = $rm->request->list();

Códigos de resposta

200 Lista

Exemplo de resposta

{ "data": [ { "id": 4, "name": "Pool Transacional", "ip_count": 3 } ], "meta": { "has_more": true, "next_cursor": "eyJpZCI6MTAwMH0=" } }

Headers: X-Request-Id, X-RateLimit-Limit, X-RateLimit-Remaining

POST
/v1/ip-pools

Cria pool (name, type)

O que faz

Cria um pool de IP nomeado. Após criar, adicione IPs ao pool via POST /v1/ip-pools/{id}/ips. Pra forçar uso do pool: passe `forced_pool_id` ao criar/editar token API (todos os envios desse token usarão o pool), ou passe `pool_id` no body de /transactional/send pra cada chamada.

Exemplo

curl -X POST 'https://api.ravimail.com.br/v1/ip-pools' \ -H 'Authorization: Bearer rvm_live_xxxxxxxx' \ -H 'Content-Type: application/json' \ -d '{ ... }'
// composer require ravisystems/ravimail-php use Ravimail\Client; $rm = new Client('rvm_live_xxxxxxxx'); $result = $rm->request->create([...]);

Códigos de resposta

201 Criado

Exemplo de resposta

{ "data": [ { "id": 4, "name": "Pool Transacional", "ip_count": 3 } ], "meta": { "has_more": true, "next_cursor": "eyJpZCI6MTAwMH0=" } }

Headers: X-Request-Id, X-RateLimit-Limit, X-RateLimit-Remaining

GET
/v1/ip-pools/{id}

Detalhes do pool

O que faz

Detalhe do pool: nome, tipo, count de IPs, lista de IPs membros, tokens forçados a usar este pool. Útil pra debugar quando envios estão pegando IP errado.

Parâmetros

path
id string obrigatório

Exemplo

curl 'https://api.ravimail.com.br/v1/ip-pools/123' \ -H 'Authorization: Bearer rvm_live_xxxxxxxx'
// composer require ravisystems/ravimail-php use Ravimail\Client; $rm = new Client('rvm_live_xxxxxxxx'); $result = $rm->request->get(123);

Códigos de resposta

200 Pool

Exemplo de resposta

{ "data": { "id": 4, "name": "Pool Transacional", "type": "transactional", "ip_count": 3, "created_at": "2026-05-01T09:00:00Z" } }

Headers: X-Request-Id, X-RateLimit-Limit, X-RateLimit-Remaining

PUT
/v1/ip-pools/{id}

Atualiza pool

O que faz

Atualiza nome ou tipo do pool. Não afeta membros nem reputação dos IPs. Pra adicionar/remover IPs use os endpoints específicos.

Parâmetros

path
id string obrigatório

Exemplo

curl -X PUT 'https://api.ravimail.com.br/v1/ip-pools/123' \ -H 'Authorization: Bearer rvm_live_xxxxxxxx' \ -H 'Content-Type: application/json' \ -d '{ ... }'
// composer require ravisystems/ravimail-php use Ravimail\Client; $rm = new Client('rvm_live_xxxxxxxx'); $result = $rm->request->update(123, [...]);

Códigos de resposta

200 Atualizado

Exemplo de resposta

{ "data": { "id": 4, "name": "Pool Transacional", "type": "transactional", "ip_count": 3, "created_at": "2026-05-01T09:00:00Z" } }

Headers: X-Request-Id, X-RateLimit-Limit, X-RateLimit-Remaining

DELETE
/v1/ip-pools/{id}

Remove pool

O que faz

Remove o pool. IPs membros voltam pro pool default. Tokens que tinham `forced_pool_id` apontando pra este pool ficam com `forced_pool_id=null` automaticamente (passam a usar default).

Parâmetros

path
id string obrigatório

Exemplo

curl -X DELETE 'https://api.ravimail.com.br/v1/ip-pools/123' \ -H 'Authorization: Bearer rvm_live_xxxxxxxx'
// composer require ravisystems/ravimail-php use Ravimail\Client; $rm = new Client('rvm_live_xxxxxxxx'); $result = $rm->request->delete(123);

Códigos de resposta

204 Removido

Exemplo de resposta

# 204 No Content — body vazio HTTP/1.1 204 No Content X-Request-Id: req_a1b2c3d4e5f6
GET
/v1/ip-pools/{id}/ips

Lista IPs do pool

O que faz

Lista IPs membros do pool. Cada IP: address, node de origem, score atual de reputação, status (active/warmup/paused).

Parâmetros

path
id string obrigatório

Exemplo

curl 'https://api.ravimail.com.br/v1/ip-pools/123/ips' \ -H 'Authorization: Bearer rvm_live_xxxxxxxx'
// composer require ravisystems/ravimail-php use Ravimail\Client; $rm = new Client('rvm_live_xxxxxxxx'); $result = $rm->request->get(123);

Códigos de resposta

200 IPs

Exemplo de resposta

{ "data": [ { "id": 8, "address": "203.0.113.10", "pool_id": 4 } ], "meta": { "has_more": true, "next_cursor": "eyJpZCI6MTAwMH0=" } }

Headers: X-Request-Id, X-RateLimit-Limit, X-RateLimit-Remaining

POST
/v1/ip-pools/{id}/ips

Adiciona IPs ao pool

O que faz

Adiciona um ou mais IPs ao pool. Aceita array de `ip_id`. IPs já em outro pool são movidos (cada IP pertence a um pool por vez). IPs em warmup ativo são suportados — o pool não interfere no progresso de warmup.

Parâmetros

path
id string obrigatório

Exemplo

curl -X POST 'https://api.ravimail.com.br/v1/ip-pools/123/ips' \ -H 'Authorization: Bearer rvm_live_xxxxxxxx' \ -H 'Content-Type: application/json' \ -d '{ ... }'
// composer require ravisystems/ravimail-php use Ravimail\Client; $rm = new Client('rvm_live_xxxxxxxx'); $result = $rm->request->create([...]);

Códigos de resposta

201 IPs adicionados

Exemplo de resposta

{ "data": { "pool_id": 4, "added": 2, "ips": [ { "id": 8, "address": "203.0.113.10" }, { "id": 9, "address": "203.0.113.11" } ] } }

Headers: X-Request-Id, X-RateLimit-Limit, X-RateLimit-Remaining

DELETE
/v1/ip-pools/{id}/ips/{ipId}

Remove IP do pool

O que faz

Remove um IP específico do pool. O IP volta pro pool default. Tokens forçados a usar este pool continuam usando os IPs restantes.

Parâmetros

path
id string obrigatório
path
ipId string obrigatório

Exemplo

curl -X DELETE 'https://api.ravimail.com.br/v1/ip-pools/123/ips/7' \ -H 'Authorization: Bearer rvm_live_xxxxxxxx'
// composer require ravisystems/ravimail-php use Ravimail\Client; $rm = new Client('rvm_live_xxxxxxxx'); $result = $rm->request->delete(123);

Códigos de resposta

204 IP removido

Exemplo de resposta

# 204 No Content — body vazio HTTP/1.1 204 No Content X-Request-Id: req_a1b2c3d4e5f6

Identity

3 endpoints

GET
/v1/health público

Health check público

O que faz

Endpoint público (sem auth) que retorna o status operacional da API. Use em uptime monitors externos (UptimeRobot, BetterStack, Pingdom) ou load balancer health checks. Resposta inclui timestamp do servidor e versão atual da API. Latência típica < 50ms.

Exemplo

curl 'https://api.ravimail.com.br/v1/health' \ -H 'Authorization: Bearer rvm_live_xxxxxxxx'
// composer require ravisystems/ravimail-php use Ravimail\Client; $rm = new Client('rvm_live_xxxxxxxx'); $result = $rm->request->list();

Códigos de resposta

200 Status do sistema

Exemplo de resposta

{ "data": { "status": "ok", "time": "2026-05-19T14:30:00Z", "version": "1.0.0", "uptime_seconds": 1234567 } }

Headers: X-Request-Id, X-RateLimit-Limit, X-RateLimit-Remaining

GET
/v1/me

Dados do token + user + saldo

O que faz

Retorna informações da identidade autenticada: id do user dono do token, scopes liberados, IP whitelist configurada, saldo atual em créditos e quotas usadas no mês corrente. Útil pra dashboards de uso e validação de permissões antes de operações sensíveis.

Exemplo

curl 'https://api.ravimail.com.br/v1/me' \ -H 'Authorization: Bearer rvm_live_xxxxxxxx'
// composer require ravisystems/ravimail-php use Ravimail\Client; $rm = new Client('rvm_live_xxxxxxxx'); $result = $rm->request->list();

Códigos de resposta

200 Identidade do token

Exemplo de resposta

{ "data": { "token_id": "tok_8f3a2b1c", "user_id": 42, "name": "Token de produção", "scopes": [ "transactional:send", "contacts:read", "webhooks:write" ], "allowed_ips": [ "203.0.113.45" ], "last_used_at": "2026-05-19T14:25:11Z", "balance": { "credits": 12500, "currency": "BRL" }, "usage": { "emails_this_month": 4321, "verifications_this_month": 87 } } }

Headers: X-Request-Id, X-RateLimit-Limit, X-RateLimit-Remaining

GET
/v1/openapi.json público

Esta própria spec OpenAPI 3.0 (público, sem auth)

O que faz

Retorna a spec OpenAPI 3.0 completa em JSON — a mesma usada por esta página de referência e pelo Swagger UI interno. Endpoint público (sem auth) pra que ferramentas externas (Postman, Insomnia, Bruno) consigam importar a definição direto via URL sem precisar autenticar.

Exemplo

curl 'https://api.ravimail.com.br/v1/openapi.json' \ -H 'Authorization: Bearer rvm_live_xxxxxxxx'
// composer require ravisystems/ravimail-php use Ravimail\Client; $rm = new Client('rvm_live_xxxxxxxx'); $result = $rm->request->list();

Códigos de resposta

200 Spec OpenAPI 3.0 JSON

Exemplo de resposta

{ "data": { "token_id": "tok_8f3a2b1c", "user_id": 42, "name": "Token de produção", "scopes": [ "transactional:send", "contacts:read", "webhooks:write" ], "allowed_ips": [ "203.0.113.45" ], "last_used_at": "2026-05-19T14:25:11Z", "balance": { "credits": 12500, "currency": "BRL" }, "usage": { "emails_this_month": 4321, "verifications_this_month": 87 } } }

Headers: X-Request-Id, X-RateLimit-Limit, X-RateLimit-Remaining

Inbound

5 endpoints

GET
/v1/inbound/routes

Lista regras de inbound routing

O que faz

Lista regras de processamento de email recebido. Cada regra: pattern (regex no destinatário), forward_url (webhook que recebe payload parseado), status active/disabled. Use pra construir features tipo 'reply-by-email', 'support@', ou capturar respostas em fluxos automatizados.

Exemplo

curl 'https://api.ravimail.com.br/v1/inbound/routes' \ -H 'Authorization: Bearer rvm_live_xxxxxxxx'
// composer require ravisystems/ravimail-php use Ravimail\Client; $rm = new Client('rvm_live_xxxxxxxx'); $result = $rm->inboundRoutes->list();

Códigos de resposta

200 Lista

Exemplo de resposta

{ "data": [ { "id": "ibr_99", "pattern": "support+*@suaempresa.com.br", "forward_url": "https://api.cliente.com/inbound" } ], "meta": { "has_more": true, "next_cursor": "eyJpZCI6MTAwMH0=" } }

Headers: X-Request-Id, X-RateLimit-Limit, X-RateLimit-Remaining

POST
/v1/inbound/routes

Cria regra (pattern → forward_url webhook)

O que faz

Cria regra que captura emails recebidos no domínio configurado e faz forward via POST HTTP. Pattern aceita curinga (`support+*@dominio.com`). Forward_secret é retornado uma única vez — use pra validar assinatura HMAC nos POSTs que seu handler recebe.

Exemplo

curl -X POST 'https://api.ravimail.com.br/v1/inbound/routes' \ -H 'Authorization: Bearer rvm_live_xxxxxxxx' \ -H 'Content-Type: application/json' \ -d '{ ... }'
// composer require ravisystems/ravimail-php use Ravimail\Client; $rm = new Client('rvm_live_xxxxxxxx'); $result = $rm->inboundRoutes->create([...]);

Códigos de resposta

201 Criada (retorna forward_secret 1x)

Exemplo de resposta

{ "data": [ { "id": "ibr_99", "pattern": "support+*@suaempresa.com.br", "forward_url": "https://api.cliente.com/inbound" } ], "meta": { "has_more": true, "next_cursor": "eyJpZCI6MTAwMH0=" } }

Headers: X-Request-Id, X-RateLimit-Limit, X-RateLimit-Remaining

GET
/v1/inbound/routes/{id}

Detalhes

O que faz

Detalhe da regra: pattern, forward_url, status, contagem de matches últimos 30d. forward_secret NÃO é exposto — só na criação.

Parâmetros

path
id string obrigatório

Exemplo

curl 'https://api.ravimail.com.br/v1/inbound/routes/123' \ -H 'Authorization: Bearer rvm_live_xxxxxxxx'
// composer require ravisystems/ravimail-php use Ravimail\Client; $rm = new Client('rvm_live_xxxxxxxx'); $result = $rm->inboundRoutes->get(123);

Códigos de resposta

200 Detalhes

Exemplo de resposta

{ "data": { "id": "ibr_99", "pattern": "support+*@suaempresa.com.br", "forward_url": "https://api.cliente.com/inbound", "forward_secret": null, "created_at": "2026-05-10T08:00:00Z" } }

Headers: X-Request-Id, X-RateLimit-Limit, X-RateLimit-Remaining

PUT
/v1/inbound/routes/{id}

Atualiza regra (pattern, forward_url)

O que faz

Atualiza pattern ou forward_url da regra. Não regenera o forward_secret. Útil pra mudar o handler sem perder histórico nem precisar reconfigurar HMAC validation.

Parâmetros

path
id string obrigatório

Exemplo

curl -X PUT 'https://api.ravimail.com.br/v1/inbound/routes/123' \ -H 'Authorization: Bearer rvm_live_xxxxxxxx' \ -H 'Content-Type: application/json' \ -d '{ ... }'
// composer require ravisystems/ravimail-php use Ravimail\Client; $rm = new Client('rvm_live_xxxxxxxx'); $result = $rm->inboundRoutes->update(123, [...]);

Códigos de resposta

200 Atualizada

Exemplo de resposta

{ "data": { "id": "ibr_99", "pattern": "support+*@suaempresa.com.br", "forward_url": "https://api.cliente.com/inbound", "forward_secret": null, "created_at": "2026-05-10T08:00:00Z" } }

Headers: X-Request-Id, X-RateLimit-Limit, X-RateLimit-Remaining

DELETE
/v1/inbound/routes/{id}

Remove regra

O que faz

Remove a regra. Emails que matchariam o pattern voltam a ser tratados pelo catch-all (geralmente descartados). Histórico de matches é mantido pra auditoria.

Parâmetros

path
id string obrigatório

Exemplo

curl -X DELETE 'https://api.ravimail.com.br/v1/inbound/routes/123' \ -H 'Authorization: Bearer rvm_live_xxxxxxxx'
// composer require ravisystems/ravimail-php use Ravimail\Client; $rm = new Client('rvm_live_xxxxxxxx'); $result = $rm->inboundRoutes->delete(123);

Códigos de resposta

204 Removida

Exemplo de resposta

# 204 No Content — body vazio HTTP/1.1 204 No Content X-Request-Id: req_a1b2c3d4e5f6

Lists

5 endpoints

GET
/v1/lists

Lista

O que faz

Lista todas as listas de contatos do user (no RaviMail, 'listas' equivalem a 'grupos/pastas' em outras plataformas). Cada item inclui nome, count atual de contatos e timestamp da última validação MX.

Exemplo

curl 'https://api.ravimail.com.br/v1/lists' \ -H 'Authorization: Bearer rvm_live_xxxxxxxx'
// composer require ravisystems/ravimail-php use Ravimail\Client; $rm = new Client('rvm_live_xxxxxxxx'); $result = $rm->lists->list();

Códigos de resposta

200 Lista

Exemplo de resposta

{ "data": [ { "id": 7, "name": "Leads Q2", "contact_count": 1543 } ], "meta": { "has_more": true, "next_cursor": "eyJpZCI6MTAwMH0=" } }

Headers: X-Request-Id, X-RateLimit-Limit, X-RateLimit-Remaining

POST
/v1/lists

Cria

O que faz

Cria uma nova lista. Listas são containers organizacionais — todo contato pertence a UMA lista. Útil pra separar audiências por origem (newsletter, ecommerce, captura, etc) ou por estágio do funil.

Exemplo

curl -X POST 'https://api.ravimail.com.br/v1/lists' \ -H 'Authorization: Bearer rvm_live_xxxxxxxx' \ -H 'Content-Type: application/json' \ -d '{ ... }'
// composer require ravisystems/ravimail-php use Ravimail\Client; $rm = new Client('rvm_live_xxxxxxxx'); $result = $rm->lists->create([...]);

Códigos de resposta

201 Criado

Exemplo de resposta

{ "data": [ { "id": 7, "name": "Leads Q2", "contact_count": 1543 } ], "meta": { "has_more": true, "next_cursor": "eyJpZCI6MTAwMH0=" } }

Headers: X-Request-Id, X-RateLimit-Limit, X-RateLimit-Remaining

GET
/v1/lists/{id}

Show

O que faz

Detalhe da lista: nome, descrição, count atual de contatos por status (active/suppressed/bounced), `last_validated_at` (idade da última validação MX — listas >25d podem ser bloqueadas pra disparo).

Parâmetros

path
id string obrigatório

Exemplo

curl 'https://api.ravimail.com.br/v1/lists/123' \ -H 'Authorization: Bearer rvm_live_xxxxxxxx'
// composer require ravisystems/ravimail-php use Ravimail\Client; $rm = new Client('rvm_live_xxxxxxxx'); $result = $rm->lists->get(123);

Códigos de resposta

200 Lista

Exemplo de resposta

{ "data": { "id": 7, "name": "Leads Q2 2026", "contact_count": 1543, "last_validated_at": "2026-05-15T08:00:00Z", "created_at": "2026-04-01T09:00:00Z" } }

Headers: X-Request-Id, X-RateLimit-Limit, X-RateLimit-Remaining

PUT
/v1/lists/{id}

Update

O que faz

Atualiza nome ou descrição da lista. Não afeta contatos contidos. Operação rápida — não recomputa counts nem revalida MX.

Parâmetros

path
id string obrigatório

Exemplo

curl -X PUT 'https://api.ravimail.com.br/v1/lists/123' \ -H 'Authorization: Bearer rvm_live_xxxxxxxx' \ -H 'Content-Type: application/json' \ -d '{ ... }'
// composer require ravisystems/ravimail-php use Ravimail\Client; $rm = new Client('rvm_live_xxxxxxxx'); $result = $rm->lists->update(123, [...]);

Códigos de resposta

200 Atualizada

Exemplo de resposta

{ "data": { "id": 7, "name": "Leads Q2 2026", "contact_count": 1543, "last_validated_at": "2026-05-15T08:00:00Z", "created_at": "2026-04-01T09:00:00Z" } }

Headers: X-Request-Id, X-RateLimit-Limit, X-RateLimit-Remaining

DELETE
/v1/lists/{id}

Delete

O que faz

Remove a lista e TODOS os contatos contidos. **Operação destrutiva** — use force=1 query param pra confirmar quando há contatos. Campanhas antigas que referenciam essa lista mantém histórico, mas não podem ser duplicadas pra novo envio.

Parâmetros

path
id string obrigatório

Exemplo

curl -X DELETE 'https://api.ravimail.com.br/v1/lists/123' \ -H 'Authorization: Bearer rvm_live_xxxxxxxx'
// composer require ravisystems/ravimail-php use Ravimail\Client; $rm = new Client('rvm_live_xxxxxxxx'); $result = $rm->lists->delete(123);

Códigos de resposta

204 Removida

Exemplo de resposta

# 204 No Content — body vazio HTTP/1.1 204 No Content X-Request-Id: req_a1b2c3d4e5f6

Recommendations

1 endpoint

GET
/v1/recommendations

Lista recomendações de deliverability (SES-style)

O que faz

Análise automatizada da conta retornando lista priorizada de melhorias acionáveis: 'Adicionar DMARC ao domínio X', 'IP Y tem bounce rate acima do ideal', 'Lista Z não foi validada há 25 dias'. Cada item inclui severidade, ação sugerida e link pro recurso afetado. Reduz tempo de troubleshooting de deliverability.

Exemplo

curl 'https://api.ravimail.com.br/v1/recommendations' \ -H 'Authorization: Bearer rvm_live_xxxxxxxx'
// composer require ravisystems/ravimail-php use Ravimail\Client; $rm = new Client('rvm_live_xxxxxxxx'); $result = $rm->request->list();

Códigos de resposta

200 Recomendações priorizadas

Exemplo de resposta

{ "data": [ { "id": "rec_1", "severity": "medium", "title": "Adicione DMARC ao domínio mail.suaempresa.com.br", "action_url": "/dashboard/domains/7" } ], "meta": { "has_more": true, "next_cursor": "eyJpZCI6MTAwMH0=" } }

Headers: X-Request-Id, X-RateLimit-Limit, X-RateLimit-Remaining

Reports

5 endpoints

GET
/v1/reports

Lista relatórios agendados

O que faz

Lista todos os relatórios automáticos agendados pelo user. Cada item: nome, frequency, lista de recipients, próximo envio. Reports geram CSV/PDF e enviam por email automaticamente.

Exemplo

curl 'https://api.ravimail.com.br/v1/reports' \ -H 'Authorization: Bearer rvm_live_xxxxxxxx'
// composer require ravisystems/ravimail-php use Ravimail\Client; $rm = new Client('rvm_live_xxxxxxxx'); $result = $rm->request->list();

Códigos de resposta

200 Lista

Exemplo de resposta

{ "data": [ { "id": 11, "name": "Resumo semanal", "frequency": "weekly" } ], "meta": { "has_more": true, "next_cursor": "eyJpZCI6MTAwMH0=" } }

Headers: X-Request-Id, X-RateLimit-Limit, X-RateLimit-Remaining

POST
/v1/reports

Agenda relatório

O que faz

Cria um relatório agendado. Aceita `frequency` (daily/weekly/monthly), `recipients` (array de emails), `metrics` (quais incluir), `filters`. O sistema gera e envia automaticamente conforme a periodicidade. Útil pra stakeholders que precisam de visibilidade sem acessar o painel.

Exemplo

curl -X POST 'https://api.ravimail.com.br/v1/reports' \ -H 'Authorization: Bearer rvm_live_xxxxxxxx' \ -H 'Content-Type: application/json' \ -d '{ ... }'
// composer require ravisystems/ravimail-php use Ravimail\Client; $rm = new Client('rvm_live_xxxxxxxx'); $result = $rm->request->create([...]);

Códigos de resposta

201 Agendado

Exemplo de resposta

{ "data": [ { "id": 11, "name": "Resumo semanal", "frequency": "weekly" } ], "meta": { "has_more": true, "next_cursor": "eyJpZCI6MTAwMH0=" } }

Headers: X-Request-Id, X-RateLimit-Limit, X-RateLimit-Remaining

GET
/v1/reports/{id}

Detalhes

O que faz

Detalhe completo do report: config (frequency, recipients, metrics, filters), histórico das últimas 10 gerações, próxima execução.

Parâmetros

path
id string obrigatório

Exemplo

curl 'https://api.ravimail.com.br/v1/reports/123' \ -H 'Authorization: Bearer rvm_live_xxxxxxxx'
// composer require ravisystems/ravimail-php use Ravimail\Client; $rm = new Client('rvm_live_xxxxxxxx'); $result = $rm->request->get(123);

Códigos de resposta

200 Detalhes

Exemplo de resposta

{ "data": { "id": 11, "name": "Resumo semanal", "frequency": "weekly", "recipients": [ "rodrigo@ravimail.com.br" ], "next_run_at": "2026-05-26T08:00:00Z" } }

Headers: X-Request-Id, X-RateLimit-Limit, X-RateLimit-Remaining

PUT
/v1/reports/{id}

Atualiza report (frequency, recipients)

O que faz

Atualiza configuração do report. Mudanças entram em vigor na próxima execução agendada — não regenera retroativamente.

Parâmetros

path
id string obrigatório

Exemplo

curl -X PUT 'https://api.ravimail.com.br/v1/reports/123' \ -H 'Authorization: Bearer rvm_live_xxxxxxxx' \ -H 'Content-Type: application/json' \ -d '{ ... }'
// composer require ravisystems/ravimail-php use Ravimail\Client; $rm = new Client('rvm_live_xxxxxxxx'); $result = $rm->request->update(123, [...]);

Códigos de resposta

200 Atualizado

Exemplo de resposta

{ "data": { "id": 11, "name": "Resumo semanal", "frequency": "weekly", "recipients": [ "rodrigo@ravimail.com.br" ], "next_run_at": "2026-05-26T08:00:00Z" } }

Headers: X-Request-Id, X-RateLimit-Limit, X-RateLimit-Remaining

DELETE
/v1/reports/{id}

Remove report

O que faz

Remove o agendamento. Reports históricos já gerados continuam acessíveis. Não cancela emails já enviados aos recipients.

Parâmetros

path
id string obrigatório

Exemplo

curl -X DELETE 'https://api.ravimail.com.br/v1/reports/123' \ -H 'Authorization: Bearer rvm_live_xxxxxxxx'
// composer require ravisystems/ravimail-php use Ravimail\Client; $rm = new Client('rvm_live_xxxxxxxx'); $result = $rm->request->delete(123);

Códigos de resposta

204 Removido

Exemplo de resposta

# 204 No Content — body vazio HTTP/1.1 204 No Content X-Request-Id: req_a1b2c3d4e5f6

Reputation

5 endpoints

GET
/v1/reputation/summary

Score agregado 24h + grade A-F

O que faz

Score agregado de reputação do user nas últimas 24h em grade A/B/C/D/F. Combina: bounce rate, complaint rate, presença em RBLs, idade dos IPs, diversidade de remetentes. Use como métrica de saúde geral — score baixo (D/F) indica risco real de degradação de entregabilidade.

Exemplo

curl 'https://api.ravimail.com.br/v1/reputation/summary' \ -H 'Authorization: Bearer rvm_live_xxxxxxxx'
// composer require ravisystems/ravimail-php use Ravimail\Client; $rm = new Client('rvm_live_xxxxxxxx'); $result = $rm->reputation->list();

Códigos de resposta

200 Score

Exemplo de resposta

{ "data": { "score": 87, "grade": "A", "sent_24h": 12450, "bounce_rate": 1.5, "complaint_rate": 0.02, "rbl_listings": 0, "computed_at": "2026-05-19T14:30:00Z" } }

Headers: X-Request-Id, X-RateLimit-Limit, X-RateLimit-Remaining

GET
/v1/reputation/domains

Score per-domain 24h

O que faz

Score detalhado por domínio remetente nas últimas 24h. Cada linha: domain, score, grade, volume enviado, bounce/complaint rate, presença em RBLs (Spamhaus, SURBL). Use pra detectar domínios queimados antes de campanhas grandes.

Exemplo

curl 'https://api.ravimail.com.br/v1/reputation/domains' \ -H 'Authorization: Bearer rvm_live_xxxxxxxx'
// composer require ravisystems/ravimail-php use Ravimail\Client; $rm = new Client('rvm_live_xxxxxxxx'); $result = $rm->reputation->list();

Códigos de resposta

200 Rows

Exemplo de resposta

{ "data": { "data": [ { "key": "mail.suaempresa.com.br", "score": 87, "grade": "A", "sent_24h": 4521 } ] } }

Headers: X-Request-Id, X-RateLimit-Limit, X-RateLimit-Remaining

GET
/v1/reputation/ips

Score per-IP 24h

O que faz

Score por IP de envio nas últimas 24h. Inclui dia do warmup, bounces por bucket de ISP (gmail/microsoft/yahoo/other), throttle 4.7.x detectado, complaints e listagens em RBL. Útil pra identificar IPs problemáticos antes de afetar deliverability global.

Exemplo

curl 'https://api.ravimail.com.br/v1/reputation/ips' \ -H 'Authorization: Bearer rvm_live_xxxxxxxx'
// composer require ravisystems/ravimail-php use Ravimail\Client; $rm = new Client('rvm_live_xxxxxxxx'); $result = $rm->reputation->list();

Códigos de resposta

200 Rows

Exemplo de resposta

{ "data": { "data": [ { "key": "mail.suaempresa.com.br", "score": 87, "grade": "A", "sent_24h": 4521 } ] } }

Headers: X-Request-Id, X-RateLimit-Limit, X-RateLimit-Remaining

GET
/v1/reputation/nodes

Score per-node 24h

O que faz

Score por nó de envio (servidor SMTP físico) nas últimas 24h. Soma comportamento de todos os IPs do nó. Use quando o nó tem múltiplos IPs e você quer ver saúde agregada da máquina como um todo.

Exemplo

curl 'https://api.ravimail.com.br/v1/reputation/nodes' \ -H 'Authorization: Bearer rvm_live_xxxxxxxx'
// composer require ravisystems/ravimail-php use Ravimail\Client; $rm = new Client('rvm_live_xxxxxxxx'); $result = $rm->reputation->list();

Códigos de resposta

200 Rows

Exemplo de resposta

{ "data": { "data": [ { "key": "mail.suaempresa.com.br", "score": 87, "grade": "A", "sent_24h": 4521 } ] } }

Headers: X-Request-Id, X-RateLimit-Limit, X-RateLimit-Remaining

GET
/v1/reputation/blacklists

Status de listagem em RBLs públicas (Spamhaus/SURBL/etc)

O que faz

Verifica se domínios e IPs do user estão listados em RBLs públicas reconhecidas (Spamhaus DBL/SBL/PBL/CSS, SURBL, URIBL, ivmURI). Listagem decisiva (Spamhaus DBL) ou em múltiplas secundárias indica reputação queimada — pause envios e investigue. Cron interno checa diariamente; este endpoint é leitura on-demand.

Exemplo

curl 'https://api.ravimail.com.br/v1/reputation/blacklists' \ -H 'Authorization: Bearer rvm_live_xxxxxxxx'
// composer require ravisystems/ravimail-php use Ravimail\Client; $rm = new Client('rvm_live_xxxxxxxx'); $result = $rm->reputation->list();

Códigos de resposta

200 Blacklist report

Exemplo de resposta

{ "data": { "checked_at": "2026-05-19T14:00:00Z", "domains": [ { "domain": "mail.suaempresa.com.br", "listed_in": [] } ], "ips": [ { "ip": "203.0.113.10", "listed_in": [ "Spamhaus DBL" ] } ] } }

Headers: X-Request-Id, X-RateLimit-Limit, X-RateLimit-Remaining

SMTP Relay

2 endpoints

GET
/v1/smtp/info

Config + credenciais pra conectar via SMTP

O que faz

Retorna config pra conectar via SMTP em vez de REST: host, porta (587 STARTTLS ou 465 TLS), user (`api`), e instrução pra usar o token API como senha. Útil pra integrações com sistemas legados (WordPress, PHPMailer, Nodemailer) que falam SMTP nativamente. SASL PLAIN ou LOGIN.

Exemplo

curl 'https://api.ravimail.com.br/v1/smtp/info' \ -H 'Authorization: Bearer rvm_live_xxxxxxxx'
// composer require ravisystems/ravimail-php use Ravimail\Client; $rm = new Client('rvm_live_xxxxxxxx'); $result = $rm->request->list();

Códigos de resposta

200 Config

Exemplo de resposta

{ "data": { "host": "smtp.ravimail.com.br", "port_starttls": 587, "port_tls": 465, "user": "api", "password_hint": "Use seu token rvm_live_*", "auth_methods": [ "PLAIN", "LOGIN" ] } }

Headers: X-Request-Id, X-RateLimit-Limit, X-RateLimit-Remaining

GET
/v1/smtp/log

Audit log de conexões (result=accepted|auth_failed|rejected)

O que faz

Log de conexões SMTP recebidas: IP, hora, user usado, resultado (accepted/auth_failed/rejected) e mensagem do servidor. Use pra debug quando WordPress/PHPMailer não está enviando — você vê exatamente em qual estágio está falhando (auth, rate limit, conteúdo rejeitado).

Exemplo

curl 'https://api.ravimail.com.br/v1/smtp/log' \ -H 'Authorization: Bearer rvm_live_xxxxxxxx'
// composer require ravisystems/ravimail-php use Ravimail\Client; $rm = new Client('rvm_live_xxxxxxxx'); $result = $rm->request->list();

Códigos de resposta

200 Log cursor-paginated

Exemplo de resposta

{ "data": [ { "at": "2026-05-19T14:30:00Z", "ip": "203.0.113.45", "user": "api", "result": "accepted" } ], "meta": { "has_more": true, "next_cursor": "eyJpZCI6MTAwMH0=" } }

Headers: X-Request-Id, X-RateLimit-Limit, X-RateLimit-Remaining

Segments

6 endpoints

GET
/v1/segments

Lista segments

O que faz

Lista segmentos dinâmicos do user. Diferente de listas (containers estáticos), segments são consultas declarativas (rules) que retornam contatos correspondentes em tempo real.

Exemplo

curl 'https://api.ravimail.com.br/v1/segments' \ -H 'Authorization: Bearer rvm_live_xxxxxxxx'
// composer require ravisystems/ravimail-php use Ravimail\Client; $rm = new Client('rvm_live_xxxxxxxx'); $result = $rm->segments->list();

Códigos de resposta

200 Lista

Exemplo de resposta

{ "data": [ { "id": 5, "name": "Engajados 30d", "last_count": 487 } ], "meta": { "has_more": true, "next_cursor": "eyJpZCI6MTAwMH0=" } }

Headers: X-Request-Id, X-RateLimit-Limit, X-RateLimit-Remaining

POST
/v1/segments

Cria segment dinâmico (rules)

O que faz

Cria segmento dinâmico definido por rules (ex: `opens_30d > 3 AND tags contains 'vip'`). Conta atualiza automaticamente conforme contatos mudam. Use como input pra campanhas em vez de listas estáticas — alcança apenas quem está realmente engajado.

Exemplo

curl -X POST 'https://api.ravimail.com.br/v1/segments' \ -H 'Authorization: Bearer rvm_live_xxxxxxxx' \ -H 'Content-Type: application/json' \ -d '{ ... }'
// composer require ravisystems/ravimail-php use Ravimail\Client; $rm = new Client('rvm_live_xxxxxxxx'); $result = $rm->segments->create([...]);

Códigos de resposta

201 Criado

Exemplo de resposta

{ "data": [ { "id": 5, "name": "Engajados 30d", "last_count": 487 } ], "meta": { "has_more": true, "next_cursor": "eyJpZCI6MTAwMH0=" } }

Headers: X-Request-Id, X-RateLimit-Limit, X-RateLimit-Remaining

GET
/v1/segments/{id}

Detalhes do segment

O que faz

Detalhe do segment: rules, last_count, timestamp do último compute. Pra recomputar agora use GET /segments/{id}/compute.

Parâmetros

path
id string obrigatório

Exemplo

curl 'https://api.ravimail.com.br/v1/segments/123' \ -H 'Authorization: Bearer rvm_live_xxxxxxxx'
// composer require ravisystems/ravimail-php use Ravimail\Client; $rm = new Client('rvm_live_xxxxxxxx'); $result = $rm->segments->get(123);

Códigos de resposta

200 Detalhes

Exemplo de resposta

{ "data": { "id": 5, "name": "Engajados últimos 30d", "rules": [ { "field": "opens_30d", "op": ">", "value": 3 } ], "last_count": 487 } }

Headers: X-Request-Id, X-RateLimit-Limit, X-RateLimit-Remaining

PUT
/v1/segments/{id}

Atualiza rules do segment

O que faz

Atualiza rules ou nome do segment. Não recomputa imediatamente — o próximo compute reflete as novas rules. Mudanças em rules de segment usado por drips em andamento podem alterar quem continua/sai da sequência.

Parâmetros

path
id string obrigatório

Exemplo

curl -X PUT 'https://api.ravimail.com.br/v1/segments/123' \ -H 'Authorization: Bearer rvm_live_xxxxxxxx' \ -H 'Content-Type: application/json' \ -d '{ ... }'
// composer require ravisystems/ravimail-php use Ravimail\Client; $rm = new Client('rvm_live_xxxxxxxx'); $result = $rm->segments->update(123, [...]);

Códigos de resposta

200 Atualizado

Exemplo de resposta

{ "data": { "id": 5, "name": "Engajados últimos 30d", "rules": [ { "field": "opens_30d", "op": ">", "value": 3 } ], "last_count": 487 } }

Headers: X-Request-Id, X-RateLimit-Limit, X-RateLimit-Remaining

DELETE
/v1/segments/{id}

Remove segment

O que faz

Remove o segment. Campanhas que usaram ficam intactas (snapshot dos contatos preservado no momento do disparo). Drips usando esse segment como trigger ficam inativas.

Parâmetros

path
id string obrigatório

Exemplo

curl -X DELETE 'https://api.ravimail.com.br/v1/segments/123' \ -H 'Authorization: Bearer rvm_live_xxxxxxxx'
// composer require ravisystems/ravimail-php use Ravimail\Client; $rm = new Client('rvm_live_xxxxxxxx'); $result = $rm->segments->delete(123);

Códigos de resposta

204 Removido

Exemplo de resposta

# 204 No Content — body vazio HTTP/1.1 204 No Content X-Request-Id: req_a1b2c3d4e5f6
GET
/v1/segments/{id}/compute

Avalia rules (count + preview ?preview=1)

O que faz

Executa as rules do segment em tempo real e retorna o count de contatos que atendem. Com `?preview=1`, inclui uma amostra de 10 contatos pra verificação manual. Use antes de criar campanha pra confirmar o tamanho da audiência. Segments são dinâmicos: o count pode mudar entre chamadas conforme contatos são adicionados/atualizados.

Parâmetros

path
id string obrigatório

Exemplo

curl 'https://api.ravimail.com.br/v1/segments/123/compute' \ -H 'Authorization: Bearer rvm_live_xxxxxxxx'
// composer require ravisystems/ravimail-php use Ravimail\Client; $rm = new Client('rvm_live_xxxxxxxx'); $result = $rm->segments->get(123);

Códigos de resposta

200 Count + sample

Exemplo de resposta

{ "data": { "segment_id": 5, "count": 487, "computed_at": "2026-05-19T14:30:00Z", "preview": [ { "id": 1, "email": "a@b.com" }, { "id": 2, "email": "c@d.com" } ] } }

Headers: X-Request-Id, X-RateLimit-Limit, X-RateLimit-Remaining

Subaccounts

9 endpoints

GET
/v1/subaccounts

Lista subaccounts (só parent token)

O que faz

Lista subaccounts do user parent. Endpoint disponível apenas pra token da conta principal — tokens de subaccounts não enxergam outros subaccounts. Cada item inclui counters de envio agregados últimos 30d.

Exemplo

curl 'https://api.ravimail.com.br/v1/subaccounts' \ -H 'Authorization: Bearer rvm_live_xxxxxxxx'
// composer require ravisystems/ravimail-php use Ravimail\Client; $rm = new Client('rvm_live_xxxxxxxx'); $result = $rm->subaccounts->list();

Códigos de resposta

200 Lista

Exemplo de resposta

{ "data": [ { "id": 12, "name": "Acme Corp", "status": "active", "sent_30d": 4500 } ], "meta": { "has_more": true, "next_cursor": "eyJpZCI6MTAwMH0=" } }

Headers: X-Request-Id, X-RateLimit-Limit, X-RateLimit-Remaining

POST
/v1/subaccounts

Cria subaccount

O que faz

Cria uma subaccount isolada (multi-tenant). Útil pra agências/SaaS que revendem RaviMail: cada subaccount tem seus próprios contatos, campanhas, métricas e tokens isolados — sem cross-contamination. Cobrança continua na conta parent.

Exemplo

curl -X POST 'https://api.ravimail.com.br/v1/subaccounts' \ -H 'Authorization: Bearer rvm_live_xxxxxxxx' \ -H 'Content-Type: application/json' \ -d '{ ... }'
// composer require ravisystems/ravimail-php use Ravimail\Client; $rm = new Client('rvm_live_xxxxxxxx'); $result = $rm->subaccounts->create([...]);

Códigos de resposta

201 Criada

Exemplo de resposta

{ "data": [ { "id": 12, "name": "Acme Corp", "status": "active", "sent_30d": 4500 } ], "meta": { "has_more": true, "next_cursor": "eyJpZCI6MTAwMH0=" } }

Headers: X-Request-Id, X-RateLimit-Limit, X-RateLimit-Remaining

GET
/v1/subaccounts/{id}

Detalhes

O que faz

Detalhe da subaccount: nome, status (active/suspended), datas, count de tokens, métricas agregadas dos últimos 30d.

Parâmetros

path
id string obrigatório

Exemplo

curl 'https://api.ravimail.com.br/v1/subaccounts/123' \ -H 'Authorization: Bearer rvm_live_xxxxxxxx'
// composer require ravisystems/ravimail-php use Ravimail\Client; $rm = new Client('rvm_live_xxxxxxxx'); $result = $rm->subaccounts->get(123);

Códigos de resposta

200 Detalhes

Exemplo de resposta

{ "data": { "id": 12, "name": "Cliente — Acme Corp", "status": "active", "created_at": "2026-04-15T10:00:00Z", "tokens_count": 2, "sent_30d": 4500 } }

Headers: X-Request-Id, X-RateLimit-Limit, X-RateLimit-Remaining

PUT
/v1/subaccounts/{id}

Atualiza subaccount (name, settings)

O que faz

Atualiza nome ou settings da subaccount. Não afeta tokens nem dados internos. Use pra renomear quando o cliente muda razão social ou pra ajustar limites/quotas.

Parâmetros

path
id string obrigatório

Exemplo

curl -X PUT 'https://api.ravimail.com.br/v1/subaccounts/123' \ -H 'Authorization: Bearer rvm_live_xxxxxxxx' \ -H 'Content-Type: application/json' \ -d '{ ... }'
// composer require ravisystems/ravimail-php use Ravimail\Client; $rm = new Client('rvm_live_xxxxxxxx'); $result = $rm->subaccounts->update(123, [...]);

Códigos de resposta

200 Atualizada

Exemplo de resposta

{ "data": { "id": 12, "name": "Cliente — Acme Corp", "status": "active", "created_at": "2026-04-15T10:00:00Z", "tokens_count": 2, "sent_30d": 4500 } }

Headers: X-Request-Id, X-RateLimit-Limit, X-RateLimit-Remaining

DELETE
/v1/subaccounts/{id}

Remove subaccount (revoga todos tokens)

O que faz

**Operação destrutiva.** Remove subaccount permanentemente: revoga todos os tokens, deleta contatos, campanhas, templates e métricas associadas. Considere /suspend se quer preservar histórico.

Parâmetros

path
id string obrigatório

Exemplo

curl -X DELETE 'https://api.ravimail.com.br/v1/subaccounts/123' \ -H 'Authorization: Bearer rvm_live_xxxxxxxx'
// composer require ravisystems/ravimail-php use Ravimail\Client; $rm = new Client('rvm_live_xxxxxxxx'); $result = $rm->subaccounts->delete(123);

Códigos de resposta

204 Removida

Exemplo de resposta

# 204 No Content — body vazio HTTP/1.1 204 No Content X-Request-Id: req_a1b2c3d4e5f6
POST
/v1/subaccounts/{id}/suspend

Suspende subaccount (revoga tokens)

O que faz

Suspende a subaccount: todos os tokens API são revogados imediatamente (qualquer envio em andamento retorna 401), campanhas em andamento são pausadas. Dados ficam intactos pra reativação posterior. Use quando cliente para de pagar mas você quer preservar histórico.

Parâmetros

path
id string obrigatório

Exemplo

curl -X POST 'https://api.ravimail.com.br/v1/subaccounts/123/suspend' \ -H 'Authorization: Bearer rvm_live_xxxxxxxx' \ -H 'Content-Type: application/json' \ -d '{ ... }'
// composer require ravisystems/ravimail-php use Ravimail\Client; $rm = new Client('rvm_live_xxxxxxxx'); $result = $rm->subaccounts->create([...]);

Códigos de resposta

200 OK

Exemplo de resposta

{ "data": { "id": 12, "status": "suspended", "revoked_tokens": 3 } }

Headers: X-Request-Id, X-RateLimit-Limit, X-RateLimit-Remaining

POST
/v1/subaccounts/{id}/unsuspend

Reativa subaccount

O que faz

Reativa a subaccount. Dados ficam acessíveis novamente, mas tokens foram revogados no suspend — você precisa gerar novos tokens via POST /subaccounts/{id}/tokens. Campanhas pausadas precisam ser retomadas manualmente.

Parâmetros

path
id string obrigatório

Exemplo

curl -X POST 'https://api.ravimail.com.br/v1/subaccounts/123/unsuspend' \ -H 'Authorization: Bearer rvm_live_xxxxxxxx' \ -H 'Content-Type: application/json' \ -d '{ ... }'
// composer require ravisystems/ravimail-php use Ravimail\Client; $rm = new Client('rvm_live_xxxxxxxx'); $result = $rm->subaccounts->create([...]);

Códigos de resposta

200 OK

Exemplo de resposta

{ "data": { "id": 12, "status": "active" } }

Headers: X-Request-Id, X-RateLimit-Limit, X-RateLimit-Remaining

GET
/v1/subaccounts/{id}/tokens

Lista tokens do subaccount

O que faz

Lista tokens API associados ao subaccount. Hash de cada token NÃO é exposto (security) — só metadata (scopes, IP whitelist, last_used_at). Use no painel de gestão de subaccounts pra ver quem tem acesso à conta filha.

Parâmetros

path
id string obrigatório

Exemplo

curl 'https://api.ravimail.com.br/v1/subaccounts/123/tokens' \ -H 'Authorization: Bearer rvm_live_xxxxxxxx'
// composer require ravisystems/ravimail-php use Ravimail\Client; $rm = new Client('rvm_live_xxxxxxxx'); $result = $rm->subaccounts->get(123);

Códigos de resposta

200 Tokens

Exemplo de resposta

{ "data": [ { "id": "tok_xy99", "name": "Prod", "scopes": [ "transactional:send" ], "last_used_at": "2026-05-19T14:25:00Z" } ], "meta": { "has_more": true, "next_cursor": "eyJpZCI6MTAwMH0=" } }

Headers: X-Request-Id, X-RateLimit-Limit, X-RateLimit-Remaining

POST
/v1/subaccounts/{id}/tokens

Cria token scoped pro subaccount (retorna plaintext 1x)

O que faz

Gera um novo token API que opera APENAS sobre os recursos do subaccount (isolamento total). Útil pra entregar credenciais ao cliente da sua agência sem expor a conta parent. O token plaintext é retornado **uma única vez** — depois disso só hash. Scopes podem ser mais restritos que os do parent, nunca mais amplos.

Parâmetros

path
id string obrigatório

Exemplo

curl -X POST 'https://api.ravimail.com.br/v1/subaccounts/123/tokens' \ -H 'Authorization: Bearer rvm_live_xxxxxxxx' \ -H 'Content-Type: application/json' \ -d '{ ... }'
// composer require ravisystems/ravimail-php use Ravimail\Client; $rm = new Client('rvm_live_xxxxxxxx'); $result = $rm->subaccounts->create([...]);

Códigos de resposta

201 Token criado

Exemplo de resposta

{ "data": { "id": "tok_xy99", "token": "rvm_live_NEW_FULL_PLAINTEXT_xxxxxxxxxxxxxxxx", "scopes": [ "transactional:send" ], "subaccount_id": 12 } }

Headers: X-Request-Id, X-RateLimit-Limit, X-RateLimit-Remaining

Suppression

3 endpoints

GET
/v1/suppression

Lista emails suprimidos

O que faz

Lista global de emails suprimidos: hard bounces, complaints (spam), opt-outs e adições manuais. Cada item inclui motivo (`reason`), timestamp e fonte (auto/manual/webhook). Pra compliance LGPD, esta lista garante que emails removidos NUNCA receberão envios novamente, mesmo se reimportados em outras listas.

Exemplo

curl 'https://api.ravimail.com.br/v1/suppression' \ -H 'Authorization: Bearer rvm_live_xxxxxxxx'
// composer require ravisystems/ravimail-php use Ravimail\Client; $rm = new Client('rvm_live_xxxxxxxx'); $result = $rm->suppression->list();

Códigos de resposta

200 Lista

Exemplo de resposta

{ "data": [ { "email": "bouncer@x.com", "reason": "hard_bounce", "created_at": "2026-05-15T10:00:00Z" } ], "meta": { "has_more": true, "next_cursor": "eyJpZCI6MTAwMH0=" } }

Headers: X-Request-Id, X-RateLimit-Limit, X-RateLimit-Remaining

POST
/v1/suppression

Suprime email em massa

O que faz

Adiciona emails à supressão global em lote. Aceita array de até 1000 emails. Útil pra importar opt-outs de outros sistemas (ex: ao migrar do SendGrid, importe a lista de suppressions deles aqui pra preservar opt-outs). Idempotente: emails já suprimidos são ignorados.

Exemplo

curl -X POST 'https://api.ravimail.com.br/v1/suppression' \ -H 'Authorization: Bearer rvm_live_xxxxxxxx' \ -H 'Content-Type: application/json' \ -d '{ ... }'
// composer require ravisystems/ravimail-php use Ravimail\Client; $rm = new Client('rvm_live_xxxxxxxx'); $result = $rm->suppression->create([...]);

Códigos de resposta

200 Contagem afetada

Exemplo de resposta

{ "data": { "suppressed": 87, "already_suppressed": 13 } }

Headers: X-Request-Id, X-RateLimit-Limit, X-RateLimit-Remaining

DELETE
/v1/suppression/{email}

Re-ativa

O que faz

Remove o email da supressão global, permitindo que campanhas e disparos futuros possam entregar pra ele de novo. Use com cuidado — só faça quando tiver confirmação explícita do user (opt-in renovado). Não reverte automaticamente os motivos: se o email estava suprimido por hard bounce e você reativa, pode ser suprimido novamente em outro bounce.

Parâmetros

path
email string obrigatório

Exemplo

curl -X DELETE 'https://api.ravimail.com.br/v1/suppression/user%40example.com' \ -H 'Authorization: Bearer rvm_live_xxxxxxxx'
// composer require ravisystems/ravimail-php use Ravimail\Client; $rm = new Client('rvm_live_xxxxxxxx'); $result = $rm->suppression->delete(123);

Códigos de resposta

200 Reativados

Exemplo de resposta

# 204 No Content — body vazio HTTP/1.1 204 No Content X-Request-Id: req_a1b2c3d4e5f6

Tags

9 endpoints

GET
/v1/campaigns/{id}/tags

Lista tags da campanha

O que faz

Lista tags associadas à campanha. Tags são labels arbitrários (strings) usados pra organização interna, filtros em listagens e agrupamento em relatórios.

Parâmetros

path
id string obrigatório

Exemplo

curl 'https://api.ravimail.com.br/v1/campaigns/123/tags' \ -H 'Authorization: Bearer rvm_live_xxxxxxxx'
// composer require ravisystems/ravimail-php use Ravimail\Client; $rm = new Client('rvm_live_xxxxxxxx'); $result = $rm->request->get(123);

Códigos de resposta

200 Tags

Exemplo de resposta

{ "data": { "resource_id": 42, "tags": [ "onboarding", "vip", "q2-2026" ] } }

Headers: X-Request-Id, X-RateLimit-Limit, X-RateLimit-Remaining

POST
/v1/campaigns/{id}/tags

Adiciona tags à campanha

O que faz

Adiciona tags à campanha. Aceita array de strings. Tags inexistentes são criadas. Idempotente — tags já presentes são ignoradas. Útil pra organizar campanhas por categoria (Q2-2026, black-friday, retencao, etc).

Parâmetros

path
id string obrigatório

Exemplo

curl -X POST 'https://api.ravimail.com.br/v1/campaigns/123/tags' \ -H 'Authorization: Bearer rvm_live_xxxxxxxx' \ -H 'Content-Type: application/json' \ -d '{ ... }'
// composer require ravisystems/ravimail-php use Ravimail\Client; $rm = new Client('rvm_live_xxxxxxxx'); $result = $rm->request->create([...]);

Códigos de resposta

200 Tags atuais

Exemplo de resposta

{ "data": { "resource_id": 42, "tags": [ "onboarding", "vip", "q2-2026", "novo" ] } }

Headers: X-Request-Id, X-RateLimit-Limit, X-RateLimit-Remaining

DELETE
/v1/campaigns/{id}/tags/{tag}

Remove tag da campanha

O que faz

Remove uma tag específica da campanha. Outras tags ficam intactas. Tag inexistente retorna 204 (idempotente).

Parâmetros

path
id string obrigatório
path
tag string obrigatório

Exemplo

curl -X DELETE 'https://api.ravimail.com.br/v1/campaigns/123/tags/onboarding' \ -H 'Authorization: Bearer rvm_live_xxxxxxxx'
// composer require ravisystems/ravimail-php use Ravimail\Client; $rm = new Client('rvm_live_xxxxxxxx'); $result = $rm->request->delete(123);

Códigos de resposta

204 Tag removida

Exemplo de resposta

# 204 No Content — body vazio HTTP/1.1 204 No Content X-Request-Id: req_a1b2c3d4e5f6
GET
/v1/lists/{id}/tags

Lista tags da lista

O que faz

Lista tags associadas à lista de contatos. Útil pra organizar listas por origem, projeto ou estágio do funil.

Parâmetros

path
id string obrigatório

Exemplo

curl 'https://api.ravimail.com.br/v1/lists/123/tags' \ -H 'Authorization: Bearer rvm_live_xxxxxxxx'
// composer require ravisystems/ravimail-php use Ravimail\Client; $rm = new Client('rvm_live_xxxxxxxx'); $result = $rm->request->get(123);

Códigos de resposta

200 Tags

Exemplo de resposta

{ "data": { "resource_id": 42, "tags": [ "onboarding", "vip", "q2-2026" ] } }

Headers: X-Request-Id, X-RateLimit-Limit, X-RateLimit-Remaining

POST
/v1/lists/{id}/tags

Adiciona tags à lista

O que faz

Adiciona tags à lista. Aceita array de strings. Idempotente. Use pra agrupar listas em dashboards (ex: tag 'cliente-acme' agrupa todas as listas de uma subaccount específica).

Parâmetros

path
id string obrigatório

Exemplo

curl -X POST 'https://api.ravimail.com.br/v1/lists/123/tags' \ -H 'Authorization: Bearer rvm_live_xxxxxxxx' \ -H 'Content-Type: application/json' \ -d '{ ... }'
// composer require ravisystems/ravimail-php use Ravimail\Client; $rm = new Client('rvm_live_xxxxxxxx'); $result = $rm->request->create([...]);

Códigos de resposta

200 Tags atuais

Exemplo de resposta

{ "data": { "resource_id": 42, "tags": [ "onboarding", "vip", "q2-2026", "novo" ] } }

Headers: X-Request-Id, X-RateLimit-Limit, X-RateLimit-Remaining

DELETE
/v1/lists/{id}/tags/{tag}

Remove tag da lista

O que faz

Remove uma tag da lista. Outras tags permanecem. Idempotente.

Parâmetros

path
id string obrigatório
path
tag string obrigatório

Exemplo

curl -X DELETE 'https://api.ravimail.com.br/v1/lists/123/tags/onboarding' \ -H 'Authorization: Bearer rvm_live_xxxxxxxx'
// composer require ravisystems/ravimail-php use Ravimail\Client; $rm = new Client('rvm_live_xxxxxxxx'); $result = $rm->request->delete(123);

Códigos de resposta

204 Tag removida

Exemplo de resposta

# 204 No Content — body vazio HTTP/1.1 204 No Content X-Request-Id: req_a1b2c3d4e5f6
GET
/v1/templates/{id}/tags

Lista tags do template

O que faz

Lista tags associadas ao template. Use pra categorizar templates (transactional/marketing/onboarding) e facilitar busca.

Parâmetros

path
id string obrigatório

Exemplo

curl 'https://api.ravimail.com.br/v1/templates/123/tags' \ -H 'Authorization: Bearer rvm_live_xxxxxxxx'
// composer require ravisystems/ravimail-php use Ravimail\Client; $rm = new Client('rvm_live_xxxxxxxx'); $result = $rm->request->get(123);

Códigos de resposta

200 Tags

Exemplo de resposta

{ "data": { "resource_id": 42, "tags": [ "onboarding", "vip", "q2-2026" ] } }

Headers: X-Request-Id, X-RateLimit-Limit, X-RateLimit-Remaining

POST
/v1/templates/{id}/tags

Adiciona tags ao template

O que faz

Adiciona tags ao template. Aceita array de strings. Idempotente. Útil pra busca rápida (ex: filtrar templates marcados como 'producao' vs 'rascunho').

Parâmetros

path
id string obrigatório

Exemplo

curl -X POST 'https://api.ravimail.com.br/v1/templates/123/tags' \ -H 'Authorization: Bearer rvm_live_xxxxxxxx' \ -H 'Content-Type: application/json' \ -d '{ ... }'
// composer require ravisystems/ravimail-php use Ravimail\Client; $rm = new Client('rvm_live_xxxxxxxx'); $result = $rm->request->create([...]);

Códigos de resposta

200 Tags atuais

Exemplo de resposta

{ "data": { "resource_id": 42, "tags": [ "onboarding", "vip", "q2-2026", "novo" ] } }

Headers: X-Request-Id, X-RateLimit-Limit, X-RateLimit-Remaining

DELETE
/v1/templates/{id}/tags/{tag}

Remove tag do template

O que faz

Remove uma tag do template. Outras tags permanecem. Idempotente.

Parâmetros

path
id string obrigatório
path
tag string obrigatório

Exemplo

curl -X DELETE 'https://api.ravimail.com.br/v1/templates/123/tags/onboarding' \ -H 'Authorization: Bearer rvm_live_xxxxxxxx'
// composer require ravisystems/ravimail-php use Ravimail\Client; $rm = new Client('rvm_live_xxxxxxxx'); $result = $rm->request->delete(123);

Códigos de resposta

204 Tag removida

Exemplo de resposta

# 204 No Content — body vazio HTTP/1.1 204 No Content X-Request-Id: req_a1b2c3d4e5f6

Templates

9 endpoints

GET
/v1/templates

Lista

O que faz

Lista templates HTML/texto do user. Cada template tem versionamento automático — só a versão atual aparece aqui; pra histórico veja /templates/{id}/versions.

Exemplo

curl 'https://api.ravimail.com.br/v1/templates' \ -H 'Authorization: Bearer rvm_live_xxxxxxxx'
// composer require ravisystems/ravimail-php use Ravimail\Client; $rm = new Client('rvm_live_xxxxxxxx'); $result = $rm->templates->list();

Códigos de resposta

200 Lista

Exemplo de resposta

{ "data": [ { "id": 17, "name": "Welcome", "current_version": 5 } ], "meta": { "has_more": true, "next_cursor": "eyJpZCI6MTAwMH0=" } }

Headers: X-Request-Id, X-RateLimit-Limit, X-RateLimit-Remaining

POST
/v1/templates

Cria

O que faz

Cria um novo template. Aceita `subject`, `html`, `text`, e variáveis no formato `{{nome_variavel}}` que serão substituídas no render. Cria automaticamente versão 1. Use POST /templates/{id}/render pra testar substituições antes de enviar.

Exemplo

curl -X POST 'https://api.ravimail.com.br/v1/templates' \ -H 'Authorization: Bearer rvm_live_xxxxxxxx' \ -H 'Content-Type: application/json' \ -d '{ ... }'
// composer require ravisystems/ravimail-php use Ravimail\Client; $rm = new Client('rvm_live_xxxxxxxx'); $result = $rm->templates->create([...]);

Códigos de resposta

201 Criado

Exemplo de resposta

{ "data": [ { "id": 17, "name": "Welcome", "current_version": 5 } ], "meta": { "has_more": true, "next_cursor": "eyJpZCI6MTAwMH0=" } }

Headers: X-Request-Id, X-RateLimit-Limit, X-RateLimit-Remaining

GET
/v1/templates/{id}

Show

O que faz

Detalhe do template: subject atual, body HTML/texto, lista de variáveis detectadas, versão atual e timestamp da última edição.

Parâmetros

path
id string obrigatório

Exemplo

curl 'https://api.ravimail.com.br/v1/templates/123' \ -H 'Authorization: Bearer rvm_live_xxxxxxxx'
// composer require ravisystems/ravimail-php use Ravimail\Client; $rm = new Client('rvm_live_xxxxxxxx'); $result = $rm->templates->get(123);

Códigos de resposta

200 Template

Exemplo de resposta

{ "data": { "id": 17, "name": "Welcome flow", "subject": "Bem-vindo, {{first_name}}!", "current_version": 5, "updated_at": "2026-05-18T11:20:00Z" } }

Headers: X-Request-Id, X-RateLimit-Limit, X-RateLimit-Remaining

PUT
/v1/templates/{id}

Update

O que faz

Atualiza o template criando uma nova versão automaticamente (histórico preservado). A versão anterior continua acessível em /versions/{N} pra rollback se necessário.

Parâmetros

path
id string obrigatório

Exemplo

curl -X PUT 'https://api.ravimail.com.br/v1/templates/123' \ -H 'Authorization: Bearer rvm_live_xxxxxxxx' \ -H 'Content-Type: application/json' \ -d '{ ... }'
// composer require ravisystems/ravimail-php use Ravimail\Client; $rm = new Client('rvm_live_xxxxxxxx'); $result = $rm->templates->update(123, [...]);

Códigos de resposta

200 Atualizado

Exemplo de resposta

{ "data": { "id": 17, "name": "Welcome flow", "subject": "Bem-vindo, {{first_name}}!", "current_version": 5, "updated_at": "2026-05-18T11:20:00Z" } }

Headers: X-Request-Id, X-RateLimit-Limit, X-RateLimit-Remaining

DELETE
/v1/templates/{id}

Delete

O que faz

Remove o template e todas as suas versões. Campanhas que usaram esse template ficam intactas (HTML enviado é independente do template após disparo). Drips com esse template como step ficam quebradas — verifique antes de remover.

Parâmetros

path
id string obrigatório

Exemplo

curl -X DELETE 'https://api.ravimail.com.br/v1/templates/123' \ -H 'Authorization: Bearer rvm_live_xxxxxxxx'
// composer require ravisystems/ravimail-php use Ravimail\Client; $rm = new Client('rvm_live_xxxxxxxx'); $result = $rm->templates->delete(123);

Códigos de resposta

204 Removido

Exemplo de resposta

# 204 No Content — body vazio HTTP/1.1 204 No Content X-Request-Id: req_a1b2c3d4e5f6
POST
/v1/templates/{id}/render

Render com variáveis

O que faz

Renderiza o template substituindo as variáveis no body do request (ex: `{ first_name: 'Maria', order_id: 1234 }`). Retorna HTML + texto plano + subject finais — exatamente o que seria enviado se você chamasse /transactional/send. Útil pra preview antes de enviar, debugging de variáveis faltantes, ou pra gerar HTML pra renderização interna.

Parâmetros

path
id string obrigatório

Exemplo

curl -X POST 'https://api.ravimail.com.br/v1/templates/123/render' \ -H 'Authorization: Bearer rvm_live_xxxxxxxx' \ -H 'Content-Type: application/json' \ -d '{ ... }'
// composer require ravisystems/ravimail-php use Ravimail\Client; $rm = new Client('rvm_live_xxxxxxxx'); $result = $rm->templates->create([...]);

Códigos de resposta

200 HTML/texto renderizado

Exemplo de resposta

{ "data": { "html": "<h1>Olá Maria</h1><p>Seu pedido #1234 foi confirmado.</p>", "text": "Olá Maria. Seu pedido #1234 foi confirmado.", "subject": "Pedido #1234 confirmado" } }

Headers: X-Request-Id, X-RateLimit-Limit, X-RateLimit-Remaining

GET
/v1/templates/{id}/versions

Lista versões

O que faz

Lista todas as versões salvas do template (cada PUT cria uma nova versão automaticamente). Cada item: number, autor, timestamp, status (current/archived). Use pra auditoria ou comparação entre versões.

Parâmetros

path
id string obrigatório

Exemplo

curl 'https://api.ravimail.com.br/v1/templates/123/versions' \ -H 'Authorization: Bearer rvm_live_xxxxxxxx'
// composer require ravisystems/ravimail-php use Ravimail\Client; $rm = new Client('rvm_live_xxxxxxxx'); $result = $rm->templates->get(123);

Códigos de resposta

200 Versões

Exemplo de resposta

{ "data": [ { "id": 17, "version": 5, "created_at": "2026-05-18T11:20:00Z" } ], "meta": { "has_more": true, "next_cursor": "eyJpZCI6MTAwMH0=" } }

Headers: X-Request-Id, X-RateLimit-Limit, X-RateLimit-Remaining

GET
/v1/templates/{id}/versions/{version}

Versão específica

O que faz

Conteúdo completo de uma versão específica (HTML, texto, subject). Use pra exibir histórico ou diff visual entre versões antes de rollback.

Parâmetros

path
id string obrigatório

Exemplo

curl 'https://api.ravimail.com.br/v1/templates/123/versions/3' \ -H 'Authorization: Bearer rvm_live_xxxxxxxx'
// composer require ravisystems/ravimail-php use Ravimail\Client; $rm = new Client('rvm_live_xxxxxxxx'); $result = $rm->templates->get(123);

Códigos de resposta

200 Versão

Exemplo de resposta

{ "data": { "id": 17, "version": 3, "subject": "Bem-vindo!", "created_at": "2026-05-19T14:30:00Z", "author": "rodrigo@ravimail.com.br" } }

Headers: X-Request-Id, X-RateLimit-Limit, X-RateLimit-Remaining

POST
/v1/templates/{id}/versions/{version}/rollback

Rollback pra versão N

O que faz

Faz rollback do template pra uma versão anterior, criando uma NOVA versão (não destrutivo) com o conteúdo da especificada. Útil quando você publica uma versão com bug e precisa voltar rápido — mais seguro que editar manualmente porque mantém histórico de quem rollback-eou quando.

Parâmetros

path
id string obrigatório

Exemplo

curl -X POST 'https://api.ravimail.com.br/v1/templates/123/versions/3/rollback' \ -H 'Authorization: Bearer rvm_live_xxxxxxxx' \ -H 'Content-Type: application/json' \ -d '{ ... }'
// composer require ravisystems/ravimail-php use Ravimail\Client; $rm = new Client('rvm_live_xxxxxxxx'); $result = $rm->templates->create([...]);

Códigos de resposta

200 Novo current_version

Exemplo de resposta

{ "data": [ { "id": 17, "version": 5, "created_at": "2026-05-18T11:20:00Z" } ], "meta": { "has_more": true, "next_cursor": "eyJpZCI6MTAwMH0=" } }

Headers: X-Request-Id, X-RateLimit-Limit, X-RateLimit-Remaining

Transactional

4 endpoints

POST
/v1/transactional/send

Enviar email transacional

O que faz

Envia um email 1-a-1 (notificação, recibo, recuperação de senha, confirmação). Aceita HTML, texto plano ou ambos. Anexos via `file_ids` (faça upload prévio em POST /v1/files). Use header `Idempotency-Key` pra prevenir envios duplicados em retries do seu lado.

Roteamento automático escolhe o melhor IP/domínio. Pra forçar, passe `route.domain_id` ou `route.ip_id`. Para testes determinísticos, envie pra qualquer endereço @simulator.ravimail.com.br (success/bounce/complaint/suppress/opened/clicked).

Parâmetros

header
Idempotency-Key string

Request body

Content-Type: application/json obrigatório
Schema: TransactionalSend

Exemplo

curl -X POST 'https://api.ravimail.com.br/v1/transactional/send' \ -H 'Authorization: Bearer rvm_live_xxxxxxxx' \ -H 'Content-Type: application/json' \ -d '{ /* TransactionalSend */ }'
// composer require ravisystems/ravimail-php use Ravimail\Client; $rm = new Client('rvm_live_xxxxxxxx'); $result = $rm->transactional->send(['to' => '...', 'subject' => '...']);

Códigos de resposta

202 Aceito + message_id
422 Erro RFC 7807
402 Saldo insuficiente

Exemplo de resposta

{ "data": { "message_id": "msg_8f3a2b1c4d5e6f", "status": "queued", "to": "joao@empresa.com.br", "subject": "Bem-vindo!", "created_at": "2026-05-19T14:30:00Z" } }

Headers: X-Request-Id, X-RateLimit-Limit, X-RateLimit-Remaining

POST
/v1/transactional/batch

Batch até 1000 mensagens

O que faz

Envia até 1000 emails distintos em uma única chamada. Cada item do array pode ter destinatário, subject e variáveis próprias. Retorna `207 Multi-Status` com resultado individual por mensagem (alguns podem ser aceitos e outros rejeitados na mesma chamada). Ideal pra notificações em lote sem precisar usar campanhas.

Exemplo

curl -X POST 'https://api.ravimail.com.br/v1/transactional/batch' \ -H 'Authorization: Bearer rvm_live_xxxxxxxx' \ -H 'Content-Type: application/json' \ -d '{ ... }'
// composer require ravisystems/ravimail-php use Ravimail\Client; $rm = new Client('rvm_live_xxxxxxxx'); $result = $rm->transactional->create([...]);

Códigos de resposta

207 Multi-status

Exemplo de resposta

{ "data": { "batch_id": "bat_xy12", "accepted": 998, "rejected": 2, "results": [ { "status": 202, "message_id": "msg_aaa111", "to": "a@empresa.com" }, { "status": 422, "error": "invalid_email", "to": "naoeemail" } ] } }

Headers: X-Request-Id, X-RateLimit-Limit, X-RateLimit-Remaining

GET
/v1/transactional/messages

Lista mensagens (cursor)

O que faz

Lista mensagens transacionais enviadas via API com paginação cursor-based (sem `offset` lento). Filtros: `status` (queued/sent/delivered/bounced/failed), `to` (destinatário exato), `cursor` + `limit`. Resultado ordenado por data de envio descendente. Inclui campos resumidos — pra timeline completa use GET /messages/{id}.

Parâmetros

query
cursor string
query
limit string
query
status string
query
to string

Exemplo

curl 'https://api.ravimail.com.br/v1/transactional/messages?cursor=valor&limit=valor' \ -H 'Authorization: Bearer rvm_live_xxxxxxxx'
// composer require ravisystems/ravimail-php use Ravimail\Client; $rm = new Client('rvm_live_xxxxxxxx'); $result = $rm->transactional->list();

Códigos de resposta

200 Lista paginada

Exemplo de resposta

{ "data": [ { "id": "msg_aaa", "to": "a@b.com", "subject": "Bem-vindo!", "status": "delivered", "sent_at": "2026-05-19T14:30:00Z" } ], "meta": { "has_more": true, "next_cursor": "eyJpZCI6MTAwMH0=" } }

Headers: X-Request-Id, X-RateLimit-Limit, X-RateLimit-Remaining

GET
/v1/transactional/messages/{id}

Detalhe da mensagem + timeline

O que faz

Retorna detalhe completo de uma mensagem específica: payload original, headers SMTP, IP usado, resposta do MTA destino, e timeline de eventos (queued → sent → delivered → opened → clicked → bounced/complained). Use pra debugar problemas de entrega individuais ou exibir status pro user final.

Parâmetros

path
id string obrigatório

Exemplo

curl 'https://api.ravimail.com.br/v1/transactional/messages/123' \ -H 'Authorization: Bearer rvm_live_xxxxxxxx'
// composer require ravisystems/ravimail-php use Ravimail\Client; $rm = new Client('rvm_live_xxxxxxxx'); $result = $rm->transactional->get(123);

Códigos de resposta

200 Detalhe

Exemplo de resposta

{ "data": { "id": "msg_8f3a2b1c4d5e6f", "status": "delivered", "to": "joao@empresa.com.br", "from": "voce@seudominio.com.br", "subject": "Bem-vindo!", "sent_at": "2026-05-19T14:30:00Z", "delivered_at": "2026-05-19T14:30:08Z", "timeline": [ { "event": "queued", "at": "2026-05-19T14:30:00Z" }, { "event": "sent", "at": "2026-05-19T14:30:02Z", "ip": "203.0.113.10" }, { "event": "delivered", "at": "2026-05-19T14:30:08Z", "mta_response": "250 2.0.0 OK" }, { "event": "opened", "at": "2026-05-19T14:31:42Z" } ] } }

Headers: X-Request-Id, X-RateLimit-Limit, X-RateLimit-Remaining

Verification

2 endpoints

GET
/v1/verify/email

Verifica email (sintaxe+MX+disposable+role)

O que faz

Valida um único endereço de email em 4 camadas: sintaxe RFC 5322, existência de registros MX no domínio, detecção de domínio descartável (mailinator, tempmail, etc) e detecção de role-based (info@, sales@, noreply@). Retorna verdict (valid/risky/invalid) + breakdown por check. Use em formulários de cadastro pra reduzir entrada de emails inválidos.

Exemplo

curl 'https://api.ravimail.com.br/v1/verify/email' \ -H 'Authorization: Bearer rvm_live_xxxxxxxx'
// composer require ravisystems/ravimail-php use Ravimail\Client; $rm = new Client('rvm_live_xxxxxxxx'); $result = $rm->verification->list();

Códigos de resposta

200 Resultado

Exemplo de resposta

{ "data": { "email": "usuario@dominio.com", "verdict": "valid", "checks": { "syntax": "ok", "mx": "ok", "disposable": false, "role_based": false }, "score": 95 } }

Headers: X-Request-Id, X-RateLimit-Limit, X-RateLimit-Remaining

POST
/v1/verify/batch

Verifica em lote (até 100 emails)

O que faz

Valida até 100 emails em uma chamada — mesma lógica do endpoint single mas em paralelo. Útil antes de importar listas grandes (faça batches de 100 e descarte os inválidos). Resultado por email no array de retorno. Não consome quota de envio, apenas créditos de verificação.

Exemplo

curl -X POST 'https://api.ravimail.com.br/v1/verify/batch' \ -H 'Authorization: Bearer rvm_live_xxxxxxxx' \ -H 'Content-Type: application/json' \ -d '{ ... }'
// composer require ravisystems/ravimail-php use Ravimail\Client; $rm = new Client('rvm_live_xxxxxxxx'); $result = $rm->verification->create([...]);

Códigos de resposta

200 Resultado batch

Exemplo de resposta

{ "data": { "total": 100, "valid": 78, "risky": 14, "invalid": 8, "results": [ { "email": "a@b.com", "verdict": "valid" }, { "email": "c@d.com", "verdict": "invalid", "reason": "no_mx_record" } ] } }

Headers: X-Request-Id, X-RateLimit-Limit, X-RateLimit-Remaining

Webhooks

9 endpoints

GET
/v1/webhooks/endpoints

Lista endpoints

O que faz

Lista todos os endpoints webhook configurados pelo user. Cada item retorna URL alvo, eventos inscritos, status (active/disabled) e timestamp da última delivery bem-sucedida. O `signing_secret` NÃO é exposto aqui — só é retornado uma vez no momento da criação.

Exemplo

curl 'https://api.ravimail.com.br/v1/webhooks/endpoints' \ -H 'Authorization: Bearer rvm_live_xxxxxxxx'
// composer require ravisystems/ravimail-php use Ravimail\Client; $rm = new Client('rvm_live_xxxxxxxx'); $result = $rm->webhooks->list();

Códigos de resposta

200 Lista

Exemplo de resposta

{ "data": [ { "id": "whe_abc123", "url": "https://app.cliente.com/webhooks/ravimail", "events": [ "delivered" ], "status": "active" } ], "meta": { "has_more": true, "next_cursor": "eyJpZCI6MTAwMH0=" } }

Headers: X-Request-Id, X-RateLimit-Limit, X-RateLimit-Remaining

POST
/v1/webhooks/endpoints

Cria endpoint (secret retornado uma vez)

O que faz

Cria um endpoint webhook que receberá HTTP POST sempre que um dos eventos inscritos ocorrer. **IMPORTANTE:** o `signing_secret` retornado na resposta é mostrado apenas uma vez — copie e guarde com segurança. Use-o pra validar a assinatura HMAC SHA-256 vinda no header `X-Ravimail-Signature` em cada delivery. Retries automáticos com backoff exponencial em falhas (até 24h).

Request body

Content-Type: application/json obrigatório
Schema: WebhookEndpoint

Exemplo

curl -X POST 'https://api.ravimail.com.br/v1/webhooks/endpoints' \ -H 'Authorization: Bearer rvm_live_xxxxxxxx' \ -H 'Content-Type: application/json' \ -d '{ /* WebhookEndpoint */ }'
// composer require ravisystems/ravimail-php use Ravimail\Client; $rm = new Client('rvm_live_xxxxxxxx'); $result = $rm->webhooks->create([...]);

Códigos de resposta

201 Criado

Exemplo de resposta

{ "data": [ { "id": "whe_abc123", "url": "https://app.cliente.com/webhooks/ravimail", "events": [ "delivered" ], "status": "active" } ], "meta": { "has_more": true, "next_cursor": "eyJpZCI6MTAwMH0=" } }

Headers: X-Request-Id, X-RateLimit-Limit, X-RateLimit-Remaining

GET
/v1/webhooks/endpoints/{id}

Show

O que faz

Detalhe de um endpoint webhook específico: URL configurada, eventos inscritos, timestamps, status. O `signing_secret` NÃO é retornado (security) — só pode ser obtido na criação ou via rotate.

Parâmetros

path
id string obrigatório

Exemplo

curl 'https://api.ravimail.com.br/v1/webhooks/endpoints/123' \ -H 'Authorization: Bearer rvm_live_xxxxxxxx'
// composer require ravisystems/ravimail-php use Ravimail\Client; $rm = new Client('rvm_live_xxxxxxxx'); $result = $rm->webhooks->get(123);

Códigos de resposta

200 Endpoint

Exemplo de resposta

{ "data": { "id": "whe_abc123", "url": "https://app.cliente.com/webhooks/ravimail", "events": [ "delivered", "bounced", "complained" ], "status": "active", "created_at": "2026-05-10T09:15:00Z", "last_delivery_at": "2026-05-19T14:29:55Z" } }

Headers: X-Request-Id, X-RateLimit-Limit, X-RateLimit-Remaining

PUT
/v1/webhooks/endpoints/{id}

Update

O que faz

Atualiza configuração do endpoint (URL, lista de eventos, status active/disabled). Não regenera signing secret — use /rotate-secret pra isso. Útil pra alterar o handler sem perder histórico de deliveries.

Parâmetros

path
id string obrigatório

Exemplo

curl -X PUT 'https://api.ravimail.com.br/v1/webhooks/endpoints/123' \ -H 'Authorization: Bearer rvm_live_xxxxxxxx' \ -H 'Content-Type: application/json' \ -d '{ ... }'
// composer require ravisystems/ravimail-php use Ravimail\Client; $rm = new Client('rvm_live_xxxxxxxx'); $result = $rm->webhooks->update(123, [...]);

Códigos de resposta

200 Atualizado

Exemplo de resposta

{ "data": { "id": "whe_abc123", "url": "https://app.cliente.com/webhooks/ravimail", "events": [ "delivered", "bounced", "complained" ], "status": "active", "created_at": "2026-05-10T09:15:00Z", "last_delivery_at": "2026-05-19T14:29:55Z" } }

Headers: X-Request-Id, X-RateLimit-Limit, X-RateLimit-Remaining

DELETE
/v1/webhooks/endpoints/{id}

Delete

O que faz

Remove o endpoint permanentemente. Eventos futuros que combinariam não serão entregues. Deliveries históricas ficam no log pra auditoria. **Irreversível** — re-criar gera novo signing_secret.

Parâmetros

path
id string obrigatório

Exemplo

curl -X DELETE 'https://api.ravimail.com.br/v1/webhooks/endpoints/123' \ -H 'Authorization: Bearer rvm_live_xxxxxxxx'
// composer require ravisystems/ravimail-php use Ravimail\Client; $rm = new Client('rvm_live_xxxxxxxx'); $result = $rm->webhooks->delete(123);

Códigos de resposta

204 Removido

Exemplo de resposta

# 204 No Content — body vazio HTTP/1.1 204 No Content X-Request-Id: req_a1b2c3d4e5f6
POST
/v1/webhooks/endpoints/{id}/test

Dispara evento sintético

O que faz

Envia um evento de teste pra URL do endpoint sem precisar gerar um evento real. Útil pra validar a configuração de handler do seu lado, verificar assinatura HMAC, testar parsing do payload e confirmar que o endpoint responde 2xx dentro do timeout. O evento sintético tem `event=test` e payload mínimo.

Parâmetros

path
id string obrigatório

Exemplo

curl -X POST 'https://api.ravimail.com.br/v1/webhooks/endpoints/123/test' \ -H 'Authorization: Bearer rvm_live_xxxxxxxx' \ -H 'Content-Type: application/json' \ -d '{ ... }'
// composer require ravisystems/ravimail-php use Ravimail\Client; $rm = new Client('rvm_live_xxxxxxxx'); $result = $rm->webhooks->create([...]);

Códigos de resposta

202 Queued

Exemplo de resposta

{ "data": [ { "id": "whe_abc123", "url": "https://app.cliente.com/webhooks/ravimail", "events": [ "delivered" ], "status": "active" } ], "meta": { "has_more": true, "next_cursor": "eyJpZCI6MTAwMH0=" } }

Headers: X-Request-Id, X-RateLimit-Limit, X-RateLimit-Remaining

GET
/v1/webhooks/deliveries

Lista deliveries (filtros: endpoint_id, status)

O que faz

Log de todas as tentativas de delivery de webhook. Cada item mostra: payload enviado, response status do seu servidor, latência, tentativa atual (1-5) e timestamp. Filtros: `endpoint_id`, `status` (success/failed/pending). Use pra debugar receivers quebrados ou auditar entregas históricas.

Parâmetros

query
endpoint_id string
query
status string
query
cursor string
query
limit string

Exemplo

curl 'https://api.ravimail.com.br/v1/webhooks/deliveries?endpoint_id=valor&status=valor' \ -H 'Authorization: Bearer rvm_live_xxxxxxxx'
// composer require ravisystems/ravimail-php use Ravimail\Client; $rm = new Client('rvm_live_xxxxxxxx'); $result = $rm->webhooks->list();

Códigos de resposta

200 Lista

Exemplo de resposta

{ "data": [ { "id": "whd_99001", "endpoint_id": "whe_abc123", "event": "delivered", "status": "success", "http_status": 200, "latency_ms": 187 } ], "meta": { "has_more": true, "next_cursor": "eyJpZCI6MTAwMH0=" } }

Headers: X-Request-Id, X-RateLimit-Limit, X-RateLimit-Remaining

POST
/v1/webhooks/deliveries/{id}/replay

Re-enfileira delivery

O que faz

Reenfileira uma delivery específica pra ser entregue novamente. Usado quando seu handler estava temporariamente fora do ar e o retry automático já esgotou — você precisa receber o evento de novo manualmente. Resultado vai gerar um novo `delivery_id` no log mantendo o original como histórico.

Parâmetros

path
id string obrigatório

Exemplo

curl -X POST 'https://api.ravimail.com.br/v1/webhooks/deliveries/123/replay' \ -H 'Authorization: Bearer rvm_live_xxxxxxxx' \ -H 'Content-Type: application/json' \ -d '{ ... }'
// composer require ravisystems/ravimail-php use Ravimail\Client; $rm = new Client('rvm_live_xxxxxxxx'); $result = $rm->webhooks->create([...]);

Códigos de resposta

202 Replay queued

Exemplo de resposta

{ "data": [ { "id": "whd_99001", "endpoint_id": "whe_abc123", "event": "delivered", "status": "success", "http_status": 200, "latency_ms": 187 } ], "meta": { "has_more": true, "next_cursor": "eyJpZCI6MTAwMH0=" } }

Headers: X-Request-Id, X-RateLimit-Limit, X-RateLimit-Remaining

POST
/v1/webhooks/endpoints/{id}/rotate-secret

Rotaciona signing_secret (mantém antigo 24h)

O que faz

Gera um novo `signing_secret` pro endpoint e retorna o valor uma única vez. Por uma janela de 24h, **ambos os secrets** (antigo + novo) são aceitos como assinaturas válidas — isso permite você atualizar o secret no seu handler sem perder eventos. Use periodicamente (3-6 meses) ou imediatamente se suspeitar de vazamento do secret atual.

Parâmetros

path
id string obrigatório

Exemplo

curl -X POST 'https://api.ravimail.com.br/v1/webhooks/endpoints/123/rotate-secret' \ -H 'Authorization: Bearer rvm_live_xxxxxxxx' \ -H 'Content-Type: application/json' \ -d '{ ... }'
// composer require ravisystems/ravimail-php use Ravimail\Client; $rm = new Client('rvm_live_xxxxxxxx'); $result = $rm->webhooks->create([...]);

Códigos de resposta

200 Novo secret

Exemplo de resposta

{ "data": { "id": "whe_abc123", "signing_secret": "whsec_NEW_K7s9aB...", "previous_secret_valid_until": "2026-05-20T14:30:00Z" } }

Headers: X-Request-Id, X-RateLimit-Limit, X-RateLimit-Remaining

Pronto pra construir?

Crie sua conta, gere um token sandbox e teste qualquer endpoint sem custo.

Criar conta gratuita Ver guia do desenvolvedor