Do Brevo para a Postal, sem levar o que não é e-mail

Antes de mudar qualquer coisa, liste o que o seu sistema usa no Brevo. Cada item tem um lugar na Postal, ou não tem, e é melhor descobrir isso agora.

Em Domínios, a Postal mostra poucos registros para quem cuida do DNS copiar e confere sozinha por até 72 horas. O domínio pode continuar autenticado no Brevo ao mesmo tempo: os nomes dos registros são diferentes.

• Copie os valores da tela do seu Brevo: os da tabela são exemplos da documentação, e o seu código de verificação é único.
• Como os nomes são diferentes (mail._domainkey no exemplo do Brevo, postal._domainkey na Postal), os dois ficam válidos durante a virada. Confira se algum nome da sua conta é igual antes de publicar.
• A Postal avisa pelo webhook domain.updated quando o domínio vira verified. Veja Domínios e DNS.

A Postal não aceita o formato do Brevo. A chamada passa a ser POST /emails, com a chave em Authorization: Bearer no lugar do cabeçalho api-key, e os campos mudam de nome. Abaixo, o mesmo e-mail nos dois formatos.

POST https://api.brevo.com/v3/smtp/email
api-key: <chave do Brevo>
Content-Type: application/json

{
  "sender": { "name": "Aurora Cosméticos", "email": "[email protected]" },
  "to": [{ "email": "[email protected]", "name": "Ana" }],
  "subject": "Seu pedido #10482 saiu para entrega",
  "htmlContent": "<p>O pedido <b>#10482</b> está a caminho.</p>",
  "textContent": "O pedido #10482 está a caminho.",
  "tags": ["entrega"]
}

POST https://api.postal.so/emails
Authorization: Bearer ps_sua_chave
Idempotency-Key: pedido-10482-saiu
Content-Type: application/json

{
  "from": "Aurora Cosméticos <[email protected]>",
  "to": ["Ana <[email protected]>"],
  "subject": "Seu pedido #10482 saiu para entrega",
  "html": "<p>O pedido <b>#10482</b> está a caminho.</p>",
  "text": "O pedido #10482 está a caminho.",
  "tags": [{ "name": "entrega" }]
}

• Sem templateId, o Brevo exige sender, subject e htmlContent. A Postal exige from, subject e html ou text.
• A Postal acrescenta o cabeçalho Idempotency-Key: repetir a chamada com a mesma chave e o mesmo corpo, em até 24 horas, devolve a resposta da primeira e não envia de novo. Veja Idempotência.
• A documentação da Postal não trata de IP dedicado. Se você usa o campo sender.ip no Brevo, fale com a gente pelo formulário de contato antes de migrar.
• Prefere um SDK? Os da Postal (Node.js, PHP e Laravel) usam esta mesma API. Veja SDKs e CLI e a referência de e-mails.

Sistemas que falam SMTP, como WordPress, ERPs e plataformas de loja, mudam quatro campos: servidor, porta, usuário e senha. No Brevo a senha é uma chave SMTP, e não a chave de API. Na Postal é uma chave de API.

- MAIL_HOST=smtp-relay.brevo.com- MAIL_PORT=587- MAIL_USERNAME=<login SMTP do Brevo>- MAIL_PASSWORD=<chave SMTP do Brevo>+ MAIL_SCHEME=smtps+ MAIL_HOST=smtp.postal.so+ MAIL_PORT=465+ MAIL_USERNAME=postal+ MAIL_PASSWORD=ps_sua_chave

• Na Postal, a autenticação (AUTH PLAIN ou AUTH LOGIN) vem sempre depois do TLS.
• O SMTP da Postal não tem tags, agendamento nem templates: para isso, use a API. Se o seu sistema manda cabeçalhos próprios do Brevo para essas funções, a Postal não os interpreta e eles seguem como cabeçalhos comuns.
• Os envios por SMTP seguem as mesmas regras da API (domínio verificado, cotas e supressão) e aparecem em E-mails e Logs. Veja o guia de SMTP.

A Postal não converte modelos de outra plataforma, mas o HTML vem pela API do Brevo. O script abaixo lista os modelos ativos, troca {{params.nome}} por {{{nome}}} e cria cada um como template, com o alias brevo-<id>. É um ponto de partida: revise o resultado antes de publicar o seu.

const brevoHeaders = { 'api-key': process.env.BREVO_API_KEY }
const postalHeaders = {
  Authorization: `Bearer ${process.env.POSTAL_API_KEY}`,
  'Content-Type': 'application/json',
}

// {{params.nome}} do Brevo vira {{{nome}}} na Postal
const convert = (text) => text.replace(/\{\{\s*params\.(\w+)\s*\}\}/g, '{{{$1}}}')

const url = 'https://api.brevo.com/v3/smtp/templates?templateStatus=true&limit=100'
const response = await fetch(url, { headers: brevoHeaders })
const { templates } = await response.json()

for (const template of templates) {
  const created = await fetch('https://api.postal.so/templates', {
    method: 'POST',
    headers: postalHeaders,
    body: JSON.stringify({
      name: template.name,
      alias: `brevo-${template.id}`,
      subject: convert(template.subject),
      html: convert(template.htmlContent),
    }),
  })
  if (!created.ok) throw new Error(await created.text())

  const { id } = await created.json()
  await fetch(`https://api.postal.so/templates/${id}/publish`, { method: 'POST', headers: postalHeaders })
}

• O Brevo só aceita params nos modelos da “nova linguagem de modelos” (New Template Language). Os modelos mais antigos precisam ser revisados à mão.
• Valores de params que são listas ou objetos não passam: na Postal, cada variável é texto ou número, e uma variável sem valor e sem valor padrão devolve 422. Declare as opcionais com fallback_value.
• A resposta do Brevo traz o remetente (sender) de cada modelo. Na Postal, ele vem de from no envio, ou do remetente padrão que você guardar no template.
• O envio usa sempre a última versão publicada. Veja a referência de templates; o plano define quantos templates o time tem.

Os eventos principais existem nos dois lados, com outros nomes e outro corpo. No Brevo, a documentação consultada não descreve assinatura: ele autentica com usuário e senha na URL, token Bearer, cabeçalhos próprios ou lista de IPs. Na Postal, cada entrega vem assinada com o segredo do endpoint.

• Crie o endpoint em Webhooks (painel ou POST /webhooks) e guarde o signing_secret. Mande um evento de teste pelo painel antes de virar.
• Os endereços de teste ([email protected], [email protected] e outros) geram webhooks reais, sem usar a cota. Dependem do plano.
• Tire os webhooks do Brevo só depois de virar todo o tráfego: os e-mails que ainda saem por lá continuam gerando eventos.

Faça isto antes de importar contatos: um endereço que está na lista de supressão nunca vira contato. O Brevo lista, por API, os contatos bloqueados ou descadastrados dos e-mails transacionais, com o motivo de cada um.

const reasonsToSuppress = new Set(['hardBounce', 'contactFlaggedAsSpam'])
const emails = []

for (let offset = 0; ; offset += 100) {
  const url = `https://api.brevo.com/v3/smtp/blockedContacts?limit=100&offset=${offset}`
  const response = await fetch(url, { headers: { 'api-key': process.env.BREVO_API_KEY } })
  const { contacts = [] } = await response.json()
  if (contacts.length === 0) break

  for (const contact of contacts) {
    if (reasonsToSuppress.has(contact.reason?.code)) emails.push(contact.email.toLowerCase())
  }
}

for (let i = 0; i < emails.length; i += 100) {
  const response = await fetch('https://api.postal.so/suppressions/batch/add', {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${process.env.POSTAL_API_KEY}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({ emails: emails.slice(i, i + 100) }),
  })
  if (!response.ok) throw new Error(await response.text())
  await new Promise((resolve) => setTimeout(resolve, 250)) // respeita o limite do plano
}

• A rota é GET /v3/smtp/blockedContacts, com até 100 por página. Cada item traz email, blockedAt e reason.code. O script leva só os dois motivos de entrega e deixa os demais para você decidir.
• Na Postal, os endereços entram com a origem manual: a diferença entre bounce e reclamação não é guardada. A chave precisa ser de acesso total. Veja a referência de supressões.
• O Brevo também tem uma lista de domínios bloqueados. A lista de supressão da Postal guarda endereços, e não domínios inteiros: se precisa disso, recuse o domínio no seu formulário ou no seu sistema.

O painel do Brevo exporta contatos em CSV, e a API também. Em CRM, Contacts, selecione os contatos e use More actions, Export, escolhendo os atributos. Pela API, o pedido abaixo gera o arquivo e avisa o seu notifyUrl quando ele ficar pronto.

POST https://api.brevo.com/v3/contacts/export
api-key: <chave do Brevo>
Content-Type: application/json

{
  "customContactFilter": { "actionForContacts": "subscribed", "listId": 12 },
  "exportAttributes": ["FIRSTNAME", "LASTNAME"],
  "notifyUrl": "https://exemplo.com.br/hooks/brevo-export"
}

• Em actionForContacts, a API aceita allContacts, subscribed, unsubscribed e unsubscribedPerList. É preciso informar também listId, segmentId, modifiedSince ou createdSince (data completa, com fuso). Exporte inscritos e descadastrados em arquivos separados.
• Sem CSV, GET /v3/contacts (até 1.000 por página) e GET /v3/contacts/lists/{id}/contacts (até 500) devolvem JSON com attributes, listIds, listUnsubscribed e emailBlacklisted.
• Descadastrados: no arquivo deles, deixe uma coluna Descadastrado com sim em todas as linhas e aponte essa coluna para o campo Descadastrado (sim/não). Quem estava com emailBlacklisted verdadeiro entra aqui, e nunca como inscrito.
• Listas: exporte uma lista por arquivo e importe cada um escolhendo o segmento. Só segmentos estáticos recebem contatos importados. Quem saiu de uma lista só (listUnsubscribed) merece cuidado: se a lista virou um tópico, registre a escolha opt_out dessas pessoas com PATCH /contacts/{id}/topics.
• Crie antes as Propriedades dos atributos que quer manter: a importação não cria propriedades novas. Se você usa um ID próprio (ext_id) e ele vier no arquivo, aponte-o para o campo de ID externo.
• Deixe desligada a opção Disparar automações. Contatos que já existem são atualizados pelo e-mail, e cada arquivo pode ter até 20 MB. O limite de contatos do plano está em Preços: no Grátis são 1.000, no Profissional 5.000 e no Escala 50.000.
• Antes de enviar, passe a lista pela Validação de e-mails.

Campanhas e automações não passam sozinhas. Não achamos na documentação do Brevo uma exportação delas para outra plataforma, então trate cada uma como nova e aproveite para revisar o que ainda faz sentido.

• Importações não iniciam automações, a menos que você ligue essa opção. Revise quem entraria antes de ativar.
• Cada plano tem um limite de execuções de automações por mês.

Vire um fluxo de cada vez, com o Brevo ainda ligado. Comece pelos endereços de teste e por você mesmo, compare entregas e bounces nos primeiros dias e só então passe o resto.