Sign inGet started

Migracja z Brevo

Ta strona mapuje payload wysyłki transakcyjnej Brevo, listy blokad i webhooki na Bird. Wykonuj główny przewodnik migracji po kolei i użyj tych mapowań do kroków 1, 3 i 4.
Brevo przechowuje supresje w dwóch niezależnych miejscach, jednym dla poczty transakcyjnej i jednym dla marketingowej. Przeczytaj Eksport supresji, zanim zaplanujesz krok 3: wyeksportowanie jednej listy bez drugiej to błąd, do którego ta migracja zachęca.

Przekaż to swojemu agentowi

Wklej to do Claude Code, Cursor lub Codex. Agent przechodzi przez tę stronę w kontekście Twojego repozytorium, korzystając z dowolnego interfejsu Bird, który już ma: serwera MCP, jeśli jest podłączony, lub CLI, jeśli jest zainstalowany i zalogowany.
Przykład kodu
I am moving an email integration from Brevo to Bird. Route through it with me.
1. Check what you already have before setting anything up. If Bird's MCP server is connected, use its tools. If the Bird CLI is installed and signed in, use that. Either one is enough, and every step below is an action you take with whichever you have. Only if neither is present, follow https://bird.com/docs/ai/set-up-your-agent.md to set one up and sign me in. Every Bird docs page serves Markdown at its own URL with `.md` appended, so fetch that rather than the HTML.
2. Read https://bird.com/docs/guides/email/migrate/brevo.md for the payload, suppression and webhook mapping, and https://bird.com/docs/guides/email/migrate.md for the order the steps go in.
3. Find and list my Brevo usage in this repository before you change anything: calls to /v3/smtp/email and any SDK wrappers around them, whether I send with templateId or with htmlContent, the webhook handler and the URL it is registered at, and every domain I send from. Tell me the list before you edit anything.
4. Register each of those sending domains with Bird and give me the DNS records to publish, following https://bird.com/docs/guides/email/sending-domains.md. Leave every DNS record Brevo uses exactly as it is: Bird's records are published alongside them and both providers authenticate side by side until I switch traffic. Publishing DNS affects mail for the whole domain, so show me the records and let me publish them.
5. Export my suppressions and import them into Bird before any production traffic goes through Bird, so my first sends do not reach addresses that already bounced or complained. Brevo holds these in two separate places and I need both: GET /v3/smtp/blockedContacts for transactional blocks and unsubscribes, and the marketing blocklist, which lives on the contact records as emailBlacklisted rather than on a suppression endpoint. Page through both. The Bird import takes one address per request and is idempotent, so a partial re-run is safe. https://bird.com/docs/guides/email/suppressions.md has the reason taxonomy.
6. Port the send call and the webhook handler using the mapping tables on the provider page. Brevo's webhook security page documents credentials I configure on the endpoint rather than a payload signature, so check what my endpoint actually relies on today: if it is a username and password in the webhook URL, take them out and tell me to rotate that pair rather than reusing it, because a credential that has lived in a URL should be treated as exposed. Bird signs every delivery instead. https://bird.com/docs/guides/webhooks.md and https://bird.com/docs/guides/email/events.md.
7. Run my whole integration against Bird's mail sandbox before any production traffic, following https://bird.com/docs/guides/email/testing-sandbox.md. Sandbox sends run the real pipeline without reaching an inbox or touching my sending reputation.
8. Stop and ask me wherever a step needs a decision. Do not point production traffic at Bird until I have seen the sandbox results and replied with the words cut over to Bird. Retiring the Brevo path is a separate step that comes later: ask me again and wait for me to reply with the words retire the Brevo path. A reply that agrees without naming what it is authorising is not authorisation. Finish by telling me what is left that only a person can do.

Zamapuj wywołanie wysyłki

POST /v3/smtp/email Brevo i nasze POST /v1/email/messages mają zbliżoną strukturę. Większość pracy polega na rozpakowaniu obiektów adresowych Brevo do zwykłych stringów.
Co robiBrevoBird
AutoryzacjaNagłówek api-keyAuthorization: Bearer
Nadawcasender ({email, name})from
Odbiorcyto / cc / bcc (tablice {email, name})to / cc / bcc (tablice adresów)
Tematsubjectsubject
TreśćhtmlContent / textContenthtml / text (co najmniej jedno)
Reply-toreplyTo ({email, name})reply_to (tablica)
Własne nagłówkiheaders (klucze w Title-Case)headers (obiekt string → string)
Filtrowalne etykietytags (tablica stringów)tags: pary {name, value}
Zapisany szablontemplateId + paramstemplate + template.parameters
Załącznikiattachment (url lub base64 content)attachments (tylko base64, patrz niżej)
PlanowaniescheduledAtscheduled_at
Uchwyt wsadowybatchId(brak odpowiednika, patrz niżej)
Kopia per odbiorcamessageVersionsjedna wysyłka na wersję lub batch
Kategoria(brak)category: marketing (domyślnie) lub transactional
Limity pól i wartości domyślne (liczba odbiorców, limity tagów i metadanych) znajdziesz w Wysyłanie e-maili.
Uwagi dotyczące portowania:
  • Adresy tam są obiektami, a tutaj stringami. {"email": "a@x.com", "name": "A"} staje się "A <a@x.com>" lub po prostu "a@x.com". To samo rozpakowanie dotyczy sender i replyTo.
  • tags to zwykłe stringi. Nasze tagi to pary. Tag taki jak "welcome" staje się {"name": "category", "value": "welcome"}. Wybierz stabilny name, żeby Twoje dashboardy filtrowały tak samo jak statystyki tagów w Brevo.
  • params to dane szablonu, a nie kontekst dwukierunkowy. Staje się template.parameters. Jeśli używałeś go też do przekazywania własnych identyfikatorów do zdarzeń, przenieś je do metadata, które zwracamy w każdym zdarzeniu webhookowym wraz z email_id/recipient_id.
  • messageVersions nie ma odpowiednika w jednym wywołaniu. Każda wersja to odrębny zestaw odbiorców i payload, więc staje się albo osobną wysyłką, albo jednym wpisem w batchu.
  • batchId nie ma odpowiednika. batchId w Brevo grupuje zaplanowane wiadomości, żebyś mógł je anulować lub przełożyć jako zestaw. Zaplanowane wysyłki tutaj są adresowane indywidualnie po ich identyfikatorze wiadomości; nie ma uchwytu grupowego do przekazania ani anulowania.
  • Załącznik przez URL nie jest obsługiwany. Brevo akceptuje wpis attachment jako URL, z którego sam pobiera plik. Pobierz plik samodzielnie i wyślij go zakodowany w base64; patrz załączniki.

Eksport supresji

Brevo rozdziela supresje między dwa systemy, które nie mają wspólnego endpointu ani schematu paginacji, a migracja pobierająca tylko pierwszy cicho traci każdy marketingowy unsubscribe:
  • Blokady i unsubscriby transakcyjne: GET /v3/smtp/blockedContacts, paginowany (domyślnie 50 na stronę, maksymalnie 100), każdy wpis zawiera powód blokady.
  • Marketingowa lista blokad: to w ogóle nie jest endpoint supresji. Znajduje się w rekordzie kontaktu jako emailBlacklisted, więc paginuj GET /v3/contacts (do 1000 na stronę z offset) i zachowaj kontakty, w których ta flaga ma wartość true.
Przepuść obie listy przez pętlę importu. Powody blokad Brevo mapują się na nasze powody hard_bounce, complaint i manual; Supresje zawierają pełną taksonomię.

Przetłumacz zdarzenia webhookowe

RezultatBrevoBird
Zaakceptowane/przetworzonerequestemail.acceptedemail.processed
Dostarczonedeliveredemail.delivered
Błąd tymczasowydeferred / soft_bounceemail.deferred
Trwały bouncehard_bounceemail.bounced / email.out_of_band_bounce
Zgłoszenie spamuspamemail.complained
Zablokowane/wstrzymaneblocked / invalid_emailemail.rejected
Otwarcieopened / unique_openedemail.opened
Kliknięcieclickemail.clicked
Wypisanie sięunsubscribedemail.unsubscribed / email.list_unsubscribed
Dwie różnice decydują o tym, jak bardzo zmieni się Twój handler.
Sprawdź, na czym Twój endpoint polega dziś, zanim zaczniesz go portować. Strona bezpieczeństwa webhooków Brevo dokumentuje dane uwierzytelniające konfigurowane na endpoincie: nazwę użytkownika i hasło dołączane do URL jako https://username:password@example.com/, token bearer, własne nagłówki żądań i zakresy IP. My podpisujemy każde dostarczenie zgodnie ze schematem HMAC Standard Webhooks, więc weryfikacja przenosi się z czegoś, co niesie wywołujący, na coś, co oblicza Twój handler. Jeśli Twój obecny endpoint przechowuje dane uwierzytelniające w URL, usuń je i zrotuj tę parę zamiast jej ponownie używać: dane uwierzytelniające, które żyły w URL, trafiły do logów dostępu, eksportów konfiguracji i konsoli dostawcy. Instrukcja jest w Webhooki i zdarzenia.
Brevo rozróżnia otwarcia i kliknięcia od ich wariantów unikalnych. My nie. opened i unique_opened przychodzą jako email.opened, więc handler, który liczył tylko wariant unikalny, musi deduplikować po recipient_id. Nasze zdarzenia dostarczenia są w zakresie odbiorcy, więc wysyłka do trzech odbiorców generuje trzy wyniki dostarczenia, a nie jeden.

Przełączenie

Przejdź przez domeny i DNS oraz test sandbox w głównym przewodniku. Oba są niezależne od dostawcy.

Następne kroki

  • Domeny wysyłkowe: rejestracja, cykl życia weryfikacji i rekordy DNS, które publikujesz
  • Webhooki i zdarzenia: konfiguracja endpointu i weryfikacja Standard Webhooks
  • Sandbox testowy: przetestuj nową integrację przed przełączeniem
  • Supresje: potwierdź zaimportowaną listę i sposób, w jaki utrzymujemy ją od teraz