Migracja ze SparkPost

Użyj tego przewodnika, aby przenieść wychodzący e-mail ze SparkPost do Bird. Postępuj zgodnie z główną listą kontrolną migracji, korzystając z poniższych mapowań dla swojej integracji HTTP lub SMTP.

Zanim zaczniesz

Potrzebujesz dostępu do swojego konta SparkPost i subkont, DNS domeny wysyłkowej, konfiguracji aplikacji oraz handlera webhooków. Przygotuj obszar roboczy Bird i klucz API w wybranym regionie. Import rezygnacji wymaga również uprawnienia do zapisu preferences na kluczu.

Zinwentaryzuj nadawców, szablony, snippety, listy odbiorców, suppresje, zaplanowane wysyłki, pule IP i webhooki. Uwzględnij SDK, adaptery pocztowe frameworków, zadania w tle i przepływy przychodzącego e-maila. Zapisuj nowe identyfikatory zasobów w miarę ich tworzenia; identyfikatory i dane uwierzytelniające SparkPost nie działają w Bird. Użyj SDK Bird przy zastępowaniu klienta SparkPost i sprawdź jego ponawianie, limity czasu i paginację.

Jeśli korzystasz z subkont SparkPost, skontaktuj się z nami przed wyborem układu obszarów roboczych. Potwierdź dostępne obszary robocze, uprawnienia, współdzielone zasoby i przepływ provisioningu tenantów. Klucz API obszaru roboczego nie może przełączać tenantów za pomocą X-MSYS-SUBACCOUNT. Zachowaj zawieszonych tenantów i ograniczenia wysyłki specyficzne dla tenantów podczas migracji.

Potwierdź, że Twoje limity planu Bird i limity liczby żądań pokrywają wolumen wysyłki, liczbę zasobów i szczytowy ruch.

Zarejestruj swoje domeny wysyłkowe wcześnie. Zachowaj działające DNS SparkPost i wybierz osobne nazwy hostów return-path i śledzenia tam, gdzie to konieczne. Jeśli rejestracja zgłosi konflikt własności, skontaktuj się ze wsparciem przed usunięciem aktywnej domeny.

Dedykowane IP: skontaktuj się z nami lub ze swoim zespołem konta przed migracją. Poproś nas o potwierdzenie, czy Twoje istniejące IP SparkPost mogą zostać przeniesione do Bird, i uzgodnij konfigurację puli, harmonogram oraz ewentualny warmup. Podaj region konta, adresy IP, nazwy pul i wolumen wysyłki. Utrzymuj swoje obecne IP aktywne do momentu potwierdzenia planu migracji.

Potwierdź wybór puli oraz listy dozwolonych IP lub nazw hostów odbiorców przed przełączeniem. Zakup IP nie zmienia domyślnej puli. Nowo zakupione IP mogą wysyłać nadmiar ruchu przez współdzieloną infrastrukturę podczas warmupu, co ma znaczenie, jeśli odbiorcy przyjmują pocztę tylko z określonych IP.

Przekaż to swojemu agentowi

Wklej to do swojego agenta kodującego w repozytorium aplikacji:

Help me migrate my SparkPost email integration to Bird.
1. Use an existing Bird MCP connection or signed-in CLI. Otherwise follow https://bird.com/docs/ai/set-up-your-agent.md. Append .md to Bird docs URLs to read Markdown.
2. Read https://bird.com/docs/guides/email/migrate/sparkpost.md and https://bird.com/docs/guides/email/migrate.md. Make a read-only inventory of my SparkPost call sites, SDKs, resource IDs, configured URLs, sending domains, and scheduled jobs before editing. Never print API keys.
3. Propose workspace and region mappings. If subaccounts, dedicated IPs, or domain ownership conflicts need a migration plan, use the available Bird tools to open a human email support ticket and return its ID. For CLI usage, read https://bird.com/docs/cli/reference/support-tickets-create.md. Wait for the agreed plan before moving those resources.
4. Follow https://bird.com/docs/guides/email/sending-domains.md; preserve working DNS and show me proposed records. Ask before DNS changes or paid provisioning.
5. Port sending, templates, and webhooks using this guide. Preserve recipient privacy, personalization, and categories. Export suppressions with scope and type; show me the handling before importing or changing preferences.
6. Test using https://bird.com/docs/guides/email/testing-sandbox.md. Show me results and unresolved differences, including tracking, signatures, and correlation.
7. Ask for explicit approval before production cutover. Keep a rollback path; get separate approval before retiring SparkPost resources or credentials.

Zamapuj wywołanie wysyłki

Zastąp POST /api/v1/transmissions wywołaniem POST /v1/email/messages lub POST /v1/email/batches dla niezależnych wiadomości. Przegląd API SparkPost zawiera listę regionalnych hostów i uwierzytelniania. Bird używa https://us1.platform.bird.com lub https://eu1.platform.bird.com, zgodnie z regionem klucza API, z Authorization: Bearer $BIRD_API_KEY.

Transmisja SparkPost może generować oddzielne, spersonalizowane wiadomości e-mail dla swoich odbiorców. Bird współdzieli treść i parametry między odbiorcami jednej wysyłki. Użyj osobnej wiadomości dla każdej personalizacji, opcjonalnie grupując je w partię. Wysyłki tylko do To pozostają adresowane indywidualnie; sprawdź widoczne nagłówki przy dodawaniu kopii Cc/Bcc.

Zamapuj pola transmisji SparkPost:

Dla kopii To/Cc/Bcc jednego e-maila odbuduj grupę odbiorców jednokrotnie. Wyświetlane adresy SparkPost mogą różnić się od odbiorców doręczenia; to, cc i bcc w Bird dodają odbiorców doręczenia. Skopiowanie nagłówka CC SparkPost do cc każdej rozwiniętej wiadomości może spowodować wysłanie duplikatów. Zweryfikuj widoczne nagłówki i liczbę odbiorców przed przełączeniem.

Sprawdź limity pól wysyłki, planowanie i zasady dotyczące załączników. Zaktualizuj identyfikatory obrazów inline i pasujące odniesienia cid: zgodnie z zasadami Bird. Skonfiguruj ścieżkę zwrotną i domenę śledzenia na domenie.

Pola wysyłki HTTP w Bird nie obejmują content.email_rfc822, content.amp_html ani options.inline_css SparkPost. Odbuduj surowe wiadomości z obsługiwanymi polami, zapewnij fallbacki HTML/text dla AMP i wstaw CSS inline przed wysłaniem HTML. SMTP parsuje i odbudowuje obsługiwane części wiadomości; zweryfikuj otrzymany MIME, jeśli zależy ci na jego dokładnej strukturze. Parametry MIME załączników, takie jak kalendarzowy method lub tekstowy charset, nie są zachowywane.

Dla zaplanowanych wiadomości API, Bird utrwala wersję szablonu, język i parametry w momencie przyjęcia żądania. Późniejsze edycje szablonu nie aktualizują tej wiadomości. Aby ją zmienić, anuluj zaplanowaną wiadomość przed rozpoczęciem przetwarzania, a następnie wyślij zamiennik. Zachowaj grupę identyfikatorów wiadomości Bird, jeśli chcesz zastąpić anulowanie oparte na kampaniach w SparkPost.

Ustaw BIRD_API_KEY na swój klucz Bird. Ten przykład sandbox nie wymaga zweryfikowanej domeny i nie trafia do żadnej prawdziwej skrzynki. Dla klucza EU użyj https://eu1.platform.bird.com:

curl --fail-with-body https://us1.platform.bird.com/v1/email/messages \
  -H "Authorization: Bearer $BIRD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "onboarding@messagebird.dev",
    "to": ["delivered@messagebird.dev"],
    "subject": "Your receipt",
    "text": "Thanks for your order, {{ first_name }}.",
    "parameters": {"first_name": "Alex"},
    "category": "transactional",
    "metadata": {"order_id": "order_123"},
    "tags": [{"name": "mailstream", "value": "receipts"}]
  }'

Oczekuj 202 Accepted i identyfikatora wiadomości em_. Zapisz ten identyfikator i śledź wyniki dla odbiorców przez zdarzenia. Przyjęcie nie oznacza doręczenia: odbiorca objęty suppresją może zostać przyjęty, a następnie odrzucony. Zaktualizuj parsowanie odpowiedzi, obsługę błędów i idempotentne ponowne próby wraz z wywołaniem wysyłki.

W przypadku partii odczytaj tablicę data i zapisz ID każdej wiadomości w swoim rejestrze wysyłek. Bird waliduje partię przed umieszczeniem w kolejce: jedna nieprawidłowa wiadomość może spowodować odrzucenie całego żądania. Podziel duże transmisje, aby zmieścić się w limitach partii, i stosuj reguły ponownych prób Bird, gdy odpowiedź jest niejednoznaczna.

Nadaj każdemu odrębnemu żądaniu lub fragmentowi partii własny stabilny klucz idempotentności. Okno powtórzenia Bird różni się od okna SparkPost; przechowuj rejestr wysyłek aplikacji dłużej niż to okno, aby zapobiec duplikatom podczas przełączania lub wycofywania.

Przenieś nadawców SMTP

Użyj ustawień połączenia SMTP Bird, nazwy użytkownika bird i klucza API z włączonym wysyłaniem e-maili. Sprawdź region, TLS i konfigurację klucza.

Skonwertuj opcje X-MSYS-API SparkPost przed usunięciem nagłówka. Ustaw domyślne wartości kategorii, tagów, śledzenia i puli w konfiguracji SMTP Bird. Te ustawienia obowiązują na klucz API; użyj oddzielnych skonfigurowanych kluczy lub HTTP, gdy różnią się między wiadomościami. Użyj HTTP do metadanych lub parametrów szablonu na poziomie wiadomości.

Umieść każdego odbiorcę doręczenia w kopercie SMTP, widocznych odbiorców w nagłówkach MIME To/Cc, a odbiorców Bcc tylko w kopercie. Zinwentaryzuj X-MSYS-API.archive oddzielnie: kopie archiwalne SparkPost zachowują adresy URL śledzenia oryginalnego odbiorcy, więc zwykłe Bcc nie jest równoważne. Zwaliduj zamiennik przed przełączeniem tego przepływu.

Skopiuj swoje efektywne ustawienia śledzenia jawnie: nieskonfigurowany klucz SMTP Bird włącza śledzenie otwarć i kliknięć, podczas gdy domyślne ustawienia SparkPost różnią się w zależności od konta. Ustaw też kategorię: Bird SMTP domyślnie oznacza wiadomości jako transakcyjne, a inline HTTP jako marketingowe. Nadawcy newsletterów potrzebują marketing na obu ścieżkach.

Przy ponownych próbach SMTP użyj ponownie klucza idempotentności, koperty i dokładnie tych samych bajtów MIME. Ponowne wygenerowanie Date, Message-ID lub granic MIME zmienia ładunek i może uniemożliwić bezpieczną ponowną próbę.

Skonwertuj szablony

Wyeksportuj wersje, które faktycznie wysyłasz, przez Templates API SparkPost: wylistuj za pomocą GET /api/v1/templates?draft=false, a następnie pobierz treść za pomocą GET /api/v1/templates/{id}?draft=false. W razie potrzeby zapisz wersje robocze oddzielnie. Uwzględnij w inwentaryzacji szablony współdzielone z subkontami i powiązane snippety.

Język szablonów SparkPost i składnia Liquid Bird różnią się. Skonwertuj warunki, pętle, wartości domyślne i zagnieżdżone wartości. Rozwiąż nadpisania odbiorcy i metadane używane do renderowania jako jawne parametry. Na przykład {{ if ... }} staje się {% if ... %}. Sama wspólna składnia {{ name }} nie zapewnia kompatybilności.

Rozwiń snippety przed publikacją; Liquid Bird nie obsługuje include ani render. W przypadku przechowywanych szablonów zastąp zewnętrzne odwołania, takie jak {{ user.name }}, płaskimi parametrami, takimi jak {{ user_name }}. Jeśli wstawiasz dynamiczny HTML przez parametry SparkPost, wyrenderuj go w swojej aplikacji i prześlij gotową treść bez inline parameters; zwykłe wartości parametrów HTML są escapowane.

Utwórz, wyświetl podgląd i opublikuj szablon Bird, a następnie postępuj zgodnie z wysyłaniem z szablonem. Przenieś efektywnego nadawcę, Reply-To i niestandardowe nagłówki ze SparkPost do żądania wysyłki; szablony Bird dostarczają treść.

W przypadku inline Liquid dołącz parameters, nawet {}; pominięcie pozostawia tokeny bez zmian. Zweryfikuj brakujące wartości, escapowanie i adresy URL.

Zastąp placeholdery rezygnacji z subskrypcji za pomocą {{ bird.unsubscribe_url }}. Bird dostarcza nagłówki rezygnacji z subskrypcji marketingowej; usuń niestandardowe nagłówki List-Unsubscribe i List-Unsubscribe-Post z wysyłek marketingowych, aby uniknąć odrzucenia 422.

Linki rezygnacji z subskrypcji Bird wyłączają adres z e-maili marketingowych w całym obszarze roboczym. Linki te nie zapewniają rezygnacji specyficznych dla listy. Sprawdź to zachowanie, jeśli Twoja integracja SparkPost oferuje oddzielne subskrypcje.

Przenieś listy odbiorców

Wyeksportuj każdą przechowywaną listę odbiorców z GET /api/v1/recipient-lists/{id}?show_recipients=true, aby uwzględnić członkostwo i personalizację. Utwórz docelowe grupy odbiorców i zarejestruj właściwości kontaktów przed importem. Sprawdź wynik każdego importu i uzgodnij liczby członków.

Właściwości kontaktów należą do kontaktu we wszystkich jego grupach odbiorców. Jeśli ten sam adres ma różne dane podstawieniowe w kilku listach SparkPost, uzgodnij te wartości przed importem, aby uniknąć ich nadpisania. Właściwości kontaktów Bird mają typy skalarne; przechowuj personalizację specyficzną dla listy lub o złożonej strukturze w swojej aplikacji, gdy nie można jej bezpiecznie odwzorować.

Używaj rozgłoszeń, gdy opublikowany szablon może być wypełniony z właściwości kontaktów. Członkostwo w grupie odbiorców jest rozwiązywane w momencie rozpoczęcia wysyłki i obowiązują limity wysyłki i współbieżności rozgłoszeń. Używaj niezależnych wiadomości wsadowych dla parametrów specyficznych dla żądania lub ustalonej migawki odbiorców. Zweryfikuj obsługę zgód i suppresji przed aktywacją zmigrowanej listy.

Wyeksportuj suppresje

Wyeksportuj przed rozpoczęciem wysyłki produkcyjnej. Zacznij od GET /api/v1/suppression-list?cursor=initial&types=transactional,non_transactional,open_tracking, a następnie kontynuuj paginację do końca. Zapisz kompletne rekordy, w tym typ, źródło, ID listy, subkonto i znaczniki czasu. Użyj X-MSYS-SUBACCOUNT: 0 dla konta głównego i ID każdego subkonta dla jego własnej listy. Zobacz Suppression List API SparkPost.

Sklasyfikuj rekordy według typu, źródła i zakresu przed użyciem pętli importu z głównego przewodnika. POST /v1/email/suppressions Bird przyjmuje email i tworzy ręczną blokadę na poziomie całego obszaru roboczego dla obu kategorii:

• Adresy zablokowane przed odbieraniem e-maili: zaimportuj te, które powinny być zablokowane we wszystkich kategoriach. Zachowaj oryginalny eksport do uzgodnienia; zaimportowane rekordy zawierają ręczny powód Bird.
• Rezygnacje marketingowe na poziomie konta: użyj POST /v1/preferences z channel: "email", adresem w handle, status: "revoked" i coverage: "non_transactional". Ustaw source: "sparkpost-migration" na potrzeby uzgadniania. Najpierw sprawdź istniejące preferencje Bird i zachowaj bardziej restrykcyjne ograniczenia; po każdym zapisie sprawdź applied i zwróconą preferencję.
• Ograniczenia specyficzne dla listy lub wyłącznie transakcyjne: zachowaj ich zakres w logice kwalifikacji wysyłki swojej aplikacji. Preferencje e-mail Bird obowiązują na poziomie całego kanału i nie mogą odwzorować tych zakresów. Ręczna suppresja może również zablokować resetowanie haseł. Wstrzymaj dotknięty ruch do czasu zweryfikowania zastępczego rozwiązania.
• Rezygnacje ze śledzenia otwarć: ustaw track_opens: false dla wiadomości niezależnej, oprócz wszelkich ograniczeń wysyłki. Dla SMTP użyj klucza z wyłączonym śledzeniem otwarć lub użyj HTTP do sterowania na poziomie pojedynczej wiadomości.

Powyższe żądanie preferencji rejestruje ograniczenie w momencie importu. Zachowaj oryginalne znaczniki czasu ze SparkPost w eksporcie i uzgodnij wszelkie późniejsze zgody przed zapisem. Uzgodnij zaimportowane rekordy i nieudane zapisy, a następnie przetestuj obie kategorie. Synchronizuj nowe rezygnacje i suppresje, gdy obaj dostawcy wysyłają wiadomości. Po przełączeniu kontynuuj stosowanie rezygnacji z wcześniej dostarczonych wiadomości SparkPost w Bird. Zobacz Suppresje, aby poznać natywną obsługę odrzuceń i skarg.

Mapowanie zdarzeń webhooków

SparkPost wysyła zbatchowane zdarzenia webhooków w ramach wrapperów msys. Bird dostarcza jedno zdarzenie na żądanie z type, timestamp i data. Zarejestruj endpoint Bird z jawnymi subskrypcjami zdarzeń i weryfikacją sygnatury. Utrzymuj handler SparkPost aktywny dla pozostałego ruchu.

Bezpośrednie wysyłki API i SMTP emitują email.accepted przed przetworzeniem. Broadcasty rejestrują akceptację w zdarzeniach API i logu e-mail, ale pomijają ten webhook. SparkPost policy_rejection, generation_failure i generation_rejection mapują się na email.rejected; sprawdź rejection_reason. Deduplikuj otwarcia osobno, licząc unikalne zaangażowanie.

Użyj data.email_id i data.recipient_id do korelacji Bird i przekazuj własne identyfikatory w metadata. Zastąp obsługę batch-ID ze SparkPost regułami deduplikacji i kolejności webhooków Bird. Przeczytaj szczegóły zwrotki, zanim zdecydujesz, czy adres powinien zostać objęty suppresją; klasyfikacja zwrotek rozróżnia trwałe błędy adresu od tymczasowych lub wynikających z polityki.

Zachowaj historię raportowania

Wyeksportuj historię zdarzeń SparkPost i raporty zagregowane, których potrzebujesz, zanim upłyną ich okna retencji. Przeiteruj paginację zdarzeń do końca i zachowaj identyfikatory dostawcy, zakres konta/subkonta, znaczniki czasu i filtry raportowania. Zbieraj spóźnione zdarzenia w trakcie okresu współistnienia i przechowuj historię SparkPost w osobnym archiwum.

Zapisz punkt odniesienia dla każdego strumienia wysyłek. Porównaj pasujące populacje odbiorców i okna raportowania, a następnie sprawdź definicje metryk: akceptacja przez dostawcę, dostarczenie na serwer odbiorcy, unikalne zaangażowanie i wstępnie pobrane otwarcia to różne miary. Sama zgodność nazw metryk nie oznacza porównywalnych wskaźników.

Zmigruj pocztę przychodzącą osobno

Jeśli używasz webhooków relay SparkPost, postępuj zgodnie z przewodnikiem Odbieranie e-maili. Webhook email.received w Bird dostarcza inbound_message_id; pobieraj treść, załączniki lub surowy MIME przez API zamiast oczekiwać pełnej wiadomości w webhooku. Przetestuj swój handler z adresem przekierowania Bird, a następnie skonfiguruj odbieranie na domenie przed zmianą rekordów MX. Zweryfikuj routing odpowiedzi po zmianie DNS i zarchiwizuj treści, które potrzebujesz poza okresem przechowywania odbieranych wiadomości w Bird.

Weryfikacja i przełączenie

1. Zweryfikuj zdolność wysyłania każdej domeny. Uruchom test dymny w sandboxie i przypadki skarg. Upewnij się, że podpisane zdarzenia docierają do Twojego handlera, są powiązane z właściwą wiadomością i że obsługujesz zduplikowane dostarczenia. Zdarzenia z sandboxa nie dowodzą dostarczenia do skrzynki, renderowania ani śledzenia.
2. Wyślij ze zweryfikowanej domeny do kontrolowanych, rzeczywistych skrzynek odbiorczych. Sprawdź personalizację, widoczność To/Cc/Bcc, załączniki, uwierzytelnianie i śledzenie. Przetestuj wypisanie: marketing musi się zatrzymać, a kwalifikujące się wiadomości transakcyjne powinny dalej docierać. Osobno przetestuj, czy blokady dla wszystkich kategorii odrzucają oba typy. Nie łącz tych testów z symulowanymi wynikami z sandboxa.
3. Przypisz oczekujące zaplanowane wysyłki do jednego dostawcy. Opróżnij kolejkę lub anuluj oryginał przed ponownym utworzeniem go u innego dostawcy. Prowadź w aplikacji rejestr, który dostawca przyjął każdą logiczną wysyłkę, aby ponowne próby lub wycofanie nie spowodowały wysłania drugiej kopii.
4. Przenieś kontrolowaną część ruchu i monitoruj metryki dostarczania oraz przetwarzanie webhooków. W przypadku dedykowanych IP postępuj zgodnie z planem migracji uzgodnionym z naszym zespołem, w tym z ewentualnym rozgrzewaniem. Zwiększaj ruch po tym, jak zaobserwowane wyniki spełnią Twoje wymagania dotyczące dostarczania.
5. Jeśli walidacja się nie powiedzie, wstrzymaj ruch Bird, którego dotyczy problem, i kieruj nowe wysyłki przez zachowaną ścieżkę SparkPost z aktualnymi wypisaniami. Uzgodnij niejednoznaczne wysyłki przed ponownym ich wysłaniem. Wycofaj stare poświadczenia, webhooki i DNS po rozliczeniu kolejek i spóźnionych zdarzeń; zachowaj działające stare linki śledzące i wypisania dla wcześniej dostarczonych wiadomości.

Jeśli uwierzytelnianie się nie powiedzie, sprawdź token bearer Bird i region. Jeśli import preferencji zwraca 403, sprawdź uprawnienie zapisu preferences na kluczu przed kontynuowaniem. Jeśli personalizacja renderuje się nieprawidłowo, zbadaj konwersję Liquid i parametry. Jeśli wiadomości transakcyjne są nieoczekiwanie odrzucane, sprawdź zaimportowane ręczne suppresje. Użyj dziennika e-mail i szczegółów zdarzeń, aby zweryfikować każdą poprawkę.

Następne kroki

• Wysyłanie e-maili: pola ładunku, personalizacja i asynchroniczne wyniki
• Szablony e-mail: podgląd, publikacja i obsługa Liquid
• Suppresje: przyczyny suppresji i zarządzanie
• Webhooki i zdarzenia: sygnatury, ponawianie i odtwarzanie