Tworzenie klucza API

Z kluczem API aplikacja wysyła pocztę bezpośrednio przez REST API 2Mail, bez połączenia SMTP, i dla każdej wiadomości otrzymuje identyfikator, dzięki któremu można śledzić jej status. Dla każdej aplikacji tworzą Państwo osobny klucz, aby można je było unieważniać niezależnie.

Krok 1: utworzenie klucza

1. Proszę otworzyć w panelu 2Mail sekcję z kluczami API.
2. Utworzyć nowy klucz i nadać mu nazwę aplikacji, która będzie go używać: nazwę sklepu internetowego, CRM-u, programu do fakturowania. Nie ogólną nazwę w rodzaju „produkcja” — za rok nikt nie będzie pamiętał, do czego służył.
3. Wybrać zakres klucza: jedna skrzynka wysyłkowa (mailbox) albo grupa skrzynek. Adres nadawcy wiadomości musi należeć do jednej z domen dozwolonych dla tej skrzynki.
4. Zapisać i od razu skopiować klucz. Ze względów bezpieczeństwa jest on wyświetlany w całości tylko raz; później widać już tylko nazwę i pierwsze znaki.

Krok 2: bezpieczne przechowywanie klucza

Klucz należy umieścić w poufnej konfiguracji aplikacji — w zmiennej środowiskowej albo w menedżerze sekretów — i nigdy w kodzie źródłowym, e-mailu czy wiadomości na czacie. Kto ma klucz, może wysyłać w imieniu Państwa domeny. Dla środowiska testowego i produkcyjnego warto użyć osobnych kluczy; wtedy test nigdy nie dotrze do prawdziwych klientów.

Krok 3: używanie klucza

Aplikacja przesyła klucz w nagłówku autoryzacji każdego żądania do API. Dokumentacja API e-mail opisuje endpointy do wysyłania wiadomości, sprawdzania statusu i zarządzania webhookami. Każde żądanie wysyłające wiadomość zwraca identyfikator; warto zapisać go przy wiadomości we własnym systemie, aby później powiązać z nią status i odbicia.

Krok 4: test

Proszę wysłać jedną wiadomość na zewnętrzny adres testowy i sprawdzić ją w dzienniku dostarczeń w panelu. W sekcji kluczy API panel pokazuje ponadto ostatnią aktywność API dla każdego klucza — to wygodny sposób, by zobaczyć, która aplikacja co robi.

Unieważnienie lub wymiana klucza

Jeśli podejrzewają Państwo wyciek klucza albo odchodzi programista, który go znał, proszę najpierw utworzyć nowy klucz, wpisać go do aplikacji i dopiero potem unieważnić stary. Dzięki temu aplikacja ani na chwilę nie przestanie działać. Unieważniony klucz przestaje działać natychmiast; żądania z nim otrzymują w odpowiedzi błąd.

Gdzie pojawiają się problemy

• Żądanie odrzucone — klucz został źle skopiowany, unieważniony albo domena nadawcy nie należy do skrzynki, do której przypisano klucz.
• Klucz zgubiony — nie da się go wyświetlić ponownie; należy utworzyć nowy.
• Jeden klucz do wszystkiego — działa, dopóki nie trzeba wyłączyć jednej aplikacji. Warto je rozdzielić.

Jeśli chcą Państwo otrzymywać w aplikacji także informacje o dostarczeniach, odbiciach i otwarciach, warto skonfigurować webhook.

Coś nie działa?

Prosimy podać nam przez stronę kontaktową nazwę klucza i godzinę żądania. Nigdy sam klucz — nie musimy go widzieć.