Para desenvolvedores

Integre email, CRM e WhatsApp
em uma única API REST

155 endpoints documentados em OpenAPI 3.0, SDK PHP oficial, webhooks com HMAC, event stream SSE, sandbox per-token e SMTP relay. Tudo o que você precisa pra construir produto em cima do RaviMail.

Gerar token API gratuito Ver documentação

155

Endpoints /v1/*

40+

Scopes granulares

SDK

PHP oficial

SSE

Event stream

# Primeiro envio em 1 request
curl -X POST https://api.ravimail.com.br/v1/transactional/send \
  -H "Authorization: Bearer rvm_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "to": "joao@empresa.com.br",
    "from": "voce@seudominio.com.br",
    "subject": "Bem-vindo!",
    "html": "<h1>Olá João</h1>",
    "tags": ["onboarding"]
  }'

# Resposta
{ "data": { "message_id": "msg_abc123", "status": "sent" } }

// composer require ravisystems/ravimail-php
use Ravimail\Client;

$rm = new Client('rvm_live_...');

$rm->transactional->send([
    'to'      => 'joao@empresa.com.br',
    'from'    => 'voce@seudominio.com.br',
    'subject' => 'Bem-vindo!',
    'html'    => '<h1>Olá João</h1>',
    'tags'    => ['onboarding'],
]);

// Qualquer cliente HTTP — fetch nativo aqui
await fetch('https://api.ravimail.com.br/v1/transactional/send', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer rvm_live_...',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    to: 'joao@empresa.com.br',
    from: 'voce@seudominio.com.br',
    subject: 'Bem-vindo!',
    html: '<h1>Olá João</h1>',
    tags: ['onboarding']
  })
});

import requests

requests.post(
    'https://api.ravimail.com.br/v1/transactional/send',
    headers={'Authorization': 'Bearer rvm_live_...'},
    json={
        'to': 'joao@empresa.com.br',
        'from': 'voce@seudominio.com.br',
        'subject': 'Bem-vindo!',
        'html': '<h1>Olá João</h1>',
        'tags': ['onboarding'],
    }
)

SDKs Node.js e Python via REST direto. SDKs nativos no roadmap →

Onboarding rápido

Do zero ao primeiro envio em 5 minutos

Três passos. Sem cartão de crédito pra começar. Sandbox grátis pra testar antes de ir pra produção.

Crie sua conta

Cadastro em 30 segundos. Sandbox liberado automaticamente — gere quantos tokens rvm_test_* quiser pra testar sem afetar produção nem ser cobrado.

Criar conta agora

Gere um token

No painel, vá em Desenvolvedores → Tokens, selecione os scopes (40+ disponíveis, princípio de menor privilégio), opcional limite por IP e expiração.

rvm_test_abc123... // sandbox
rvm_live_xyz789... // produção

Faça o primeiro request

Use o snippet do hero acima — curl, PHP, Node ou Python. Resposta em JSON com message_id e status. Em sandbox, retorna msg_sandbox_* sem envio real.

Ver guia completo

155 endpoints organizados

Tudo via REST. Tudo documentado.

18 grupos de recursos, do envio transacional ao funil de vendas. OpenAPI 3.0 spec + Swagger UI dentro do painel.

Ver referência completa dos 155 endpoints

Transacional

Envio 1-a-1, batch, agendamento. Anexos via upload de arquivos.

POST /v1/transactional/send · POST /v1/transactional/batch

Campanhas

CRUD + start/pause/resume/cancel/duplicate. A/B testing nativo.

GET POST PUT DELETE /v1/campaigns · /v1/campaigns/{id}/{start|pause|resume|cancel}

Drip campaigns

Sequências automatizadas com steps, gatilhos e condições.

/v1/drips · /v1/drips/{id}/steps · /v1/drips/{id}/subscribe

Contatos & Listas

CRUD, tags, supressão, bulk import via CSV/JSON, custom fields.

/v1/contacts · /v1/lists · /v1/contacts/{id}/{suppress|tag}

Segmentos dinâmicos

Definição declarativa de regras + computação on-demand.

/v1/segments · /v1/segments/{id}/compute

Templates

CRUD com versionamento, preview de render e variáveis.

/v1/templates · /v1/templates/{id}/render · /v1/templates/{id}/versions

Verification

Email check (DNS + MX + disposable + role). Batch async.

/v1/verification/email · /v1/verification/batch

Domínios

Add, verify DKIM/SPF/DMARC, upgrade pra dashboard de reputação.

/v1/domains · /v1/domains/{id}/verify

Analytics

Summary, timeseries, by-domain/ip/node/isp/device/country/heatmap.

/v1/analytics/{summary|timeseries|by-*|heatmap}

Webhooks

HTTP push HMAC SHA-256/512, retries com backoff, rotate secret.

/v1/webhooks · /v1/webhooks/{id}/deliveries · /rotate-secret

Events (SSE)

Stream de eventos em tempo real (delivered, opened, clicked, bounced).

GET /v1/events · GET /v1/events/stream

Subaccounts

Multi-tenant pra agências/SaaS. Isolamento de tokens e métricas.

/v1/subaccounts · token isolation por escopo

IP Pools

Criar pools, agrupar IPs, forçar pool por token ou campanha.

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

Mailbox Simulator

Endereços especiais que retornam bounce, complaint, suppression, etc.

success@simulator.ravimail.com.br · bounce@... · complaint@...

Reputation

Score por domínio/IP/nó + breakdown + blacklist report.

/v1/reputation/{domain|ip|node}/{id} · /v1/reputation/blacklists

Inbound Routes

Regras de parsing inbound → forward via webhook.

/v1/inbound-routes · pattern matching + webhook target

Exports

Jobs CSV async pra contatos, eventos, métricas.

/v1/exports · /v1/exports/{id}/status · /v1/exports/{id}/download

Files & Tags

Upload de anexos, tags genéricas em qualquer recurso.

/v1/files · /v1/{resource}/{id}/tags

Auth & Segurança

Bearer tokens com controle granular

Hash SHA-256 server-side, scopes granulares (40+), IP whitelist em CIDR, expiração configurável e rotação sem downtime. Auditoria completa em logs estruturados.

40+ scopes granulares

contacts:read, campaigns:write, webhooks:admin, sandbox:trigger…
IP whitelist por token

Lista CIDR (192.168.0.0/24) ou IPs individuais. Bloqueia fora da allowlist.
Sandbox per-token

Token rvm_test_* não envia email real, não cobra créditos, não aparece nos relatórios live.
Rotação sem downtime

Edite scopes/IPs em produção. Revogue ou regenere a qualquer momento.

# Header obrigatório em todos os endpoints /v1/*
Authorization: Bearer rvm_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

# Erros padronizados
401  → token inválido / revogado
403  → scope insuficiente / IP fora da allowlist
422  → payload inválido (campos faltando/inválidos)
429  → rate limit (header Retry-After)
5xx  → erro interno (retry com backoff exponencial)

# Estrutura de erro
{
  "error": {
    "code": "validation_failed",
    "message": "Field 'to' is required",
    "field": "to"
  }
}

Eventos em tempo real

Webhooks HMAC ou Event Stream SSE

Receba delivered, opened, clicked, bounced, complained, unsubscribed em tempo real.

Webhooks HTTP Push

Para ambientes serverless ou que não mantém conexão aberta

Assinatura HMAC SHA-256/512 em header
Retry automático com backoff exponencial
Rotação de signing secret sem downtime
Filtro por tipo de evento
Log de deliveries com replay manual

# Verificação da assinatura (PHP)
$sig   = $_SERVER['HTTP_X_RAVIMAIL_SIGNATURE'];
$body  = file_get_contents('php://input');
$valid = hash_equals(
    'sha256=' . hash_hmac('sha256', $body, $secret),
    $sig
);

Event Stream SSE

Para dashboards reativos, observabilidade ao vivo

Server-Sent Events nativos (EventSource)
Filtro por tipo, domínio, campanha, IP
Sem polling — push assim que evento ocorre
Reconexão automática com last-event-id
Mesma auth Bearer dos endpoints REST

# Consumir o stream (Node.js)
const es = new EventSource(
  'https://api.ravimail.com.br/v1/events/stream',
  { headers: { 'Authorization': 'Bearer rvm_live_...' } }
);
es.onmessage = (e) => {
  console.log(JSON.parse(e.data));
};

# Endereços especiais que retornam cenários reais
success@simulator.ravimail.com.br     # delivered
bounce@simulator.ravimail.com.br      # hard bounce
soft-bounce@simulator.ravimail.com.br # soft bounce + retry
complaint@simulator.ravimail.com.br   # marca como spam
suppress@simulator.ravimail.com.br    # vai pra supressão
opened@simulator.ravimail.com.br      # delivered + open evento
clicked@simulator.ravimail.com.br     # delivered + open + click

# Trigger manual de eventos via API
curl -X POST https://api.ravimail.com.br/v1/sandbox/trigger-event \
  -H "Authorization: Bearer rvm_test_..." \
  -d '{"message_id":"msg_sandbox_abc","event":"bounced"}'

Sandbox & Testes

Teste tudo antes de ir pra produção

Sandbox isolado do ambiente live: nada é enviado de verdade, nada cobra crédito, nada aparece em relatórios reais. Combine com o Mailbox Simulator pra reproduzir bounces, complaints, supressões e clicks deterministicamente.

Custo de testes em sandbox

Endereços simulator pré-definidos

100%

Determinístico (cenário garantido)

Pronto pra integration tests

SDK PHP oficial

ravisystems/ravimail-php

Client tipado, PSR-4, exceções específicas (Validation/RateLimit/Auth), suporte completo aos 18 grupos de recursos.

# Instalação
composer require ravisystems/ravimail-php

# Exceções tipadas
use Ravimail\Exception\{
    ValidationException,
    RateLimitException,
    AuthenticationException,
    ApiException
};

SMTP Relay

smtp.ravimail.com.br:587

Sistemas legados que falam SMTP (PHPMailer, Nodemailer, smtplib, WordPress) podem usar diretamente — autenticação SASL via mesmo token API.

# Credenciais de autenticação
Host:     smtp.ravimail.com.br
Porta:    587 (STARTTLS) ou 465 (TLS)
User:     api
Senha:    rvm_live_xxxxxxxxxxxxxxxxxxxxxxxx
Auth:     PLAIN ou LOGIN

Perguntas frequentes

Dúvidas comuns de quem está integrando.

Configurável por token. Padrão é compatível com o plano contratado. Resposta 429 inclui header Retry-After. Burst e janela móvel são documentados em /docs.

Sim. Tokens rvm_live_* e rvm_test_* coexistem na mesma conta. Sandbox é totalmente isolado — não cobra créditos, não envia email real, não aparece em métricas live.

Sim. Cada token aceita allowlist em formato CIDR (10.0.0.0/24) ou IPs individuais. Requests de IPs fora retornam 403 e ficam logados.

No painel ou via POST /v1/webhooks/{id}/rotate-secret. Por uma janela curta, ambos os secrets são aceitos pra você atualizar seu handler.

PHP oficial está publicado. Para outras linguagens, a API REST é trivial de consumir com qualquer client HTTP (exemplos acima). SDKs nativos estão no roadmap — entre em contato pra priorizar uma linguagem.

Sim — endereços @simulator.ravimail.com.br são reconhecidos em qualquer modo. Útil pra testar handlers de webhook em produção sem afetar reputação.

User fixo api, senha = seu token API (live ou test). SASL PLAIN ou LOGIN. Funciona com qualquer cliente SMTP padrão — PHPMailer, Nodemailer, smtplib, WP Mail SMTP, etc.

Sim. Endpoint /v1/subaccounts cria subcontas com tokens isolados, métricas separadas e supressão independente. Ideal pra agências e SaaS revendendo email.

Comece a integrar agora.

Crie sua conta gratuita, gere um token sandbox e faça o primeiro envio em minutos. Sem cartão de crédito.

Criar conta gratuita Ler documentação

Integre email, CRM e WhatsApp em uma única API REST