Exportação e migração de dados na Brevo: como levar seus dados para dentro ou para fora

O volume de busca por frases como “brevo data export migration to another platform” é movido por uma preocupação só: a de que os dados que você acumulou sejam mais fáceis de colocar do que de tirar. A resposta honesta no caso da Brevo é que a maior parte sai limpa, uma parte sai em um formato que você precisa reconstruir, e uma parcela pequena mas importante não pode se mover de jeito nenhum.

Este guia cobre as duas direções. Ele lista exatamente o que é exportado, o que não é, as chamadas de API para contas grandes demais para a interface, e um checklist de migração que trata listas de supressão e reputação de envio como preocupações de primeira classe, não como detalhes de última hora.

O que dá para exportar de verdade da Brevo

Contatos e atributos

O caminho na interface é CRM e depois Contatos. Para exportar o banco inteiro, garanta que nenhuma lista ou segmento esteja carregado e que nenhum filtro esteja aplicado. Para exportar uma lista ou um segmento, clique em “Carregar uma lista ou segmento” e escolha antes.

Depois você seleciona quais atributos padrão e personalizados incluir. EMAIL, a data da última alteração e a data de criação vêm marcados por padrão, e o resto você acrescenta, que é a etapa que as pessoas mais erram. Escolha o separador de campos do CSV, ponto e vírgula ou vírgula, e opcionalmente ative “Enviar exportação por e-mail” para que um link de download vá ao endereço do dono da conta. Clique em “Iniciar exportação” e depois baixe o arquivo pelo sino de notificações ao lado do nome da sua conta.

Listas e segmentos

As listas são exportadas como participação: rode uma exportação por lista, ou inclua o metadado _listIds em uma exportação completa única e divida o arquivo depois. GET /v3/contacts/lists devolve os nomes, ids e ids de pasta das listas para você recriar a estrutura do outro lado.

Os segmentos são diferentes, e aqui está a primeira lacuna de verdade. GET /v3/contacts/segments devolve apenas id, segmentName, categoryName e updatedAt. As condições de filtro que definem um segmento não são expostas. Você pode exportar os membros de um segmento em um dado momento, mas a regra que os produziu precisa ser lida na tela e reconstruída à mão na nova ferramenta. Tire print de cada segmento antes de cancelar a conta.

Estatísticas de campanha

A partir de um relatório de campanha você pode exportar os dados em CSV, e os relatórios de e-mail e SMS também oferecem uma versão em PDF para compartilhar ou imprimir. Para um puxão histórico completo, GET /v3/emailCampaigns aceita um parâmetro statistics com os valores globalStats, linksStats ou statsByDomain, e um par startDate e endDate cobrindo um intervalo de até dois anos.

Logs transacionais

Dois caminhos, com janelas diferentes.

GET /v3/smtp/statistics/events devolve eventos individuais filtrados por tipo (delivered, opened, clicks, hardBounces, spam, unsubscribed e outros). O intervalo de datas não pode passar de 90 dias, e ele assume os últimos 30 dias se você não passar nem um intervalo nem o parâmetro days.

Para volume, POST /v3/webhooks/export cria um job de exportação sobre os últimos 7 dias de eventos brutos, com teto de 20 jobs de exportação a cada período de 7 dias. Ele devolve um processId, chama sua URL de notificação quando termina e entrega um CSV com colunas que incluem date, email, event, message-id, reason, sending_ip, subject, tag e template_id. Volumes grandes chegam como um arquivo compactado com vários CSVs.

A consequência prática: se você quer mais de 90 dias de histórico transacional, precisava estar exportando isso em uma rotina agendada desde sempre. Configure esse job agora, não na semana em que você decidir sair.

O que não vai com você

Esta é a parte que a maioria dos guias de migração pula.

• Estruturas de fluxos de automação. A API consegue disparar automações por eventos, mas não existe endpoint documentado que leia de volta as ramificações, os atrasos e as condições de um fluxo. Todo fluxo é reconstruído manualmente na nova plataforma.
• Definições de filtro de segmentos. Como já dito, só os nomes e os membros atuais são recuperáveis.
• Histórico completo de engajamento por contato. Você pode exportar quem abriu, clicou, não abriu, cancelou a inscrição, teve hard bounce ou soft bounce em uma campanha específica usando o customContactFilter no endpoint de exportação. O que você não consegue puxar é um único arquivo organizado com “toda abertura e todo clique que este contato já fez”, porque os endpoints de eventos brutos são limitados a 90 dias.
• Fidelidade de renderização dos templates. O htmlContent é exportado sem problema, mas blocos de arrastar e soltar, sintaxe de merge tags e placeholders de link de cancelamento são específicos de cada plataforma. O HTML que você exporta é um ponto de partida, não um template pronto. Reserve tempo para testar de novo cada template no novo editor.
• Reputação de entregabilidade. A reputação de remetente vive nos IPs de envio e no domínio autenticado. Plataforma nova, pool de IPs novo, aquecimento novo. Manter o mesmo domínio e a mesma configuração DKIM preserva o lado de domínio da reputação, o que ajuda de verdade, mas não carrega o lado do IP.
• Identificadores de formulários, landing pages e rastreamento. Formulários de inscrição, landing pages e o script de rastreamento têm ids específicos da plataforma. Qualquer coisa embutida no seu site precisa ser trocada, e qualquer análise atrelada a esses ids quebra na virada.

Exportação automatizada para contas grandes

Acima de aproximadamente 100.000 contatos, a exportação pela interface fica lenta e desconfortável, e você quer um job repetível de qualquer forma. O endpoint de exportação de contatos é assíncrono: ele aceita um filtro, devolve um id de processo e entrega um CSV quando termina.

curl --request POST \
  --url https://api.brevo.com/v3/contacts/export \
  --header 'accept: application/json' \
  --header 'content-type: application/json' \
  --header 'api-key: YOUR_API_KEY' \
  --data '{
    "customContactFilter": { "actionForContacts": "allContacts" },
    "exportMandatoryAttributes": true,
    "exportAttributes": ["FIRSTNAME", "LASTNAME", "SMS", "COUNTRY"],
    "exportMetadata": ["_listIds", "ADDED_TIME", "MODIFIED_TIME"],
    "exportSubscriptionStatus": ["email_marketing", "sms_marketing"],
    "exportDateInUTC": true,
    "notifyUrl": "https://example.com/hooks/brevo-export"
  }'

Uma chamada bem-sucedida devolve HTTP 202 e um corpo contendo um processId. exportMandatoryAttributes é verdadeiro por padrão e cobre EMAIL, ADDED_TIME e MODIFIED_TIME, então exportAttributes é onde você nomeia seus campos personalizados. Definir exportSubscriptionStatus é o que coloca no arquivo o estado de opt-in de marketing para e-mail e SMS, e omiti-lo é a forma mais comum de produzir uma exportação inútil para uma migração em conformidade.

Se você prefere paginar registros a esperar um job, GET /v3/contacts aceita limit de até 1000 com um offset, além de modifiedSince e createdSince para puxadas incrementais. Cada contato volta com emailBlacklisted, smsBlacklisted, listIds, listUnsubscribed e consentGroups, que é tudo de que você precisa para reconstruir o estado de consentimento.

Fique de olho nos limites de taxa enquanto automatiza isso. Os endpoints de contato permitem 36.000 requisições por hora e 10 por segundo nos planos padrão, o dobro nos níveis Professional e Enterprise, enquanto a maioria dos outros endpoints fica em 100 requisições por hora. Paginar um milhão de contatos a 1000 por página são 1000 requisições, confortavelmente dentro do orçamento de contatos, mas martelar endpoints de campanha ou de template em loop já não é.

Por que sua lista de supressão precisa migrar primeiro

Mova os cancelamentos antes de qualquer outra coisa.

O argumento legal é simples. Um contato que cancelou a inscrição retirou o consentimento da sua marca. Essa retirada não é zerada porque você trocou de fornecedor. Sob o GDPR, o registro do consentimento e de sua retirada é sua obrigação como controlador, e sob o CAN-SPAM um cancelamento precisa ser honrado em até dez dias úteis e permanece honrado indefinidamente. Perder a lista em uma migração não é um acidente técnico, é uma falha de conformidade com rastro documental apontando para você.

O argumento de entregabilidade é pior na prática. Endereços suprimidos são desproporcionalmente pessoas que reclamaram, tiveram hard bounce ou queriam ativamente sair. Enviar para elas a partir de um IP novinho sem reputação é o jeito mais rápido conhecido de ter uma configuração de envio nova limitada ou bloqueada já na primeira semana. Alguns milhares de spam traps recicladas e reclamantes podem desfazer um mês de aquecimento cuidadoso.

Então exporte as coortes suprimidas explicitamente, em vez de torcer para que estejam implícitas. No endpoint de exportação, actionForContacts aceita unsubscribed para contatos bloqueados por qualquer meio e unsubscribedPerList para contatos que saíram de uma lista específica. Faça uma passagem separada por hardBounces por campanha. Na entrada da nova plataforma, importe esse arquivo para a lista de supressão dela, não para uma lista enviável.

A Brevo cuida do caminho inverso também: ela permite importar uma lista de contatos bloqueados, e a API de importação aceita os booleanos emailBlacklist e smsBlacklist para que um arquivo importado entre como suprimido. Note a assimetria que a Brevo faz bem em impor: contatos não podem ser desbloqueados em massa, porque reinscrever em massa alguém que pediu para ser deixado em paz seria ilegal. Supressão é fácil de acrescentar e deliberadamente difícil de remover. Trate isso como o comportamento correto, não como um obstáculo.

Checklist de migração, saindo da Brevo

1. Auditoria. Conte contatos, listas, segmentos, automações ativas, templates e integrações. Anote quais integrações escrevem na Brevo, porque são esses os canos que você vai ter que redirecionar.
2. Exportação. Contatos com todos os atributos mais o status de inscrição, um arquivo por lista ou um arquivo único carregando _listIds, coortes de supressão como arquivos separados, estatísticas de campanha, eventos transacionais até onde a janela de 90 dias permitir, e o HTML dos templates.
3. Arquive o que expira. Tudo que é limitado no tempo (eventos brutos, logs) some quando a janela vira. Guarde isso no seu próprio data warehouse ou armazenamento de objetos agora.
4. Limpe e mapeie. Deduplique, normalize formatos de data e telefone e escreva um mapeamento explícito de coluna para campo na nova plataforma. Este também é o momento natural para descartar endereços que não engajaram em um ano, o que é mais barato que pagar para aquecer peso morto. Nosso guia de limpeza de lista de e-mail cobre os limiares.
5. Carregue a supressão primeiro. Importe cancelamentos e hard bounces para a lista de supressão da nova plataforma, confira se as contagens batem com sua exportação e só então carregue os contatos enviáveis.
6. Aqueça. Comece pelo seu segmento mais engajado, aumente o volume aos poucos e acompanhe as taxas de bounce e reclamação diariamente. Nosso guia de entregabilidade de e-mail traz a sequência em detalhe.
7. Rode em paralelo. Mantenha a Brevo no ar enviando seu e-mail transacional crítico enquanto a nova plataforma assume uma fatia crescente dos envios de marketing. Não vire as duas de uma vez.
8. Verifique. Reconcilie as contagens de contatos, confira vinte contatos campo a campo, confirme que os contatos suprimidos estão de fato suprimidos tentando um envio de teste, e compare uma semana de volume de envio com a plataforma antiga.
9. Vire a chave e mantenha um plano de rollback. Mude o DNS e os endpoints de integração em uma janela em que alguém esteja acompanhando. Mantenha a conta Brevo ativa e paga por pelo menos um ciclo de faturamento completo depois da virada, com os arquivos exportados guardados fora das duas plataformas. Isso, e não a promessa de um fornecedor, é seu plano de rollback de verdade.

Migrando para a Brevo vindo de outra plataforma

O mesmo checklist roda ao contrário, com três observações específicas da Brevo.

Consiga uma exportação de verdade do fornecedor atual. A maioria das plataformas entrega contatos e campos personalizados em CSV. Peça especificamente a lista de supressão e a lista de bounces, que muitas vezes ficam em uma exportação separada que as pessoas esquecem de solicitar. Se você vem de um modelo de preço por contato, compare o que vai pagar de fato na entrada com nosso guia de preços da Brevo.

Mapeie os campos antes de subir o arquivo. Os atributos da Brevo têm tipos (texto, número, data, booleano, categoria), e uma data caindo em um atributo de texto não vai ser filtrável depois. Crie os atributos com os tipos certos primeiro, depois importe.

Importe pela API qualquer coisa de tamanho relevante. POST /v3/contacts/import aceita CSV inline em fileBody, um array JSON em jsonBody, ambos com teto em torno de 10 MB, ou um arquivo remoto por fileUrl, além de listIds ou um objeto newList. updateExistingContacts é verdadeiro por padrão e casa por e-mail. Rode uma importação com emailBlacklist como verdadeiro para o seu arquivo de supressão, depois uma segunda importação para os contatos enviáveis. Os scripts completos e funcionais estão no nosso guia de importar contatos CSV para a Brevo com um script.

Depois reconstrua o que não foi transferido: automações, segmentos, formulários e templates. Envie um teste semente para um punhado de provedores de caixa de entrada antes de enviar para alguém de verdade.

Não deixe a próxima migração virar um abismo

O motivo pelo qual uma migração de plataforma parece um abismo é que a plataforma virou o sistema de registro. Histórico de pedidos, estado dos assinantes e resultados de campanha vivem dentro de um fornecedor, e movê-los significa uma evacuação.

A alternativa é manter sua própria fonte da verdade e deixar a plataforma de envio ser um destino, não um cofre. Se os dados da sua loja, o estado de consentimento e os eventos de engajamento são sincronizados continuamente para os seus próprios sistemas, trocar ou acrescentar um canal vira uma mudança de configuração em vez de um projeto. É esse o trabalho que a Tajo faz entre a Brevo e a stack de um lojista: manter os dados fluindo nas duas direções para que a plataforma nunca seja a única cópia.

De qualquer forma, vale rodar agora mesmo os jobs de exportação descritos acima em uma rotina agendada, planeje sair ou não. A migração mais barata é aquela em que os dados já estão fora da plataforma quando você decide.