Esportazione dati e migrazione da Brevo: come spostare i tuoi dati dentro o fuori

Il volume di ricerca per frasi come “brevo data export migration to another platform” nasce da una sola preoccupazione: che i dati accumulati siano più facili da far entrare che da far uscire. La risposta onesta per Brevo è che la maggior parte esce pulita, una parte esce in una forma che devi ricostruire e una parte piccola ma importante non si può proprio spostare.

Questa guida copre entrambe le direzioni. Elenca esattamente cosa si esporta, cosa no, le chiamate API per gli account troppo grandi per l’interfaccia e una checklist di migrazione che tratta liste di soppressione e reputazione di invio come temi di primo piano invece che come ripensamenti.

Cosa puoi davvero esportare da Brevo

Contatti e attributi

Il percorso nell’interfaccia è CRM, poi Contatti. Per esportare l’intero database, assicurati che non sia caricata nessuna lista o segmento e che non sia applicato nessun filtro. Per esportare una sola lista o un segmento, clicca su “Carica una lista o un segmento” e scegli prima quello.

Poi selezioni quali attributi standard e personalizzati includere. EMAIL, la data di ultima modifica e la data di creazione sono selezionati per impostazione predefinita, e il resto lo aggiungi tu: è il passaggio che più spesso viene sbagliato. Scegli il separatore di campo del CSV, punto e virgola o virgola, e volendo attiva “Invia esportazione via email” così il link di download arriva all’indirizzo del proprietario dell’account. Clicca su “Avvia esportazione”, poi scarica il file dalla campanella delle notifiche accanto al nome del tuo account.

Liste e segmenti

Le liste si esportano come appartenenza: esegui un’esportazione per lista, oppure includi i metadati _listIds in un’unica esportazione completa e dividi il file dopo. GET /v3/contacts/lists ti dà nomi, id e id delle cartelle delle liste, così puoi ricreare la struttura dall’altra parte.

I segmenti sono un’altra storia, e qui c’è il primo vero buco. GET /v3/contacts/segments restituisce solo id, segmentName, categoryName e updatedAt. Le condizioni di filtro che definiscono un segmento non sono esposte. Puoi esportare i membri di un segmento in un dato momento, ma la regola che li ha prodotti va letta dallo schermo e ricostruita a mano nel nuovo strumento. Fai uno screenshot di ogni segmento prima di chiudere l’account.

Statistiche delle campagne

Da un report di campagna puoi esportare i dati in CSV, e i report email e SMS offrono anche una versione PDF da condividere o stampare. Per un’estrazione storica completa, GET /v3/emailCampaigns accetta un parametro statistics con valori globalStats, linksStats o statsByDomain, e una coppia startDate e endDate che copre un intervallo fino a due anni.

Log transazionali

Due percorsi, con finestre diverse.

GET /v3/smtp/statistics/events restituisce i singoli eventi filtrati per tipo (delivered, opened, clicks, hardBounces, spam, unsubscribed e altri). L’intervallo di date non può superare i 90 giorni, e per impostazione predefinita copre gli ultimi 30 giorni se non passi né un intervallo né il parametro days.

Per il massivo, POST /v3/webhooks/export crea un job di esportazione sugli ultimi 7 giorni di eventi grezzi, con un tetto di 20 job di esportazione per periodo di 7 giorni. Restituisce un processId, chiama il tuo URL di notifica quando ha finito e consegna un CSV con colonne che includono date, email, event, message-id, reason, sending_ip, subject, tag e template_id. I volumi grandi arrivano come archivio compresso di più file CSV.

La conseguenza pratica: se vuoi più di 90 giorni di storico transazionale, dovevi già esportarlo con una schedulazione. Imposta quel job adesso, non nella settimana in cui decidi di andartene.

Cosa non viene con te

Questa è la parte che la maggior parte delle guide alla migrazione salta.

• Le strutture dei workflow di automazione. L’API può attivare le automazioni tramite eventi, ma non esiste un endpoint documentato che rilegga i rami, i ritardi e le condizioni di un workflow. Ogni workflow va ricostruito a mano nella nuova piattaforma.
• Le definizioni dei filtri dei segmenti. Come sopra, si recuperano solo i nomi e i membri attuali.
• La cronologia di engagement completa per contatto. Puoi esportare chi ha aperto, cliccato, non aperto, si è disiscritto o ha generato un hard bounce o un soft bounce su una campagna specifica usando customContactFilter sull’endpoint di esportazione. Quello che non puoi estrarre è un unico file ordinato con “ogni apertura e ogni clic mai fatti da questo contatto”, perché gli endpoint degli eventi grezzi sono limitati a 90 giorni.
• La fedeltà di rendering dei template. htmlContent si esporta pulito, ma i blocchi drag and drop, la sintassi dei merge tag e i segnaposto dei link di disiscrizione sono specifici della piattaforma. L’HTML che esporti è un punto di partenza, non un template finito. Metti a budget il tempo per ritestare ogni template nel nuovo editor.
• La reputazione di recapito. La reputazione del mittente vive sugli IP di invio e sul dominio autenticato. Nuova piattaforma, nuovo pool di IP, nuovo warm up. Mantenere lo stesso dominio e la stessa configurazione DKIM preserva il lato dominio della reputazione, il che aiuta davvero, ma non porta con sé il lato IP.
• Gli identificatori di moduli, landing page e tracciamento. I moduli di iscrizione, le landing page e lo script di tracciamento hanno tutti id specifici della piattaforma. Tutto ciò che è incorporato nel tuo sito va sostituito, e ogni analisi legata a quegli id si rompe al momento del passaggio.

Esportazione automatizzata per account grandi

Sopra i 100.000 contatti circa l’esportazione dall’interfaccia diventa lenta e scomoda, e comunque vuoi un job ripetibile. L’endpoint di esportazione dei contatti è asincrono: accetta un filtro, restituisce un id di processo e ti consegna un CSV quando finisce.

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"
  }'

Una chiamata riuscita restituisce HTTP 202 e un corpo che contiene un processId. exportMandatoryAttributes vale true per impostazione predefinita e copre EMAIL, ADDED_TIME e MODIFIED_TIME, quindi exportAttributes è dove indichi i tuoi campi personalizzati. Impostare exportSubscriptionStatus è ciò che porta nel file lo stato di consenso marketing per email e SMS, e ometterlo è di gran lunga il modo più comune di produrre un’esportazione inutile per una migrazione conforme.

Se preferisci paginare i record invece di aspettare un job, GET /v3/contacts accetta limit fino a 1000 con un offset, più modifiedSince e createdSince per le estrazioni incrementali. Ogni contatto torna con emailBlacklisted, smsBlacklisted, listIds, listUnsubscribed e consentGroups, cioè tutto quello che serve per ricostruire lo stato del consenso.

Tieni d’occhio i limiti di frequenza mentre scrivi lo script. Gli endpoint dei contatti consentono 36.000 richieste all’ora e 10 al secondo sui piani standard, il doppio sui livelli Professional ed Enterprise, mentre la maggior parte degli altri endpoint sta a 100 richieste all’ora. Paginare un milione di contatti a 1000 per pagina fa 1000 richieste, comodamente dentro il budget dei contatti, ma martellare in un ciclo gli endpoint delle campagne o dei template no.

Perché la tua lista di soppressione deve migrare per prima

Sposta le rinunce prima di ogni altra cosa.

L’argomento legale è semplice. Un contatto che si è disiscritto ha revocato il consenso al tuo brand. Quella revoca non si azzera perché hai cambiato fornitore. Sotto il GDPR la traccia del consenso e della sua revoca è un tuo obbligo in quanto titolare, e sotto il CAN-SPAM una rinuncia va onorata entro dieci giorni lavorativi e resta valida per sempre. Perdere quella lista in una migrazione non è un incidente tecnico, è una violazione di conformità con una traccia documentale che punta a te.

L’argomento di recapitabilità è ancora peggiore nella pratica. Gli indirizzi soppressi sono in misura sproporzionata persone che hanno reclamato, che hanno generato hard bounce o che volevano attivamente uscire. Scrivere loro da un IP nuovo di zecca e senza reputazione è il modo più rapido conosciuto per far limitare o bloccare una configurazione di invio nella sua prima settimana. Qualche migliaio di spam trap riciclate e di persone che hanno reclamato può annullare un mese di warm up attento.

Quindi esporta le coorti soppresse in modo esplicito invece di sperare che siano implicite. Sull’endpoint di esportazione, actionForContacts accetta unsubscribed per i contatti in blocklist per qualunque motivo e unsubscribedPerList per i contatti che hanno rinunciato a una lista specifica. Fai un passaggio separato per hardBounces per campagna. In entrata sulla nuova piattaforma, importa quel file nella sua lista di soppressione, non in una lista contattabile.

Brevo gestisce anche il caso inverso: supporta l’importazione di una lista di contatti in blocklist, e l’API di import accetta i booleani emailBlacklist e smsBlacklist così un file importato arriva come soppresso. Nota l’asimmetria che Brevo fa bene a imporre: i contatti non possono essere tolti dalla blocklist in blocco, perché reiscrivere in massa qualcuno che ha chiesto di essere lasciato in pace sarebbe illegale. La soppressione è facile da aggiungere e volutamente difficile da rimuovere. Consideralo il comportamento corretto, non un ostacolo.

Checklist di migrazione, in uscita da Brevo

1. Audit. Conta contatti, liste, segmenti, automazioni attive, template e integrazioni. Annota quali integrazioni scrivono dentro Brevo, perché sono i tubi che dovrai reindirizzare.
2. Esporta. Contatti con tutti gli attributi più lo stato di iscrizione, un file per lista oppure un singolo file che porta _listIds, le coorti di soppressione come file separati, le statistiche delle campagne, gli eventi transazionali per quanto indietro consente la finestra di 90 giorni e l’HTML dei template.
3. Archivia ciò che scade. Tutto ciò che ha un limite temporale (eventi grezzi, log) sparisce quando la finestra scorre. Conservalo ora nel tuo data warehouse o nel tuo object storage.
4. Pulisci e mappa. Deduplica, normalizza i formati di data e telefono e scrivi una mappatura esplicita colonna per campo per la nuova piattaforma. È anche il momento naturale per eliminare gli indirizzi che non interagiscono da un anno, cosa più economica che pagare per scaldare peso morto. La nostra guida alla pulizia delle liste email copre le soglie.
5. Carica prima la soppressione. Importa rinunce e hard bounce nella lista di soppressione della nuova piattaforma, verifica che i conteggi corrispondano alla tua esportazione e solo dopo carica i contatti contattabili.
6. Warm up. Parti dal tuo segmento più coinvolto, aumenta il volume gradualmente e controlla ogni giorno i tassi di bounce e di reclamo. La nostra guida alla recapitabilità delle email contiene la sequenza nel dettaglio.
7. Fai girare in parallelo. Tieni Brevo attivo a inviare le tue email transazionali critiche mentre la nuova piattaforma gestisce una quota crescente degli invii marketing. Non ribaltare tutto insieme.
8. Verifica. Riconcilia i conteggi dei contatti, controlla a campione venti contatti campo per campo, conferma che i contatti soppressi siano davvero soppressi provando un invio di test e confronta una settimana di volume di invio con la vecchia piattaforma.
9. Passa e tieni un piano di rientro. Cambia DNS ed endpoint delle integrazioni in una finestra in cui qualcuno sta guardando. Tieni l’account Brevo vivo e pagato per almeno un ciclo di fatturazione completo dopo il passaggio, con i file esportati conservati fuori da entrambe le piattaforme. Quello, e non una promessa del fornitore, è il tuo vero piano di rientro.

Migrare dentro Brevo da un’altra piattaforma

La stessa checklist gira al contrario, con tre note specifiche per Brevo.

Ottieni una vera esportazione dal fornitore attuale. La maggior parte delle piattaforme ti dà i contatti e i loro campi personalizzati in CSV. Chiedi esplicitamente la lista di soppressione e la lista dei bounce, che spesso stanno in un’esportazione separata che tutti dimenticano di richiedere. Se arrivi da un modello di prezzo per contatto, confronta quello che pagherai davvero in entrata con la nostra guida ai prezzi di Brevo.

Mappa i campi prima di caricare. Gli attributi di Brevo hanno un tipo (testo, numero, data, booleano, categoria), e una data che finisce in un attributo di testo non sarà filtrabile in seguito. Crea prima gli attributi con i tipi giusti, poi importa.

Importa tramite API per qualsiasi cosa di dimensioni serie. POST /v3/contacts/import accetta CSV inline in fileBody, un array JSON in jsonBody, entrambi con un tetto intorno ai 10 MB, oppure un file remoto tramite fileUrl, più listIds o un oggetto newList. updateExistingContacts vale true per impostazione predefinita e abbina sull’email. Esegui un’importazione con emailBlacklist impostato a true per il file di soppressione, poi una seconda importazione per i contatti contattabili. Gli script completi e funzionanti sono nella nostra guida su come importare contatti CSV in Brevo con uno script.

Poi ricostruisci ciò che non si è trasferito: automazioni, segmenti, moduli e template. Invia un test seed a una manciata di provider di posta prima di scrivere a qualcuno di reale.

Fai in modo che la prossima migrazione non sia un salto nel vuoto

Il motivo per cui la migrazione di piattaforma sembra un salto nel vuoto è che la piattaforma è diventata il sistema di riferimento. Storico ordini, stato degli iscritti e risultati delle campagne vivono dentro un unico fornitore, e spostarli significa un’evacuazione.

L’alternativa è mantenere una tua fonte di verità e lasciare che la piattaforma di invio sia una destinazione invece che una cassaforte. Se i dati del tuo negozio, lo stato del consenso e gli eventi di engagement sono sincronizzati di continuo nei tuoi sistemi, cambiare o aggiungere un canale diventa una modifica di configurazione invece di un progetto. È il lavoro che Tajo svolge tra Brevo e lo stack di un merchant: tenere i dati in movimento in entrambe le direzioni così la piattaforma non è mai l’unica copia.

In ogni caso, i job di esportazione descritti sopra vale la pena eseguirli con una schedulazione fin da ora, che tu abbia intenzione di andartene o no. La migrazione più economica è quella in cui i dati sono già fuori dalla piattaforma quando decidi.