Tokens de API

Este guia acompanha a tela Tokens de API do painel (Integrações → Tokens de API).

Para que serve

Gerar um token secreto para o seu CRM ou sistema externo cadastrar/atualizar contatos e enviar e-mails avulsos via API — sem usar o login do painel. Na mesma tela você também vê o histórico Envios pela API (aceitos, na fila ou com falha).

O que você vai fazer

1. Abrir Integrações → Tokens de API.
2. Clicar em Criar token e dar um nome (ex.: “Integração RD Station”).
3. Copiar o token imediatamente — por segurança ele não aparece de novo.
4. No seu sistema, enviar o cabeçalho Authorization: Bearer seguido do token.
5. Se o token vazar ou deixar de ser usado, clique em Revogar.
6. Para conferir falhas ou reenviar: role até Envios pela API (ou abra o alerta do dashboard).

Envios pela API

Abaixo da lista de tokens aparece o histórico dos e-mails avulsos aceitos via POST /messages (não são campanhas do painel).

• Filtre por status (ex.: Falhou), por token (nome do CRM) ou use o link do dashboard.
• Abra o detalhe para ver o motivo e, se fizer sentido, Tentar de novo.
• Exporte CSV se precisar analisar fora do painel.
• Se o cliente responde ao e-mail e a resposta não chega: no Setup de envio, configure Responder para (ou envie reply_to no body da API). O remetente (From) no domínio de envio muitas vezes não é uma caixa real.

Fila e status pending

Depois do POST /messages a API responde 202 com status: pending. O envio real é em background.

• Em geral vira sent em poucos segundos até cerca de 1–2 minutos.
• Se o CRM alertar em 90 segundos, trate como aviso soft (ainda pode estar na fila).
• Só trate como incidente de plataforma se continuar pending por cerca de 5 minutos — aí use Tokens de API → Envios pela API ou fale com o suporte (leve o horário e, se houver erro 500, o error.request_id / header X-Request-Id).

Token real vs sandbox do portal

• Token criado no painel (be_token_…) de uma conta real dispara e-mail de verdade (SES) e consome cota.
• Token sandbox do portal da documentação (be_sandbox_…) só simula o aceite — não envia SES nem gasta cota. Não use sandbox para testar entrega na caixa do cliente.

Documentação técnica do endpoint: docs.brenvio.com.br.

Exemplo (cadastrar ou atualizar um contato)

Limite: 60 requisições por minuto por token.

curl (bash)

curl -X POST "https://api.brenvio.com.br/api/v1/integration/contacts" \
  -H "Authorization: Bearer SEU_TOKEN_AQUI" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "Accept-Language: pt-BR" \
  -d '{
    "email": "helena@empresa.com",
    "name": "Helena",
    "country_code": "55",
    "phone_number": "11988887777",
    "tags": ["Lead CRM"],
    "fields": { "empresa": "Acme" }
  }'

JavaScript (fetch)

await fetch("https://api.brenvio.com.br/api/v1/integration/contacts", {
  method: "POST",
  headers: {
    Authorization: "Bearer SEU_TOKEN_AQUI",
    Accept: "application/json",
    "Content-Type": "application/json",
    "Accept-Language": "pt-BR",
  },
  body: JSON.stringify({
    email: "helena@empresa.com",
    name: "Helena",
    country_code: "55",
    phone_number: "11988887777",
    tags: ["Lead CRM"],
    fields: { empresa: "Acme" },
  }),
});

PHP

$ch = curl_init('https://api.brenvio.com.br/api/v1/integration/contacts');
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer SEU_TOKEN_AQUI',
        'Accept: application/json',
        'Content-Type: application/json',
        'Accept-Language: pt-BR',
    ],
    CURLOPT_POSTFIELDS => json_encode([
        'email' => 'helena@empresa.com',
        'name' => 'Helena',
        'country_code' => '55',
        'phone_number' => '11988887777',
        'tags' => ['Lead CRM'],
        'fields' => ['empresa' => 'Acme'],
    ]),
]);
$response = curl_exec($ch);
curl_close($ch);

• Se o e-mail já existir, os dados são atualizados.
• Tags: por padrão anexadas (tag_match omitido). Use "tag_match": "replace" para o CRM mandar o conjunto completo.
• CRUD do catálogo de tags: GET/POST/PATCH/DELETE https://api.brenvio.com.br/api/v1/integration/tags (mesmo Bearer).
• Consultar um contato: GET …/integration/contacts/lookup?email= ou GET …/integration/contacts/{id}. Listar: GET …/integration/contacts. Atualizar: PATCH …/integration/contacts/{id}. Excluir: DELETE (lixeira; um upsert do mesmo e-mail restaura).
• Formulário no seu site (sem token): GET/POST https://api.brenvio.com.br/api/v1/public/forms/{public_key} — a chave sai do painel em Formulários.
• E-mails na lista de bloqueio ou na supressão global são rejeitados (não entram na base).

Documentação técnica completa

Portal público (Try It Out, OpenAPI, Postman, snippets PHP/Node): docs.brenvio.com.br.