Migracja z MailerSend
Ta strona mapuje payload wysyłki, listy blokad i webhooki MailerSend na Bird. Postępuj zgodnie z głównym przewodnikiem migracji po kolei i użyj tych mapowań w krokach 1, 3 i 4.
MailerSend prowadzi pięć list blokad, z których jedna jest z założenia tymczasowa. Przeczytaj Eksport list blokad przed krokiem 3: zaimportowanie tej jednej zamienia 72-godzinne wstrzymanie w trwałą blokadę.
Przekaż to swojemu agentowi
Wklej to do Claude Code, Cursora lub Codex. Agent przetwarza tę stronę na tle Twojego repozytorium, korzystając z dowolnej powierzchni Bird, jaką 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 MailerSend 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/mailersend.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 MailerSend usage in this repository before you change anything: calls to /v1/email and any SDK wrappers around them, whether I send with template_id and personalization or with html, 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 MailerSend 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. MailerSend keeps five lists under /v1/suppressions: hard bounces, spam complaints, unsubscribes and the blocklist are the four to carry over. Do NOT import the On Hold list: it is a temporary 72-hour hold that MailerSend clears by itself, and importing it would suppress those addresses permanently. 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. Both providers sign with HMAC-SHA256, so this is a re-implementation rather than new code: MailerSend sends one Signature header, Bird follows the Standard Webhooks scheme with webhook-id, webhook-timestamp and webhook-signature, and the signed string is constructed differently. Keep the constant-time comparison. 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 MailerSend path is a separate step that comes later: ask me again and wait for me to reply with the words retire the MailerSend 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.Mapowanie wywołania wysyłki
POST /v1/email MailerSend i nasz POST /v1/email/messages mają podobną strukturę. Różnice wymagające zmian w kodzie to limit tagów i sposób przekazywania danych per odbiorca.
| Co robi | MailerSend | Bird |
|---|---|---|
| Nadawca | from ({email, name}) | from |
| Odbiorcy | to (maks. 50), cc / bcc (maks. 10 każdy) | to / cc / bcc (tablice) |
| Temat | subject (maks. 998 znaków) | subject |
| Treść | html / text | html / text (co najmniej jedno) |
| Reply-to | reply_to ({email, name}) | reply_to (tablica) |
| Własne nagłówki | headers ({name, value}, wyższe plany) | headers (obiekt string → string) |
| Etykiety filtrujące | tags (tablica stringów, maks. 5) | pary tags: {name, value} |
| Zapisany szablon | template_id + personalization | template + template.parameters (patrz niżej) |
| Załączniki | attachments (content, filename, disposition, id) | attachments |
| Planowanie | send_at (do 72 godzin naprzód) | scheduled_at |
| Bulk precedence | precedence_bulk | (brak odpowiednika, patrz niżej) |
| Kategoria | (brak) | category: marketing (domyślnie) lub transactional |
| Wątek | in_reply_to | headers |
Limity pól i wartości domyślne (liczba odbiorców, limity tagów i metadanych) znajdziesz w Wysyłanie e-maili.
Uwagi do portowania:
- Adresy tam są obiektami, a u nas stringami. {"email": "a@x.com", "name": "A"} staje się "A <a@x.com>" lub po prostu "a@x.com", zarówno dla from, to, cc, bcc, jak i reply_to.
- tags to proste stringi z limitem pięciu. Nasze tagi to pary. Tag taki jak "welcome" staje się {"name": "category", "value": "welcome"}. Wybierz stabilny name, żeby Twoje dashboardy filtrowały tak, jak robiły to statystyki tagów w MailerSend.
- personalization to dane szablonu per odbiorca. Jest to tablica indeksowana adresem e-mail odbiorcy. Nasz template.parameters dotyczy całej wysyłki, więc wiadomość, której treść faktycznie różni się per odbiorca, wymaga osobnej wysyłki na odbiorcę lub osobnego wpisu w batch. Jeśli Twoja tablica personalization zawiera te same wartości dla każdego odbiorcy, można ją zwinąć do jednego obiektu template.parameters.
- Kontekst zwrotny nie ma odpowiednika w MailerSend do skopiowania. Jeśli rekonstruowałeś kontekst z tags, użyj zamiast tego metadata: zwracamy go w każdym zdarzeniu webhooka obok email_id/recipient_id i nie ma limitu pięciu wpisów.
- precedence_bulk nie ma odpowiednika, a category nim nie jest. precedence_bulk ustawia nagłówek Precedence: bulk, który prosi autorespondera i agentów out-of-office o milczenie. Nasz category decyduje, które rekordy blokad i preferencje wypisania mogą zablokować wiadomość, i nic więcej. Ustawienie category w jego miejsce zmienia zachowanie blokad i nie wpływa na autoresponderów. Jeśli potrzebujesz tego nagłówka, zwróć uwagę, że headers odrzuca nazwy adresowe i nazwy platform, ale nie ten nagłówek.
- Własne nagłówki i list_unsubscribe są w MailerSend uzależnione od planu. Jeśli Twój plan ich nie obejmował, u nas są dostępne; zobacz wysyłanie e-maili i kategorie, żeby dowiedzieć się, jak obsługujemy list-unsubscribe w mailach marketingowych.
Eksport list blokad
MailerSend prowadzi pięć list w ramach /v1/suppressions, po jednym endpoincie na listę. Cztery są stałe i powinny zostać przeniesione; piąta nie.
Wyeksportuj i przepuść przez pętlę importu:
- Twarde odbicia, na przykład GET https://api.mailersend.com/v1/suppressions/hard-bounces
- Zgłoszenia spamu
- Wypisania
- Blocklist, adresy i wzorce dodane ręcznie
Nie importuj listy On Hold. Opis MailerSend mówi, że przechowuje ona adresy, które "have soft bounced 5 times within 30 days", które "these emails will be blocked for 72 hours" i które są następnie "automatically removed from the list". To okres wyciszenia, który dostawca sam kasuje, więc import zamienia tymczasowe wstrzymanie w trwałą blokadę i po cichu zatrzymuje wysyłkę na adresy, które miały zostać zwolnione. Nasz odpowiednik tego zachowania to odroczenie, które obsługujemy na podstawie bieżących wyników dostarczania, a nie z importowanej listy.
Typy list MailerSend mapują się na nasze powody hard_bounce, complaint i manual; Blokady zawierają pełną taksonomię.
Tłumaczenie zdarzeń webhookowych
| Wynik | MailerSend | Bird |
|---|---|---|
| Zaakceptowano/przetworzono | activity.sent | email.accepted → email.processed |
| Dostarczono | activity.delivered | email.delivered |
| Tymczasowa awaria | activity.soft_bounced / activity.deferred | email.deferred |
| Trwałe odbicie | activity.hard_bounced | email.bounced / email.out_of_band_bounce |
| Zgłoszenie spamu | activity.spam_complaint | email.complained |
| Otwarcie | activity.opened / activity.opened_unique | email.opened |
| Kliknięcie | activity.clicked / activity.clicked_unique | email.clicked |
| Wypisanie | activity.unsubscribed | email.unsubscribed / email.list_unsubscribed |
| Tymczasowe wstrzymanie | recipient.on_hold_added / ..._removed | (brak odpowiednika; patrz wyżej) |
Dwie różnice decydują o tym, jak bardzo zmieni się Twój handler.
Obie strony podpisują za pomocą HMAC-SHA256, więc to reimplementacja, a nie nowy kod. MailerSend wysyła pojedynczy nagłówek Signature zawierający hash payloadu obliczony z użyciem signing secret danego webhooka. My stosujemy schemat Standard Webhooks, który używa webhook-id, webhook-timestamp i webhook-signature i podpisuje string zbudowany z id, znacznika czasu i ciała żądania, więc znacznik czasu daje Ci jednocześnie ochronę przed powtórkami. Zachowaj porównanie w stałym czasie, które już masz, i zamień konstrukcję; przepis znajdziesz w Webhooki i zdarzenia.
MailerSend rozróżnia otwarcia i kliknięcia od ich unikalnych wariantów. My nie. activity.opened i activity.opened_unique przychodzą jako email.opened, więc handler liczący tylko wariant unikalny musi sam deduplikować po recipient_id. Nasze zdarzenia dostarczania dotyczą pojedynczego 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 kroki są niezależne od dostawcy.
Następne kroki
- Domeny nadawcze: 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
- Blokady: potwierdź zaimportowaną listę i sposób, w jaki ją utrzymujemy od tego momentu
Powiązane zasoby
Kontynuuj z dokumentacją, przewodnikami i przykładami dotyczącymi tego tematu. Zasoby są w języku angielskim.
Obejrzyj przewodnikGetting started with emailPoznaj możliwościEmailPodążaj ścieżką naukiBuild your first integrationPrzewodnik wdrożeniowySend your first email
Wypróbuj ćwiczenie i uzyskaj brief wdrożeniowy