Migracja z innego dostawcy

Skorzystaj z tego przewodnika, aby przenieść produkcyjną wysyłkę e-maili od innego dostawcy. Zmapuj żądanie wysyłki, opublikuj rekordy DNS, zaimportuj suppresje, przetłumacz zdarzenia webhooków i przetestuj integrację przed skierowaniem ruchu produkcyjnego do Bird.

Lista kontrolna migracji:

1. Zmapuj wywołanie wysyłki na POST /v1/email/messages
2. Przekieruj domeny wysyłkowe i DNS
3. Zaimportuj listę suppresji
4. Przełącz webhooki na nasze słownictwo zdarzeń
5. Zweryfikuj w sandboxie pocztowym przed przełączeniem

Kroki 1, 3 i 4 zależą od dostawcy, od którego odchodzisz. Twój przewodnik po dostawcy zawiera mapowanie pól payloadu, informacje o eksporcie listy suppresji oraz tabelę tłumaczeń nazw zdarzeń webhooków.

1. Zmapuj wywołanie wysyłki

Mamy jeden endpoint do pojedynczej wysyłki: POST /v1/email/messages. Tworzysz płaski payload JSON (bez wrappera personalizations, bez składania MIME) z from, tablicami to/cc/bcc, subject, html i/lub text, opcjonalną listą reply_to oraz headers dla niestandardowych nagłówków e-mail. Udane wysłanie zwraca 202 Accepted z identyfikatorem wiadomości z prefiksem em_. Wyniki dostarczenia przychodzą asynchronicznie przez webhooki i endpointy odczytu. Pełny payload ze wszystkimi limitami pól i wartościami domyślnymi znajdziesz w Wysyłanie e-maili. Mapowanie pól z Twojego obecnego payloadu jest w przewodniku po dostawcy. Jeśli Twoja aplikacja wysyła obecnie przez SMTP, być może w ogóle nie musisz przenosić wywołania: akceptujemy wysyłkę przez SMTP do tego samego pipeline'u, co sprowadza ten krok do wymiany danych uwierzytelniających.

Używaj tags jako wymiarów filtrowania w listach wiadomości, analityce i podsumowaniach dashboardu. Używaj metadata dla ustrukturyzowanego kontekstu, który Bird przechowuje na wiadomości, zwraca przy odczytach API i powtarza w zdarzeniach webhooków. Limity opisano w Tagi vs metadane.

Przed przeniesieniem kodu uwzględnij te różnice:

• Planowanie, zapisane szablony i załączniki przenoszą się bezproblemowo. Użyj scheduled_at do planowanej wysyłki. Użyj template zamiast treści inline dla zapisanych szablonów. Zmapuj pliki na tablicę załączników.
• Odbiorcy objęci suppresją są odrzucani w widoczny sposób. Adres objęty suppresją wciąż otrzymuje recipient_id i pojawia się na liście odbiorców wiadomości ze statusem rejected oraz zdarzeniem email.rejected (rejection_reason: recipient_suppressed), nigdy jako cicha utrata. Nawet gdy wszyscy odbiorcy są objęci suppresją, żądanie jest akceptowane z 202. Każdy odbiorca wraca jako odrzucony. Zobacz Suppresje.
• Ustaw category: "transactional" dla poczty operacyjnej. Domyślna wartość wysyłki to marketing, a kategoria kontroluje politykę suppresji: marketing blokuje na podstawie skarg i wypisań, transactional dostarcza mimo nich. Newslettery i kampanie są obsługiwane poprawnie przez wartość domyślną. Oznacz potwierdzenia, resety haseł i podobną pocztę operacyjną jako transactional, aby nie były blokowane przez wypisanie.

2. Przekieruj domeny i DNS

Zarejestruj każdą domenę wysyłkową za pomocą POST /v1/email/domains lub w Email > Domains, a następnie opublikuj rekordy z dns_records. DKIM, CNAME return-path i polityka DMARC warunkują wysyłkę. Istniejący rekord DMARC, w tym na domenie nadrzędnej, jest wystarczający. CNAME śledzenia warunkuje wyłącznie brandowane śledzenie otwarć i kliknięć. Domeny wysyłkowe opisują rekordy, cykl życia weryfikacji i model regionalny. Użyj narzędzia do dzielenia rekordów DNS, jeśli Twój dostawca wymaga podzielonej wartości DKIM, oraz generatora polityki DMARC, jeśli potrzebujesz polityki.

Jeden rekord, który większość dostawców każe Ci dodać na początku, jest celowo nieobecny: nie publikujesz rekordu SPF w apeksie swojej domeny. SPF jest oceniany względem domeny envelope-from, na którą CNAME return-path wskazuje nas, więc SPF przechodzi i jest wyrównany bez modyfikacji Twojego apeksu. Jeśli Twój poprzedni dostawca kazał Ci dodać include: do rekordu SPF w apeksie, zostaw go na czas przejścia i usuń po przełączeniu. Nie pomaga ani nie szkodzi poczcie wysyłanej przez nas, a jego usunięcie zwalnia jedno z 10 wyszukiwań DNS, na które pozwala SPF w apeksie. Pełne wyjaśnienie znajdziesz w DKIM, SPF & DMARC.

Możesz opublikować nasze rekordy, gdy rekordy starego dostawcy są wciąż aktywne. Rekord DKIM używa naszego selektora. CNAME'y return-path i śledzenia to nowe nazwy hostów, które sam wybierasz, a Twój istniejący rekord DMARC spełnia warunek w obecnej postaci. Obaj dostawcy uwierzytelniają się równolegle, dopóki nie będziesz gotowy do przełączenia ruchu. Stan domeny jest regionalny, więc zarejestruj domenę w każdym regionie, z którego wysyłasz.

3. Zaimportuj suppresje

Przenieś swoją listę suppresji przed skierowaniem ruchu produkcyjnego przez nas. W przeciwnym razie Twoje pierwsze wysyłki trafią na adresy, które już odbiły się lub zgłosiły skargi u poprzedniego dostawcy, co uszkodzi reputację, którą chcesz chronić.

Wyeksportuj listę od obecnego dostawcy (Twój przewodnik po dostawcy zawiera dokładne endpointy), a następnie dodaj każdy adres u nas za pomocą POST /v1/email/suppressions:

while read -r address; do
  curl -s -X POST https://us1.platform.bird.com/v1/email/suppressions \
    -H "Authorization: Bearer $BIRD_API_KEY" \
    -H "Content-Type: application/json" \
    -d "{\"email\": \"$address\"}"
done < suppressions.txt

Dwie rzeczy, które warto wiedzieć o tej ścieżce importu:

• Importujesz jeden adres na żądanie. API suppresji to CRUD dla pojedynczych wpisów, więc duża lista oznacza iterację po wyeksportowanych adresach. Wywołanie jest idempotentne (201 dla nowego rekordu, 200 z istniejącym rekordem, jeśli adres jest już ręcznie objęty suppresją), więc ponowne uruchomienie częściowego importu jest bezpieczne.
• Zaimportowane adresy otrzymują reason: manual, applies_to: all, co blokuje każdą kategorię, w tym transakcyjną. To surowsze niż natywny rekord skargi, który blokuje tylko wysyłki nietransakcyjne, więc jeśli potrzebujesz zachowania zależnego od kategorii dla konkretnych adresów, zobacz taksonomię przyczyn w Suppresje.

Od teraz nie zarządzasz odbiciami samodzielnie: automatycznie obejmujemy suppresją twarde odbicia i skargi, wysyłając email_suppression.created, aby Twoje systemy mogły odzwierciedlać listę suppresji. Wypisania są rejestrowane jako deklarowane preferencje i odzwierciedlane przez email.unsubscribed i email.list_unsubscribed, a nie przez zdarzenie suppresji.

4. Przełącz webhooki

Zarejestruj endpoint za pomocą POST /v1/webhooks i zapisz go na jawną listę typów zdarzeń. Nasze nazwy zdarzeń mają postać resource.action: email.accepted → email.processed → email.delivered na ścieżce sukcesu, a email.deferred, email.bounced, email.complained, email.rejected, email.opened, email.clicked i para zdarzeń wypisania pokrywają resztę. Tłumaczenie nazw zdarzeń ze słownictwa Twojego obecnego dostawcy znajdziesz w przewodniku po dostawcy. Schematy payloadów poszczególnych zdarzeń są w dokumentacji zdarzeń.

Korelacja przenosi się bez problemów. Każde zdarzenie zawiera identyfikatory email_id, recipient_id i workspace_id. Powtarza też tags i metadata z żądania wysyłki. Dzięki temu odzyskujesz kontekst, który Twój poprzedni dostawca zwracał przez echo payloadu, bez dodatkowego wyszukiwania. Umieść swoje wewnętrzne identyfikatory w metadata przy wysyłce i odczytuj je bezpośrednio z każdego zdarzenia.

Podpisujemy dostawy zgodnie ze specyfikacją Standard Webhooks, używając trzech nagłówków: webhook-id, webhook-timestamp i webhook-signature, z HMAC-SHA256 po {id}.{timestamp}.{raw body}. Jeśli już weryfikujesz dostawy Standard Webhooks z innej platformy, dokładnie ten sam kod weryfikacji zadziała tutaj. W przeciwnym razie przepis na weryfikację, harmonogram ponownych prób i narzędzia do powtórek znajdziesz w Webhooki i zdarzenia. Dostawy mają gwarancję at-least-once i przychodzą w dowolnej kolejności, więc deduplikuj po webhook-id i sortuj po timestamp z payloadu. Twój obecny handler powinien już stosować tę samą dyscyplinę.

5. Zweryfikuj w sandboxie przed przełączeniem

Przed przeniesieniem ruchu produkcyjnego uruchom pełną integrację (przeniesione wywołanie wysyłki, handler webhooków, odzwierciedlanie suppresji) w sandboxie pocztowym. Wysyłki sandboxowe trafiają na magiczne adresy w messagebird.dev i przechodzą przez prawdziwy pipeline produkcyjny: ten sam 202, tę samą sekwencję zdarzeń, te same podpisane dostawy webhooków, bez dotarcia do skrzynki odbiorczej i bez wpływu na Twoją reputację.

Minimalny test dymny przed przełączeniem:

1. Wyślij na delivered@messagebird.dev i sprawdź, czy Twój handler przetwarza email.accepted → email.processed → email.delivered.
2. Wyślij na bounce@messagebird.dev i sprawdź, czy Twoja obsługa odbić reaguje na email.bounced (symulowane odbicia nie zapisują do Twojej listy suppresji, więc adres pozostaje wielokrotnego użytku).
3. Wyślij na suppressed@messagebird.dev i sprawdź, czy obsługujesz email.accepted, a po nim email.rejected, bez email.processed ani zdarzeń dostarczenia po nim. Taki kształt generuje każdy odbiorca objęty suppresją w produkcji; szczegóły rejection_reason: recipient_suppressed znajdują się w rekordzie odbiorcy i zdarzeniach API.
4. Wyślij wiadomość category: "marketing" i potwierdź, że kategoria pojawia się tam, gdzie oczekujesz, w odczycie wiadomości.

Użyj subadresowania +label (bounce+cutover-test@messagebird.dev) do korelowania przypadków testowych. Pełny adres pojawia się w Twoich zdarzeniach. Gdy test dymny przejdzie, przełącz ruch. Skieruj aplikację na nas i zostaw DNS poprzedniego dostawcy na miejscu, dopóki Twoje domeny tutaj nie pokażą capabilities.sending jako zweryfikowane. Obserwuj pierwsze godziny rzeczywistych dostaw w dashboardzie i strumieniu webhooków.

Migracja z konkretnego dostawcy

• SparkPost: transmisje i SMTP, konwersja szablonów, suppresje z zakresem i zdarzenia webhooków
• SendGrid: personalizations → płaski payload, categories/custom_args → tags/metadata, równoważność dropped ↔ email.rejected
• Mailgun: parametry o:*/v:*/h:* → pola pierwszej klasy, eksport odbić/skarg/wypisań
• Amazon SES: SendEmail v2 → jeden endpoint, zestawy konfiguracji → flagi śledzenia per wiadomość, SNS → podpisane webhooki
• Resend: niemal identyczny kształt payloadu, webhooki podpisane przez Svix → Standard Webhooks
• Postmark: odbiorcy oddzieleni przecinkami → tablice, zrzuty suppresji per strumień, niepodpisane webhooki → podpisane
• Brevo: obiekty adresów → zwykłe adresy, dwie osobne listy blokad do wyeksportowania, params → template.parameters
• MailerSend: pięć list suppresji, z których tymczasowa zostaje u dostawcy, personalization → parametry per wysyłkę
• Mailjet: tablica Messages → jeden płaski payload, EventPayload → metadata, eksport listy blokad
• Mandrill: wrapper message i uwierzytelnianie w ciele → płaski payload i uwierzytelnianie bearer, eksport blacklisty odrzuceń

Kolejne kroki

• Wysyłanie e-maili: pełny payload wysyłki, tagi vs metadane, asynchroniczny model 202
• Domeny wysyłkowe: rejestracja, cykl życia weryfikacji, konfiguracja wieloregionowa
• DKIM, SPF & DMARC: co dowodzi każdy rekord i dlaczego SPF w apeksie nie jest wymagany
• Suppresje: przyczyny, kategorie i API zarządzania
• Webhooki i zdarzenia: konfiguracja endpointu, weryfikacja Standard Webhooks, ponowne próby i powtórki
• Zdarzenia: schematy payloadów poszczególnych zdarzeń
• Sandbox testowy: pełna lista magicznych adresów i instrukcje krok po kroku
• Dokumentacja API: schematy żądań i odpowiedzi dla endpointu wysyłki