Mailgun CLI Tools

Narzędzia wiersza poleceń Mailgun umożliwiają obsługę tej usługi wysyłkowej ze skryptów i systemów automatyzacji.

Mailgun CLI Tools jako warstwa wiersza poleceń

Mailgun CLI Tools to określenie narzędzi uruchamianych w terminalu, które pozwalają wykonywać operacje w usłudze Mailgun bez ręcznego korzystania z panelu internetowego. Nie jest to jedna, jednoznacznie zdefiniowana aplikacja o wspólnym zestawie poleceń, lecz kategoria programów i skryptów komunikujących się z Mailgun Email API. Konkretne możliwości zależą od użytego projektu, jego języka programowania, sposobu instalacji oraz zakresu endpointów, które zostały przez autora zaimplementowane.

W praktyce narzędzie CLI może przyjmować parametry w terminalu, odczytywać ustawienia ze zmiennych środowiskowych i przekazywać żądania HTTP do API. Dzięki temu wysyłanie wiadomości, sprawdzanie zdarzeń, analiza statystyk lub obsługa wybranych zasobów Mailgun może zostać włączona do skryptu powłoki, zadania harmonogramu albo procesu automatyzacji. Sam interfejs wiersza poleceń nie zastępuje Mailgun API, tylko upraszcza przygotowanie żądań i prezentację odpowiedzi.

Żądania HTTP, uwierzytelnianie i region API

Mailgun API udostępnia funkcje przez protokół HTTPS. Uwierzytelnianie odbywa się przy użyciu klucza API, a wiele przykładów korzysta z uwierzytelniania HTTP Basic Auth, w którym nazwą użytkownika jest wartość api, natomiast hasłem pozostaje klucz. Klucz powinien być przekazywany przez bezpieczny magazyn sekretów albo zmienną środowiskową, a nie wpisywany na stałe do pliku skryptu, historii powłoki lub publicznego repozytorium.

Wysyłanie wiadomości przez Send API wymaga między innymi wskazania domeny używanej przez Mailgun oraz pól wiadomości, takich jak nadawca, odbiorca, temat i treść. Przykładowe żądanie wykonywane programem curl może mieć postać curl --user "api:$MAILGUN_API_KEY" --form from="Ten adres pocztowy jest chroniony przed spamowaniem. Aby go zobaczyć, konieczne jest włączenie w przeglądarce obsługi JavaScript." --form to="Ten adres pocztowy jest chroniony przed spamowaniem. Aby go zobaczyć, konieczne jest włączenie w przeglądarce obsługi JavaScript." --form subject="Test" --form text="Treść wiadomości" https://api.mailgun.net/v3/example.com/messages. Jest to przykład bezpośredniego wywołania API, a nie uniwersalna składnia każdego programu określanego jako Mailgun CLI Tools. Dla kont korzystających z infrastruktury europejskiej należy użyć odpowiedniego europejskiego adresu API, zgodnego z konfiguracją konta.

Automatyzacja wysyłki i odczyt odpowiedzi

Najważniejszą cechą narzędzi CLI jest możliwość powtarzalnego wykonywania tych samych czynności. Skrypt może przygotować treść, przekazać listę adresów, dołączyć plik, ustawić temat i zapisać odpowiedź serwera do logu. Odpowiedź API jest zwykle dokumentem JSON zawierającym informację o przyjęciu żądania, identyfikatorze operacji albo błędzie. Program automatyzujący powinien analizować zarówno kod zakończenia procesu, jak i kod statusu HTTP oraz treść odpowiedzi, ponieważ samo poprawne uruchomienie polecenia nie oznacza jeszcze prawidłowego przyjęcia wiadomości.

W diagnostyce przydatne jest rozróżnienie kilku etapów: lokalne przygotowanie danych, uwierzytelnienie, połączenie TLS, odpowiedź API oraz późniejsze zdarzenie związane z dostarczeniem wiadomości. Błąd składni polecenia może wystąpić przed wysłaniem żądania, błąd uwierzytelnienia może zwrócić odpowiedź HTTP 401, a nieprawidłowa domena lub brak uprawnień może skutkować inną odpowiedzią API. Przyjęcie wiadomości przez Mailgun nie jest równoznaczne z jej dostarczeniem do skrzynki odbiorcy. Status dostarczenia, odrzucenia, odbicia lub opóźnienia należy sprawdzać za pomocą funkcji zdarzeń i raportowania dostępnych dla danego konta.

Problemy lokalne na laptopie i komputerze PC

Nieprawidłowe działanie Mailgun CLI Tools na komputerze może wynikać z problemów niezwiązanych bezpośrednio z usługą: uszkodzonej instalacji interpretera, braku wymaganej biblioteki, błędnej ścieżki systemowej, nieustawionej zmiennej środowiskowej albo blokady połączeń HTTPS. Warto również sprawdzić, czy terminal korzysta z tej samej wersji programu, która została użyta podczas instalacji, oraz czy konfiguracja nie odwołuje się do starego klucza, niewłaściwej domeny lub nieprawidłowego regionu API.

Warszawskie Pogotowie Komputerowe zajmuje się profesjonalną naprawą laptopów i komputerów PC, w tym diagnostyką problemów z systemem, połączeniem sieciowym, terminalem oraz oprogramowaniem używanym do pracy z narzędziami CLI. Diagnoza laptopa jest bezpłatna w trybie door-to-door, czyli przy odbiorze urządzenia przez kierowcę. W przypadku komputera stacjonarnego diagnoza kosztuje 200 zł i jest zaliczana na poczet naprawy. Jeżeli problem dotyczy samej konfiguracji konta Mailgun lub uprawnień po stronie usługi, konieczne jest sprawdzenie ustawień w dokumentacji i panelu Mailgun, ponieważ naprawa komputera nie zmienia parametrów konta u dostawcy.