Twoja aplikacja wysyła ustrukturyzowane dane do endpointu HTTP i otrzymuje odpowiedź z wynikiem wysyłki lub błędem. To żądanie i odpowiedź stanowią powierzchnię roboczą API e-mail.
Co obsługuje API e-mail?
Endpoint wysyłki przyjmuje odbiorców, temat oraz treść tekstową lub HTML. Może też przyjmować nagłówki, tagi, szablony i załączniki, jeśli dostawca je obsługuje.
Endpoint zdarzeń lub webhook raportuje, co wydarzyło się po przyjęciu wiadomości. Typowe zdarzenia to dostarczenie, odrzucenie, skarga, otwarcie i kliknięcie. API odbiorcze zamienia przychodzącą pocztę na ustrukturyzowane wiadomości dla Twojej aplikacji, zamiast zmuszać Cię do odpytywania skrzynki pocztowej.
Czym API e-mail różni się od SMTP?
SMTP wymaga od Twojej aplikacji otwarcia połączenia, uwierzytelnienia, wysłania poleceń i odczytania kodów odpowiedzi. API e-mail korzysta zamiast tego z żądań HTTP, dzięki czemu biblioteka kliencka może obsłużyć ponowne użycie połączeń, kodowanie JSON, ponawianie prób i parsowanie odpowiedzi.
Wybierz API, gdy Twoja aplikacja już korzysta z HTTP, potrzebuje ustrukturyzowanych zdarzeń lub działa w środowisku, w którym otwieranie połączeń SMTP jest kłopotliwe. Wybierz relay SMTP, gdy istniejąca biblioteka pocztowa lub serwer pocztowy już obsługuje SMTP. Obie ścieżki mogą dostarczyć tę samą wiadomość.
| Zadanie | API wysyłki | Relay SMTP | API skrzynki |
|---|---|---|---|
| Wysłanie wiadomości | Tak | Tak | Odpowiedź lub nowa wiadomość |
| Odbiór sparsowanej poczty | Niektórzy dostawcy | Nie | Tak |
| Odczyt historii konwersacji | Niektórzy dostawcy | Nie | Tak |
| Obserwacja dostarczenia | Zdarzenia lub webhooki | Kody odpowiedzi i zdarzenia | Status wiadomości i zdarzenia |
Produkty używają terminu API e-mail na oznaczenie różnych zestawów funkcji. Sprawdź schemat dostawcy, zanim założysz, że jedno API obejmuje każdy wiersz.
Co powinno zawierać żądanie do API?
Wyślij pola wymagane przez Twojego dostawcę. Zapisz zwrócony identyfikator wiadomości. Używaj własnego klucza idempotentności, gdy ponowienie próby nie może spowodować duplikatu wysyłki. Waliduj odbiorców przed wysłaniem. Przechowuj sekrety na swoim serwerze.
Przykładowe żądanie transakcyjne zawiera from, to, subject, text, category: transactional oraz klucz idempotentności przechowywany na serwerze. Przed wysłaniem użyj zweryfikowanej domeny nadawczej.
Odpowiedź HTTP oznacza, że usługa przyjęła żądanie. Zdarzenia dostarczenia, odrzucenia i skargi przychodzą później, więc odpowiedź o przyjęciu nie potwierdza dostarczenia do skrzynki odbiorczej.
Używaj webhooków do późniejszych zdarzeń, zamiast traktować przyjęte żądanie jako dowód dotarcia wiadomości do skrzynki odbiorczej. Zdarzenia dostarczenia i skargi opisują, co wydarzyło się po przyjęciu.
Jak wysyłać za pomocą Bird?
Wywołaj createEmailMessage API Bird z kluczem API obszaru roboczego, nadawcą, odbiorcami, treścią i opcjonalnymi metadanymi. Przewodnik wysyłki e-mail opisuje pola żądania i odpowiedzi.
Aby obsługiwać odpowiedzi i pocztę przychodzącą, utwórz skrzynkę i konsumuj jej zdarzenia wiadomości i dostarczenia. Przewodnik po skrzynkach opisuje te endpointy i nazwy webhooków.
Podsumowanie
- API e-mail udostępnia wysyłkę i zdarzenia wiadomości przez HTTP.
- Odpowiedź potwierdza przyjęcie przez API, nie dostarczenie do skrzynki odbiorczej.
- Klucze idempotentności umożliwiają bezpieczne ponawianie prób.
- Bird udostępnia API wysyłki i skrzynek z przewodnikami dla każdej ścieżki.