MailerSend (na własnym serwerze z API)

MailerSend udostępnia API do wysyłek transakcyjnych, które można wywoływać z własnych aplikacji i serwerów.

MailerSend jako zewnętrzna usługa wywoływana z własnego serwera

MailerSend jest usługą do wysyłania wiadomości e-mail przez interfejs programistyczny API. Aplikacja uruchomiona na własnym serwerze nie instaluje całego silnika pocztowego MailerSend lokalnie. Serwer przygotowuje żądanie HTTP, a następnie przekazuje je do infrastruktury MailerSend przez szyfrowane połączenie HTTPS. Oznacza to, że własny serwer może odpowiadać za logikę aplikacji, dane zamówienia, generowanie treści i moment wywołania, natomiast sama obsługa wysyłki odbywa się po stronie zewnętrznej usługi.

Integracja służy przede wszystkim do wiadomości transakcyjnych, czyli takich, które wynikają z działania aplikacji. Mogą to być na przykład potwierdzenia rejestracji, informacje o zmianie hasła, potwierdzenia zamówienia, komunikaty o zmianie statusu zgłoszenia albo automatyczne powiadomienia systemowe. Wysyłanie powinno być wywoływane przez kod aplikacji po wystąpieniu określonego zdarzenia, a nie przez ręczne uruchamianie programu pocztowego na serwerze.

Żądanie HTTP, uwierzytelnianie i format wiadomości

MailerSend udostępnia Email API pod adresem https://api.mailersend.com/v1/email. Własna aplikacja wysyła tam żądanie HTTP z danymi wiadomości w formacie JSON. Uwierzytelnianie odbywa się za pomocą nagłówka Authorization zawierającego wartość w postaci Bearer oraz tokenu API. Żądanie powinno również określać typ danych JSON w nagłówku Content-Type: application/json.

Treść żądania może zawierać nadawcę, odbiorców, temat, wersję tekstową i HTML wiadomości, a także identyfikator szablonu lub dane używane do wstawiania zmiennych. Adres nadawcy musi być związany z domeną skonfigurowaną w koncie MailerSend. Przed wysyłką domena nadawcza wymaga weryfikacji przy użyciu odpowiednich rekordów DNS, ponieważ usługa musi potwierdzić możliwość legalnego używania danego adresu i domeny do wysyłki.

Token API należy przechowywać po stronie serwera, na przykład w zmiennej środowiskowej albo w bezpiecznym magazynie konfiguracji. Nie powinien być umieszczany w kodzie JavaScript wysyłanym do przeglądarki, w publicznym repozytorium ani bezpośrednio w treści strony. Aplikacja powinna rozróżniać błędy uwierzytelniania, nieprawidłowe dane żądania, przekroczenie limitu oraz niedostępność usługi, ponieważ każda z tych sytuacji wymaga innego sposobu obsługi.

Asynchroniczna wysyłka i kontrola statusu wiadomości

Wywołanie Email API rozpoczyna asynchroniczne przetwarzanie wiadomości. Otrzymanie poprawnej odpowiedzi HTTP oznacza przyjęcie żądania przez API, ale nie jest równoznaczne z dostarczeniem wiadomości do skrzynki odbiorcy. Aplikacja nie powinna więc oznaczać operacji biznesowej jako zakończonej wyłącznie na podstawie faktu, że serwer API zwrócił odpowiedź bez błędu.

Do śledzenia dalszego przebiegu można wykorzystać webhooki. MailerSend wysyła powiadomienia HTTP między innymi dla zdarzeń activity.sent, activity.delivered i activity.soft_bounced. Własny serwer odbiera takie żądania pod publicznym adresem HTTPS i aktualizuje zapisany status wiadomości. Endpoint webhooka powinien szybko zwrócić kod z zakresu 2xx, a cięższe operacje, takie jak aktualizacja wielu rekordów lub powiadomienie użytkownika, mogą zostać wykonane później.

Żądania webhooków zawierają nagłówek Signature. Podpis należy sprawdzać na podstawie niezmienionego surowego ciała żądania oraz sekretu przypisanego do webhooka. MailerSend dokumentuje weryfikację z użyciem HMAC-SHA256; porównanie obliczonego podpisu z otrzymaną wartością powinno odbywać się w sposób odporny na ataki czasowe. Dopiero po pozytywnej weryfikacji aplikacja powinna przetwarzać dane o wysłaniu, dostarczeniu albo odbiciu wiadomości.

Diagnostyka integracji MailerSend w aplikacji serwerowej

Sprawdzanie problemu należy rozpocząć od logów aplikacji i odpowiedzi HTTP zwracanej przez API. Warto zapisać czas żądania, identyfikator operacji, kod odpowiedzi oraz bezpiecznie zanonimizowany adres odbiorcy. Nie należy logować pełnego tokenu API, sekretu podpisu webhooka ani całej treści wiadomości, jeżeli może zawierać dane użytkownika. Kod 401 lub 403 wskazuje zwykle na problem z tokenem albo uprawnieniami, a błąd walidacji danych oznacza niepoprawną strukturę JSON, adres nadawcy lub konfigurację domeny.

Jeżeli API przyjmuje wiadomość, lecz odbiorca jej nie widzi, trzeba oddzielić etap przyjęcia żądania od etapu dostarczenia. Pomocne są statusy webhooków, identyfikator wiadomości oraz sprawdzenie folderów spamu i konfiguracji domeny nadawczej. W aplikacji trzeba także zabezpieczyć się przed wielokrotnym wysłaniem po ponowieniu żądania. Przerwa sieciowa może wystąpić po stronie klienta już po przyjęciu wiadomości przez API, dlatego mechanizm retry powinien uwzględniać idempotencję, rejestrować próby i nie tworzyć bez kontroli duplikatów.

W przypadku serwisu laptopów lub komputerów diagnostyka może obejmować konfigurację środowiska uruchomieniowego, certyfikaty TLS, rozwiązywanie DNS, zaporę sieciową, zmienne środowiskowe oraz kod odpowiedzialny za obsługę odpowiedzi API. Sam fakt, że aplikacja działa na własnym serwerze, nie oznacza jednak, że MailerSend jest usługą instalowaną lokalnie; jest to integracja serwerowej aplikacji z zewnętrznym interfejsem wysyłkowym.