Utwórz klucz API i zarządzaj nim

Opublikowano: 16 lipca 2026 · Ostatnia aktualizacja: 12 września 2026 · Autor: Marcus Biel

Na stronie klucza API możesz zapewnić zewnętrznemu systemowi uwierzytelniony dostęp do obsługiwanych endpointów API Maildroppa na swoim koncie.

Możesz utworzyć jeden klucz API, skopiować jego pełną, poufną wartość, bezpiecznie go zresetować przez rotację lub usunąć, gdy nie jest już potrzebny. Ten sam klucz konta może służyć integracjom po stronie serwera oraz wyzwalaczom żądań API w automatyzacjach Maildroppa.

Klucz API reprezentuje konto Maildroppa. Traktuj go jak hasło: każda osoba, która zdobędzie klucz, może wywoływać dostępne dla niego endpointy API, dopóki nie wymienisz go przez rotację lub nie usuniesz.

Do czego służy klucz API

Używaj klucza API, gdy oprogramowanie spoza Maildroppa musi komunikować się z Maildroppa bez interaktywnego logowania użytkownika.

Typowe zastosowania:

• Synchronizowanie subskrybentów z systemem CRM, sklepem, systemem członkowskim lub wewnętrzną bazą danych.
• Tworzenie lub aktualizowanie subskrybentów z aplikacji działającej po stronie serwera.
• Odczytywanie tagów, pól, wartości pól i segmentów lub zarządzanie nimi za pomocą obsługiwanych endpointów.
• Wysyłanie zdarzeń niestandardowych do wyzwalacza żądania API w automatyzacji.
• Wysyłanie transakcyjnych wiadomości e-mail przez API.
• Zarządzanie subskrypcjami webhooków opartymi na API.

Klucz API jest przeznaczony do komunikacji między serwerami. Nie używaj go w kodzie uruchamianym w przeglądarce odwiedzającego, w publicznej witrynie, aplikacji mobilnej ani osadzonym formularzu zapisu.

Strona jest obecnie oznaczona jako „beta”. Korzystaj z podlinkowanej dokumentacji OpenAPI jako źródła informacji o endpointach, treściach żądań, parametrach i schematach odpowiedzi obsługiwanych obecnie przez API.

Otwórz stronę klucza API

Otwórz „Settings”, rozwiń „Developers” i wybierz „API key”.

Możesz też otworzyć stronę bezpośrednio pod adresem:

https://app.maildroppa.com/settings/developers/api-key

Na stronie znajdziesz:

• Panel klucza API z oznaczeniem beta.
• Link „View OpenAPI docs”.
• Widok informujący o braku klucza i przycisk „Create API key”, gdy klucz jeszcze nie istnieje.
• Zamaskowaną postać bieżącego klucza, jeśli klucz istnieje.
• Przycisk „Copy”, który kopiuje cały klucz.
• Opcje „Rotate API key” i „Delete API key”, które pozwalają zastąpić lub usunąć bieżący klucz.

Maildroppa umożliwia utworzenie jednego klucza API na konto. Na tej stronie nie utworzysz osobnych kluczy dla poszczególnych aplikacji, środowisk ani członków zespołu.

Utwórz klucz API

Gdy na stronie pojawi się komunikat „No API key yet”, kliknij „Create API key”.

Maildroppa tworzy klucz natychmiast. Przy pierwszym utworzeniu klucza nie pojawia się okno z prośbą o potwierdzenie. Podczas przetwarzania żądania tekst przycisku zmienia się na „Creating API key”, a dalsze działania związane z kluczem są tymczasowo niedostępne.

Po utworzeniu klucza:

• Znika widok informujący o braku klucza.
• Pojawia się zamaskowany klucz.
• Dostępne stają się opcje „Copy”, „Rotate API key” i „Delete API key”.
• Maildroppa wyświetla komunikat potwierdzający powodzenie operacji: „API key updated”.

Jeśli na koncie istnieje już klucz, Maildroppa nie utworzy drugiego. Użyj istniejącego klucza lub wymień go przez rotację.

Jak działa maskowanie klucza

Strona nie wyświetla pełnej, poufnej wartości klucza jawnym tekstem. Pokazuje pierwsze pięć znaków, a po nich pięć gwiazdek, na przykład:

a1b2c*****

To jedynie sposób ukrycia klucza na ekranie. Gwiazdki nie odzwierciedlają jego rzeczywistej długości, a zamaskowanej wartości nie można użyć w żądaniu API.

Kliknij „Copy”, aby skopiować cały bieżący klucz do schowka. Po skopiowaniu tekst przycisku na krótko zmienia się na „Copied!”.

Po powrocie na stronę klucz nadal jest zamaskowany, ale przycisk „Copy” wciąż kopiuje jego pełną bieżącą wartość. Nie musisz więc wymieniać ważnego klucza przez rotację tylko dlatego, że nie został zapisany podczas tworzenia.

Przechowuj klucz bezpiecznie

Przenieś skopiowany klucz bezpośrednio do magazynu sekretów używanego przez integrację.

Odpowiednie miejsca to:

• Zarządzany menedżer sekretów.
• Chroniona konfiguracja środowiska serwera.
• Zaszyfrowany sekret wdrożeniowy.
• Menedżer haseł używany do przywracania działania systemów.

Nie przechowuj klucza w:

• Kodzie JavaScript działającym w przeglądarce ani innym pakiecie frontendowym, który można pobrać.
• Pliku kodu źródłowego zapisanym w publicznym lub prywatnym repozytorium.
• Adresie URL ani parametrze zapytania.
• Publicznej dokumentacji, zrzutach ekranu, wiadomościach do pomocy technicznej ani systemach śledzenia zgłoszeń.
• Współdzielonych logach aplikacji, zdarzeniach analitycznych ani raportach błędów.
• Niezaszyfrowanym arkuszu kalkulacyjnym ani zwykłym czacie zespołowym.

Nie dodawaj klucza do przykładu curl, który trafi do dokumentacji lub historii powłoki udostępnianej innym osobom. Zamiast tego użyj zmiennej środowiskowej, takiej jak MAILDROPPA_API_KEY.

Korzystaj z klucza API

Wysyłaj cały klucz w nagłówku żądania HTTP X-API-Key:

X-API-Key: your-complete-api-key

Nie wysyłaj go jako tokenu Bearer. Maildroppa oczekuje X-API-Key, a nie Authorization: Bearer ....

Produkcyjne API i jego interaktywna dokumentacja OpenAPI są dostępne pod adresem:

https://api.maildroppa.com

Kliknij „View OpenAPI docs” na stronie klucza API, aby otworzyć dokumentację w nowej karcie przeglądarki. Wybierz w niej endpoint i sprawdź jego metodę, ścieżkę, parametry, treść żądania, typ odpowiedzi i możliwe kody statusu.

Przykładowe żądanie

Poniższy przykład pobiera pierwszą stronę listy subskrybentów. Odczytuje klucz ze zmiennej środowiskowej zamiast umieszczać sekret bezpośrednio w poleceniu:

curl --request GET \
  --url 'https://api.maildroppa.com/subscribers?pageNumber=1' \
  --header 'Accept: application/json' \
  --header "X-API-Key: ${MAILDROPPA_API_KEY}"

Ustaw zmienną w bezpiecznym środowisku, w którym działa integracja. Konkretna metoda, ścieżka, parametry zapytania i treść żądania zależą od endpointu. Skopiuj te informacje z dokumentacji OpenAPI, zamiast zgadywać je na podstawie działań dostępnych w aplikacji Maildroppa.

Żądania z treścią JSON

Jeśli żądanie wysyła dane w formacie JSON, dodaj również:

Content-Type: application/json

Przykładowa podstawowa struktura wygląda tak:

curl --request POST \
  --url 'https://api.maildroppa.com/example-endpoint' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --header "X-API-Key: ${MAILDROPPA_API_KEY}" \
  --data '{"example":"value"}'

/example-endpoint i treść żądania to wartości zastępcze. Zastąp je udokumentowanym endpointem i treścią zgodną z jego udokumentowanym schematem żądania.

Do czego klucz daje dostęp

Klucz działa wyłącznie z endpointami obsługującymi uwierzytelnianie za pomocą klucza API. Strona lub żądanie używane wewnętrznie przez aplikację Maildroppa nie stają się automatycznie częścią publicznego API dla klientów.

Dokumentacja OpenAPI opisuje obsługiwane API dla klientów. Jeśli dokumentacja nie wskazuje, że dana ścieżka obsługuje klucz API, nie zakładaj, że klucz zapewnia do niej dostęp.

Strona klucza API nie oferuje zakresów uprawnień ani pól wyboru uprawnień dla poszczególnych endpointów. Dlatego traktuj bieżący klucz konta jako szczególnie ważne poświadczenie, nawet jeśli dana integracja korzysta tylko z jednego endpointu.

Limity częstotliwości żądań

Aktualna specyfikacja OpenAPI określa następujące limity dla kluczy API:

• Domyślny limit API dla klientów: 300 żądań na minutę i 2000 żądań na godzinę.
• Events API pod adresem /events: 100 żądań na sekundę, z możliwością obsługi krótkiej serii do 500 żądań.

Limity dotyczą konta Maildroppa, a nie każdego skryptu korzystającego z jego klucza osobno. Kilka integracji może więc zużywać wspólny limit.

Gdy Maildroppa zwróci 429 Too Many Requests, wstrzymaj wysyłanie nowych żądań i uwzględnij czas oczekiwania wskazany w nagłówku odpowiedzi Retry-After, jeśli jest obecny. Korzystaj z kolejki i kontrolowanych opóźnień między ponowieniami, zamiast uruchamiać wiele ponowień równolegle.

Zasady limitowania żądań mogą się zmieniać, dopóki API jest w wersji beta. Przed zaprojektowaniem integracji wysyłającej dużą liczbę żądań sprawdź informacje na początku dokumentacji OpenAPI.

Używaj klucza do żądań API w automatyzacjach

Automatyzacja może się uruchomić, gdy zewnętrzny system wyśle zdarzenie niestandardowe do Events API Maildroppa.

Podczas konfigurowania wyzwalacza „API request” Maildroppa używa tego samego klucza API konta, którym zarządzasz na tej stronie. W konfiguracji wyzwalacza możesz utworzyć klucz, jeśli jeszcze nie istnieje, oraz skopiować przygotowane żądanie curl zawierające cały klucz.

Ma to dwie ważne konsekwencje:

• Rotacja lub usunięcie klucza konta wpływa również na systemy wysyłające zdarzenia niestandardowe do automatyzacji.
• Skopiowany przykład żądania automatyzacji umieszcza sekret w schowku, mimo że na ekranie klucz jest zamaskowany.

Przed rotacją lub usunięciem klucza uwzględnij w wykazie integracji każdy wyzwalacz żądania API i każdy zewnętrzny system wysyłający zdarzenia.

Zresetuj lub wymień klucz API

Użyj opcji „Rotate API key”, gdy chcesz zresetować lub wymienić bieżący klucz. W ramach jednej operacji Maildroppa tworzy nowy klucz i unieważnia poprzedni.

Przeprowadź rotację, gdy:

• Klucz mógł zostać ujawniony.
• Osoba lub dostawca znający klucz nie potrzebuje już dostępu.
• Polityka bezpieczeństwa wymaga okresowej wymiany poświadczeń.
• Chcesz zastąpić klucz przechowywany w starym lub niezabezpieczonym miejscu.

Kliknij „Rotate API key” pod zamaskowanym kluczem. Maildroppa otworzy okno z ostrzeżeniem, że dotychczasowego klucza nie będzie już można używać.

Kliknij „Rotate API key” w oknie dialogowym, aby kontynuować, lub „Cancel”, aby zachować bieżący klucz.

Rotacja nie ma okresu przejściowego

Po potwierdzeniu rotacji stary klucz natychmiast przestaje działać. W Maildroppa stary i nowy klucz nie są ważne jednocześnie.

Ponieważ konto ma tylko jeden klucz, rotacja wpływa na każdy serwer, zaplanowane zadanie, integrację, skrypt i system wysyłający zdarzenia do automatyzacji, który z niego korzysta.

Przy planowanej rotacji postępuj w tej kolejności:

1. Sporządź listę wszystkich integracji korzystających z bieżącego klucza.
2. Przygotuj dostęp do konfiguracji sekretów i procesu wdrażania każdej integracji.
3. Wybierz krótkie okno serwisowe, jeśli nieprzerwany dostęp do API jest ważny.
4. Kliknij „Rotate API key”, a następnie potwierdź ostrzeżenie przyciskiem „Rotate API key” w oknie dialogowym.
5. Kliknij „Copy”, aby skopiować cały nowy klucz.
6. Natychmiast zastąp sekret w każdej integracji.
7. Uruchom ponownie lub wdróż ponownie usługi, które wczytują sekrety tylko przy uruchamianiu.
8. Wyślij bezpieczne, udokumentowane żądanie, aby sprawdzić działanie każdej integracji.
9. Sprawdź, czy nie pojawiają się odpowiedzi 401 Unauthorized związane z pominiętą usługą, która nadal używa starego klucza.

Jeśli podejrzewasz, że bieżący klucz został przejęty, natychmiast przeprowadź jego rotację i zaakceptuj krótką przerwę potrzebną na aktualizację uprawnionych systemów.

Usuń klucz API

Usuń klucz, gdy konto nie powinno już przyjmować żądań uwierzytelnianych za pomocą klucza API.

Kliknij „Delete API key” pod zamaskowanym kluczem. Maildroppa otworzy okno z ostrzeżeniem, że klucz zostanie trwale usunięty z konta.

Kliknij „Delete API key” w oknie dialogowym, aby usunąć klucz, lub „Cancel”, aby go zachować.

Po usunięciu:

• Bieżący klucz natychmiast przestaje działać.
• Strona ponownie wyświetla komunikat „No API key yet”.
• Integracje serwerowe korzystające z usuniętego klucza nie mogą już się uwierzytelniać.
• Systemy wysyłające żądania API do automatyzacji za pomocą tego klucza nie mogą już dostarczać zdarzeń.

Usunięcie klucza nie usuwa subskrybentów, kampanii, tagów, pól, segmentów, automatyzacji ani innych danych konta. Usuwa jedynie poświadczenie służące do uzyskiwania dostępu do obsługiwanych endpointów API.

Później możesz kliknąć „Create API key”, aby utworzyć nowy klucz. Usunięta wartość nie zostanie przywrócona. Każdą integrację trzeba zaktualizować, zanim będzie mogła korzystać z nowego klucza.

Resetowanie czy usuwanie — co wybrać?

Wybierz „Rotate API key”, jeśli chcesz zachować dostęp do API z użyciem nowego klucza.

Wybierz usunięcie, jeśli chcesz całkowicie zatrzymać dostęp do API — przynajmniej na razie.

Obie operacje natychmiast unieważniają bieżący klucz. Rotacja w ramach tej samej operacji tworzy nowy klucz, a usunięcie pozostawia konto bez klucza.

Zalecenia dotyczące bezpieczeństwa

Wywołuj API z własnego serwera

Przeglądarka ani aplikacja mobilna nie mogą niezawodnie chronić osadzonego w nich sekretu. Użytkownik może przeanalizować aplikację, nagłówki żądań, mapy źródeł lub ruch sieciowy i wydobyć klucz.

Jeśli witryna lub aplikacja musi wywołać działanie, najpierw wyślij żądanie do własnego backendu wymagającego uwierzytelnienia. To backend powinien zweryfikować użytkownika i wywołać Maildroppa za pomocą klucza przechowywanego na serwerze.

Ogranicz udostępnianie klucza do minimum

Udostępniaj klucz tylko systemom, które go potrzebują. Nie przekazuj go każdemu programiście ani nie wklejaj do wielu lokalnych plików konfiguracyjnych.

Obecnie strona pozwala zarządzać jednym kluczem dla całego konta, a nie wieloma kluczami z nazwami lub określonymi zakresami uprawnień. Jeśli kilka aplikacji wymaga silniejszej izolacji od siebie, użyj wewnętrznej usługi integracyjnej lub serwera proxy.

Maskuj poufne dane w nagłówkach żądań

Skonfiguruj klientów HTTP, odwrotne serwery proxy, narzędzia obserwowalności i narzędzia do raportowania błędów tak, aby maskowały wartość X-API-Key. Żądanie może działać poprawnie, a jednocześnie ujawniać klucz w logach debugowania.

Zachowaj rozdzielenie środowisk

Nie używaj klucza produkcyjnego w lokalnym środowisku programistycznym, przykładowym kodzie, zrzutach ekranu ani danych testowych. Sekrety poszczególnych środowisk przechowuj w przeznaczonych dla nich magazynach sekretów.

Link „View OpenAPI docs” automatycznie kieruje użytkowników środowiska produkcyjnego do dokumentacji produkcyjnego API. Zawsze sprawdzaj nazwę hosta przed wysłaniem rzeczywistego klucza.

Przeprowadź rotację przy każdym podejrzeniu ujawnienia

Usunięcie wiadomości, commita z repozytorium, wiersza logu lub zrzutu ekranu nie dowodzi, że nikt nie skopiował klucza. Jeśli jego pełna wartość została ujawniona, przeprowadź rotację.

Obsługa błędów API

Na podstawie statusu HTTP i udokumentowanej treści odpowiedzi zdecyduj, jak powinna zareagować integracja.

Typowe przypadki:

• 400 Bad Request — ścieżka, parametr lub treść JSON nie spełnia wymagań specyfikacji endpointu. Porównaj żądanie ze schematem OpenAPI.
• 401 Unauthorized — brakuje nagłówka X-API-Key, jest on pusty lub nieprawidłowy, klucz został usunięty albo nagłówek zawiera starą wartość po rotacji.
• 403 Forbidden — uwierzytelniony klucz nie ma uprawnień do wykonania tej operacji.
• 404 Not Found — ścieżka lub wskazany zasób nie istnieje na tym koncie.
• 429 Too Many Requests — integracja osiągnęła limit częstotliwości żądań API. Wstrzymaj żądania i uwzględnij czas oczekiwania wskazany w nagłówku Retry-After, jeśli jest obecny.
• 5xx — Maildroppa nie zdołała zrealizować żądania. Ponawiaj bezpieczne operacje z wykładniczo rosnącymi opóźnieniami do ustalonego limitu i zapisuj logi bez klucza API.

Nie ponawiaj automatycznie każdej nieudanej operacji bez sprawdzenia przyczyny. Usuń przyczyny odpowiedzi 400, 401, 403 i większości odpowiedzi 404, zanim ponownie wyślesz to samo żądanie.

W przypadku żądań modyfikujących dane sprawdź zasady ponawiania i idempotencji danego endpointu, zanim automatycznie powtórzysz żądanie. Błąd połączenia nie zawsze oznacza, że Maildroppa nie wprowadziła żadnej zmiany.

Rozwiązywanie problemów

Przycisk „Create API key” nadal jest widoczny

Na koncie nie ma obecnie klucza. Kliknij przycisk raz i poczekaj na zakończenie żądania.

Jeśli tworzenie się nie powiedzie, odśwież stronę przed ponowną próbą. Klucz konta mógł już zostać utworzony na innej stronie lub podczas konfiguracji automatyzacji.

Klucz na stronie wygląda na zbyt krótki

Strona celowo pokazuje tylko pierwsze pięć znaków i *****. Kliknij „Copy”, aby skopiować pełną wartość. Nie wysyłaj zamaskowanego tekstu w żądaniu.

Tekst przycisku „Copy” nie zmienia się na „Copied!”

Przeglądarka mogła zablokować dostęp do schowka. Pozostaw stronę w aktywnej karcie, zezwól na dostęp do schowka, jeśli pojawi się prośba o zgodę, i ponownie kliknij „Copy”.

Nie próbuj odtwarzać klucza na podstawie zamaskowanego tekstu.

Żądanie zwraca 401 Unauthorized

Sprawdź, czy:

• Nazwa nagłówka to dokładnie X-API-Key.
• Nagłówek zawiera pełną wartość, bez widocznych gwiazdek.
• Integracja nie wysyła zamiast tego Authorization: Bearer.
• Do sekretu nie dodano białych znaków, cudzysłowów ani znaku nowej linii.
• Nikt nie przeprowadził rotacji klucza konta ani go nie usunął.
• Usługa została ponownie uruchomiona, jeśli odczytuje zmienne środowiskowe tylko przy uruchamianiu.
• Żądanie trafia do właściwego środowiska API Maildroppa.

Jedna integracja działa, ale druga przestała działać po rotacji

Druga integracja prawdopodobnie nadal używa starego klucza. Nie ma okresu, w którym oba klucze są ważne. Zaktualizuj jej sekret i uruchom ponownie każdy proces, który przechowuje konfigurację w pamięci podręcznej.

Strona OpenAPI działa, ale endpoint zwraca 403

Nie każdy endpoint aplikacji obsługuje uwierzytelnianie za pomocą klucza API. Użyj operacji udokumentowanej dla API dla klientów i sprawdź jej wymagania dotyczące uwierzytelniania na stronie OpenAPI.

Żądania zwracają 429 Too Many Requests

Ogranicz liczbę żądań wysyłanych w krótkich seriach, kolejkuj zadania i ponawiaj żądania po upływie czasu wskazanego przez API. Unikaj lawiny równoległych ponowień. Jeśli kilka aplikacji korzysta z jednego klucza konta, skoordynuj liczbę wysyłanych przez nie żądań, ponieważ współdzielą limity API konta.

Zalecana lista kontrolna konfiguracji

Zanim zaczniesz regularnie korzystać z integracji, upewnij się, że:

• Klucz jest przechowywany wyłącznie w konfiguracji sekretów po stronie serwera.
• Żądania używają nagłówka X-API-Key.
• Integracja w środowisku produkcyjnym korzysta z https://api.maildroppa.com.
• Każda metoda, ścieżka, parametr i treść JSON są zgodne z dokumentacją OpenAPI.
• Klucz jest maskowany w logach i raportach błędów.
• Skonfigurowano limity czasu i ograniczoną liczbę ponowień.
• Monitorowane są błędy 401, 403, 429 oraz błędy serwera.
• Zapisano, kto odpowiada za integrację.
• Plan rotacji uwzględnia każdy system współdzielący klucz konta.
• W razie przejęcia klucza można szybko przeprowadzić jego rotację.

Strona klucza API jest celowo prosta, ale wykonywane na niej działania wpływają na każdą integrację API połączoną z kontem. Twórz klucz tylko wtedy, gdy jest potrzebny, przechowuj go na zaufanych serwerach i planuj rotację jako zmianę poświadczenia dla całego konta.