Po złożeniu zamówienia Twoja aplikacja ma zamówienie i odbiorcę, który potrzebuje potwierdzenia. Używa e-mailowego API, żeby wysłać wiadomość. Zapisuje odpowiedź przy zamówieniu.
Wysłanie to dopiero pierwszy krok. Twoja aplikacja potrzebuje też sposobu na ponowienie żądania. Musi się dowiedzieć, co stało się z wiadomością po wysłaniu.
Jak zdarzenie w aplikacji staje się e-mailem?
Twoja aplikacja zamienia zakończoną transakcję lub żądanie dotyczące konta w operację wysyłki. Serwis e-mail obsługuje dostarczanie po wysłaniu.
Dla potwierdzenia zakupu ta sekwencja wygląda tak:
- Twoja aplikacja potwierdza, że zamówienie jest gotowe do wysłania potwierdzenia.
- Wybiera odbiorcę i przekazuje szczegóły zamówienia jako treść lub wartości szablonu.
- Wysyła żądanie i zapisuje zwrócone ID wiadomości przy zamówieniu.
- Aktualizuje rekord wysyłki, gdy nadejdą zdarzenia dostarczania.
E-mailowe API może obsługiwać zarówno wiadomości transakcyjne, jak i marketingowe. Użycie API nie sprawia, że treści promocyjne stają się transakcyjne, ani nie zdejmuje obowiązków wynikających z CAN-SPAM.
Co oznacza pomyślna odpowiedź?
Pomyślna odpowiedź na wysyłkę rejestruje, co serwis zaakceptował. Jest oddzielna od późniejszej decyzji odbierającego serwera pocztowego.
Status 202 HTTP oznacza, że żądanie zostało przyjęte do przetwarzania. Przetwarzanie nie zostało zakończone, więc ta odpowiedź nie potwierdza dostarczenia.
Dokładna odpowiedź zależy od API. Endpoint wysyłki Bird zwraca na przykład zakolejkowaną wiadomość z id. Zachowaj to ID przy zamówieniu lub zdarzeniu konta, aby późniejsze wyniki można było powiązać z pierwotnym żądaniem.
Jeśli walidacja się nie powiedzie, Bird zwraca 422 z błędem wyjaśniającym, dlaczego żądanie zostało odrzucone.
Jak ponowienia unikają duplikatów wiadomości?
Klucz idempotentności identyfikuje jedną logiczną operację wysyłki w ramach ponowień. API, które go obsługuje, może rozpoznać powtórzone żądanie zamiast tworzyć kolejną wysyłkę.
Na przykład potwierdzenie zamówienia 8472 może użyć klucza receipt/order-8472. Ponów to samo żądanie z tym kluczem, jeśli połączenie zostanie przerwane, zanim otrzymasz odpowiedź.
Nowy klucz identyfikuje inną operację. Twoja aplikacja musi więc zachować oryginalny klucz między własnymi ponowieniami i restartami.
Idempotentność ma okno retencji zdefiniowane przez dostawcę. Po wygaśnięciu tego okna ten sam klucz może zostać przetworzony jako nowe żądanie.
Jak webhooki raportują dostarczanie?
Webhook wysyła zdarzenie do Twojej aplikacji, gdy zmienia się stan wiadomości. Pozwala Twojej aplikacji zaktualizować rekordy po początkowej odpowiedzi API.
Zdarzenia e-mail Bird rozróżniają następujące wyniki:
| Zdarzenie | Co potwierdza |
|---|---|
email.delivered | Odbierający serwer pocztowy przyjął odpowiedzialność za wiadomość |
email.deferred | Tymczasowy błąd dostarczania zostanie ponowiony |
email.bounced | Odbierający serwer odmówił dostarczenia |
email.rejected | Wiadomość nie dotarła do próby dostarczenia |
Akceptacja przez serwer nie potwierdza umieszczenia w skrzynce odbiorczej ani odczytania. Odbierający serwer może też zgłosić późniejsze odrzucenie po zaakceptowaniu wiadomości.
Handler webhooka musi zweryfikować podpis nadawcy i obsłużyć duplikaty dostarczeń. Kontrakt webhooka Bird wymaga deduplikacji za pomocą webhook-id.
Co zmieniają szablony?
Zapisany szablon oddziela wielokrotnie używaną treść wiadomości od wartości dostarczanych przy każdej wysyłce. Twoja aplikacja może przekazać numer zamówienia i nazwę klienta bez składania całej treści e-maila.
Za pomocą szablonów Bird wysyłka wskazuje opublikowany szablon i przekazuje jego parametry. Szablon dostarcza temat i treść.
Szablon nie decyduje, kiedy zamówienie jest gotowe ani czy resetowanie hasła jest autoryzowane. Te decyzje pozostają w Twojej aplikacji.
Czym się różni od przekaźnika SMTP lub platformy marketingowej?
HTTP API i przekaźnik SMTP to różne interfejsy wysyłki. Platforma marketingowa zarządza też pracą kampanijną, taką jak wybór odbiorców i planowanie wysyłki.
| Interfejs lub produkt | Co dostarcza Twoja aplikacja |
|---|---|
| E-mailowe API | Strukturalne żądanie HTTP zawierające odbiorców i treść lub szablon |
| Przekaźnik SMTP | Konwersacja SMTP przekazująca odbiorców i sformatowaną wiadomość e-mail |
| Platforma marketingowa | Treść kampanii, wybór odbiorców i instrukcje wysyłki |
SMTP definiuje wymianę służącą do wysłania wiadomości i jej odbiorców. Może przenosić pocztę transakcyjną i marketingową.
Przekaźnik SMTP Bird i HTTP API korzystają z tego samego produktu dostarczania, włącznie ze zdarzeniami i obsługą suppressji. Wybór SMTP nie usuwa tych możliwości.
Jak wysłać transakcyjny e-mail przez Bird?
Wywołaj POST /v1/email/messages ze zweryfikowanym nadawcą, odbiorcami i treścią inline lub opublikowanym szablonem. Ustaw category: "transactional" dla poczty operacyjnej. Odpowiedź to 202 Accepted z ID wiadomości; dostarczanie odbywa się asynchronicznie.
Użyj Idempotency-Key dla każdej logicznej wysyłki. Bird przechowuje zakończoną odpowiedź przez trzy godziny. Ponowienie po tym oknie może utworzyć kolejną wiadomość, więc prowadź własny rejestr zakończonych zdarzeń biznesowych.
Subskrybuj zdarzenia e-mail i dopasowuj email_id oraz recipient_id do swoich rekordów. Wiadomość z wieloma odbiorcami ma osobne wyniki dla każdego odbiorcy.
Przy wyborze dostawcy lista kontrolna usług transakcyjnego e-maila obejmuje możliwości dostarczania i operacyjne do porównania.