Vytvorte a spravujte svoj API kľúč

Published: 16. júla 2026 · Last updated: 21. júla 2026 · By Marcus Biel

Stránka API kľúča poskytuje externému systému overený prístup k podporovaným koncovým bodom Maildroppa API vo vašom účte.

Môžete vytvoriť jeden API kľúč, skopírovať jeho úplnú tajnú hodnotu, bezpečne ho resetovať rotáciou alebo ho odstrániť, keď ho už nepotrebujete. Ten istý kľúč účtu možno používať serverovými integráciami aj spúšťačmi API požiadaviek v Maildroppa Automations.

API kľúč reprezentuje váš účet Maildroppa. Zaobchádzajte s ním ako s heslom: každý, kto kľúč získa, môže volať koncové body API, ktoré sú pre tento kľúč dostupné, až kým ho neotočíte alebo neodstránite.

Na čo slúži API kľúč

API kľúč použite vtedy, keď softvér mimo Maildroppa potrebuje pracovať s Maildroppou bez interaktívneho prihlásenia používateľa.

Typické príklady:

• Synchronizácia odberateľov s CRM, obchodom, členským systémom alebo internou databázou.
• Vytváranie alebo aktualizácia odberateľov zo serverovej aplikácie.
• Čítanie alebo správa štítkov, polí, hodnôt polí a segmentov prostredníctvom podporovaných koncových bodov.
• Odosielanie vlastných udalostí do spúšťača API požiadaviek v Automation.
• Odosielanie transakčných e-mailových správ prostredníctvom API.
• Správa odberov webhookov založených na API.

API kľúč je určený na komunikáciu medzi servermi. Nie je určený pre kód spúšťaný v prehliadači návštevníka, na verejnej webovej stránke, v mobilnej aplikácii ani vo vloženom registračnom formulári.

Stránka je momentálne označená ako „beta“. Pre koncové body, telá požiadaviek, parametre a schémy odpovedí, ktoré API momentálne podporuje, používajte prepojenú dokumentáciu OpenAPI ako zdroj.

Otvorenie stránky API kľúča

Otvorte „Settings“, rozbaľte „Developers“ a vyberte „API key“.

Stránku môžete otvoriť aj priamo na adrese:

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

Stránka obsahuje:

• Panel API kľúča s označením beta.
• Odkaz „View OpenAPI docs“.
• Prázdny stav a tlačidlo „Create API key“, keď neexistuje žiadny kľúč.
• Maskovanú podobu aktuálneho kľúča, keď existuje.
• Tlačidlo „Copy“, ktoré skopíruje úplný kľúč.
• Akcie „Rotate API key“ a „Delete API key“ na nahradenie alebo odstránenie aktuálneho kľúča.

Maildroppa povoľuje jeden API kľúč na účet. Stránka nevytvára samostatné kľúče pre jednotlivé aplikácie, prostredia ani členov tímu.

Vytvorenie API kľúča

Keď sa na stránke zobrazí „No API key yet“, kliknite na „Create API key“.

Maildroppa vytvorí kľúč okamžite. Pri prvom vytvorení sa nezobrazuje potvrdzovacie dialógové okno. Počas spracovania požiadavky sa tlačidlo zmení na „Creating API key“ a stránka dočasne deaktivuje ďalšie akcie s kľúčom.

Po vytvorení kľúča:

• Prázdny stav zmizne.
• Zobrazí sa maskovaný kľúč.
• Sprístupnia sa akcie „Copy“, „Rotate API key“ a „Delete API key“.
• Maildroppa zobrazí úspešnú správu „API key updated“.

Ak účet už obsahuje iný kľúč, Maildroppa nevytvorí druhý. Použite existujúci kľúč alebo ho otočte.

Vysvetlenie maskovaného kľúča

Stránka nezobrazuje úplnú tajnú hodnotu ako bežný text. Zobrazuje prvých päť znakov, po ktorých nasleduje päť hviezdičiek, napríklad:

a1b2c*****

Ide iba o vizuálne maskovanie. Hviezdičky nepredstavujú skutočnú dĺžku kľúča a maskovanú hodnotu nemožno použiť v API požiadavke.

Kliknutím na „Copy“ zapíšete úplný aktuálny kľúč do schránky. Po úspešnom skopírovaní sa tlačidlo nakrátko zmení na „Copied!“.

Po návrate na stránku zostane kľúč maskovaný, no tlačidlo „Copy“ bude naďalej kopírovať úplnú aktuálnu hodnotu. Platný kľúč preto nemusíte otáčať len preto, že ste si ho pri vytvorení neuložili.

Bezpečné uloženie kľúča

Skopírovaný kľúč priamo vložte do úložiska tajomstiev, ktoré používa integrácia.

Vhodné miesta zahŕňajú:

• Spravovaný správca tajomstiev.
• Chránenú serverovú konfiguráciu prostredia.
• Zašifrované tajomstvo nasadenia.
• Správcu hesiel používaného na operatívne obnovenie.

Kľúč neukladajte do:

• JavaScriptu na strane prehliadača ani iného frontendového balíka dostupného na stiahnutie.
• Verejného ani súkromného súboru zdrojového kódu odovzdaného do repozitára.
• URL adresy ani parametra dotazu.
• Verejnej dokumentácie, snímok obrazovky, správ podpory ani systémov na sledovanie problémov.
• Zdieľaných aplikačných protokolov, analytických udalostí ani hlásení chýb.
• Nezašifrovaného tabuľkového súboru ani bežného tímového chatu.

Kľúč nepridávajte do príkladu curl, ktorý sa bude kopírovať do dokumentácie alebo do histórie shellu zdieľanej s inými ľuďmi. Uprednostnite premennú prostredia, napríklad MAILDROPPA_API_KEY.

Používanie API kľúča

Úplný kľúč odošlite v hlavičke HTTP požiadavky X-API-Key:

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

Neposielajte ho ako token Bearer. Maildroppa očakáva X-API-Key, nie Authorization: Bearer ....

Produkčné API a jeho interaktívna dokumentácia OpenAPI sú dostupné na adrese:

https://api.maildroppa.com

Kliknutím na „View OpenAPI docs“ na stránke API kľúča otvoríte dokumentáciu na novej karte prehliadača. Vyberte tam koncový bod a skontrolujte jeho metódu, cestu, parametre, telo požiadavky, typ odpovede a možné stavové kódy.

Príklad požiadavky

Nasledujúci príklad načíta prvú stránku odberateľov. Kľúč načíta z premennej prostredia namiesto jeho priameho vloženia do príkazu:

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

Premennú nastavte v zabezpečenom prostredí, v ktorom integrácia beží. Presná metóda, cesta, parametre dotazu a telo závisia od koncového bodu. Tieto údaje preberte z dokumentácie OpenAPI, namiesto toho, aby ste ich odhadovali podľa akcií dostupných v aplikácii Maildroppa.

Požiadavky s JSON telom

Pri požiadavke odosielajúcej JSON pridajte aj:

Content-Type: application/json

Základná štruktúra napríklad vyzerá takto:

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 a jeho telo sú zástupné hodnoty. Nahraďte ich zdokumentovaným koncovým bodom a jeho zdokumentovanou schémou požiadavky.

K čomu má kľúč prístup

Kľúč funguje iba s koncovými bodmi, ktoré podporujú overenie pomocou API kľúča. Stránka alebo požiadavka používaná interne aplikáciou Maildroppa nie je automaticky súčasťou verejného API pre zákazníkov.

Dokumentácia OpenAPI zobrazuje podporované zákaznícke API. Ak cesta nie je zdokumentovaná na použitie s API kľúčom, nepredpokladajte, že k nej kľúč poskytuje prístup.

Stránka API kľúča neponúka rozsahy ani začiarkavacie políčka oprávnení pre jednotlivé koncové body. S aktuálnym kľúčom účtu preto treba zaobchádzať ako s cenným poverením, aj keď jedna integrácia používa iba jediný koncový bod.

Limity frekvencie požiadaviek

Aktuálna zmluva OpenAPI dokumentuje tieto limity pre API kľúč:

• Predvolené zákaznícke API: 300 požiadaviek za minútu a 2 000 požiadaviek za hodinu.
• Events API na adrese /events: 100 požiadaviek za sekundu s kapacitou nárazového zaťaženia 500 požiadaviek.

Tieto limity sa uplatňujú na účet Maildroppa, nie nezávisle na každý skript, ktorý zdieľa jeho kľúč. Viaceré integrácie preto môžu spotrebúvať rovnaký limit.

Keď Maildroppa vráti 429 Too Many Requests, prestaňte odosielať nové požiadavky a rešpektujte hlavičku odpovede Retry-After, ak je prítomná. Použite front a riadený ústup namiesto spúšťania mnohých paralelných opakovaní.

Pravidlá limitov sa môžu počas beta prevádzky API meniť. Pred návrhom vysokokapacitných integrácií skontrolujte informácie v hornej časti dokumentácie OpenAPI.

Použitie kľúča na požiadavky Automation API

Automation sa môže spustiť, keď váš systém odošle vlastnú udalosť do Events API Maildroppa.

Pri konfigurácii spúšťača „API request“ Maildroppa používa rovnaký API kľúč účtu spravovaný na tejto stránke. Nastavenie spúšťača môže vytvoriť kľúč, ak žiadny neexistuje, a môže skopírovať pripravenú požiadavku curl obsahujúcu úplný kľúč.

Má to dva dôležité dôsledky:

• Otočenie alebo odstránenie kľúča účtu ovplyvní aj systémy, ktoré odosielajú vlastné udalosti do Automations.
• Skopírovaný príklad požiadavky Automation obsahuje tajnú hodnotu v schránke, hoci je kľúč na obrazovke maskovaný.

Pred otočením alebo odstránením kľúča zahrňte do inventára integrácií každý spúšťač API požiadaviek a každého externého odosielateľa udalostí.

Resetovanie alebo nahradenie API kľúča

Ak potrebujete resetovať alebo nahradiť aktuálne poverenie, použite „Rotate API key“. Maildroppa vytvorí nový kľúč a v rámci tej istej akcie zneplatní predchádzajúci.

Rotáciu použite, keď:

• Mohlo dôjsť k odhaleniu kľúča.
• Osoba alebo poskytovateľ, ktorí kľúč poznali, už prístup nepotrebujú.
• Vaše bezpečnostné pravidlá vyžadujú pravidelnú výmenu poverení.
• Chcete nahradiť kľúč uložený na starom alebo nezabezpečenom mieste.

Kliknite na „Rotate API key“ pod maskovaným kľúčom. Maildroppa otvorí varovné dialógové okno s vysvetlením, že existujúci kľúč už nebude použiteľný.

Ak chcete pokračovať, kliknite na „Rotate API key“ v dialógovom okne; aktuálny kľúč zachováte kliknutím na „Cancel“.

Rotácia nemá odkladnú lehotu

Po potvrdení rotácie starý kľúč okamžite prestane fungovať. Maildroppa neudržiava starý a nový kľúč platné súčasne.

Keďže účet má iba jeden kľúč, rotácia ovplyvní každý server, naplánovanú úlohu, integráciu, skript a odosielateľa udalostí Automation, ktorý ho používa.

Pri plánovanej rotácii postupujte takto:

1. Spíšte každú integráciu, ktorá používa aktuálny kľúč.
2. Pripravte si prístup ku konfigurácii tajomstiev a procesu nasadenia každej integrácie.
3. Ak je dôležitý neprerušovaný prístup k API, vyberte krátke servisné okno.
4. Kliknite na „Rotate API key“ a potom potvrďte varovanie kliknutím na „Rotate API key“ v dialógovom okne.
5. Kliknutím na „Copy“ skopírujte úplný nový kľúč.
6. Okamžite nahraďte tajnú hodnotu v každej integrácii.
7. Reštartujte alebo znova nasaďte služby, ktoré načítavajú tajomstvá iba pri spustení.
8. Odošlite neškodnú zdokumentovanú požiadavku na overenie každej integrácie.
9. Skontrolujte odpovede 401 Unauthorized zo zabudnutej služby, ktorá stále používa starý kľúč.

Ak sa predpokladá kompromitácia aktuálneho kľúča, okamžite ho otočte a akceptujte krátke prerušenie potrebné na aktualizáciu legitímnych systémov.

Odstránenie API kľúča

Kľúč odstráňte vtedy, keď účet už nemá prijímať požiadavky overené pomocou API kľúča.

Kliknite na „Delete API key“ pod maskovaným kľúčom. Maildroppa otvorí varovné dialógové okno s vysvetlením, že kľúč bude z účtu natrvalo odstránený.

Ak ho chcete odstrániť, kliknite na „Delete API key“ v dialógovom okne; zachováte ho kliknutím na „Cancel“.

Po odstránení:

• Aktuálny kľúč okamžite prestane fungovať.
• Stránka sa vráti do stavu „No API key yet“.
• Serverové integrácie používajúce odstránený kľúč sa už nebudú môcť overiť.
• Odosielatelia požiadaviek Automation API používajúci tento kľúč už nebudú môcť doručovať udalosti.

Odstránením kľúča sa neodstránia odberatelia, kampane, štítky, polia, segmenty, Automations ani iné údaje účtu. Odstráni sa poverenie používané na prístup k podporovaným koncovým bodom API.

Neskôr môžete kliknúť na „Create API key“ a vytvoriť nové poverenie. Odstránená hodnota sa neobnoví. Každú integráciu treba aktualizovať, aby mohla používať nový kľúč.

Resetovať alebo odstrániť: čo si vybrať?

Vyberte „Rotate API key“, keď má prístup k API pokračovať s novým poverením.

Vyberte odstránenie, keď sa má prístup k API úplne zastaviť, aspoň nateraz.

Obe akcie okamžite zneplatnia aktuálny kľúč. Rotácia vytvorí náhradu v rámci tej istej akcie; odstránenie ponechá účet bez kľúča.

Bezpečnostné odporúčania

API volania udržiavajte na serveri

Prehliadač ani mobilná aplikácia nedokážu spoľahlivo chrániť vložené tajomstvo. Používateľ môže skontrolovať aplikáciu, hlavičky požiadaviek, zdrojové mapy alebo sieťovú prevádzku a kľúč získať.

Ak webová stránka alebo aplikácia potrebuje spustiť akciu, najprv odošlite požiadavku na vlastný overený backend. Backend nech overí používateľa a zavolá Maildroppa s kľúčom uloženým na serveri.

Používajte čo najmenšie možné vystavenie

Kľúč poskytujte iba systémom, ktoré ho potrebujú. Nedistribuujte ho každému vývojárovi ani ho nevkladajte do viacerých lokálnych konfiguračných súborov.

Keďže stránka momentálne spravuje jeden kľúč pre celý účet namiesto viacerých pomenovaných alebo obmedzených kľúčov, ak viaceré aplikácie potrebujú lepšiu vzájomnú izoláciu, použite internú integračnú službu alebo proxy.

Redigujte hlavičky požiadaviek

Nakonfigurujte HTTP klientov, reverzné proxy, nástroje observability a hlásenia chýb tak, aby redigovali X-API-Key. Požiadavka môže fungovať správne a zároveň môže svoje poverenie odhaliť prostredníctvom protokolovania ladenia.

Udržiavajte oddelené prostredia oddelené

Produkčný kľúč nepoužívajte v lokálnom vývoji, ukážkovom kóde, snímkach obrazovky ani testovacích prípravkoch. Tajomstvá špecifické pre prostredie ukladajte do úložísk tajomstiev špecifických pre dané prostredie.

Odkaz „View OpenAPI docs“ automaticky smeruje používateľov produkcie na dokumentáciu produkčného API. Pred odoslaním skutočného kľúča vždy overte názov hostiteľa.

Po každom podozrení na odhalenie vykonajte rotáciu

Odstránenie správy, commitu v repozitári, riadku protokolu alebo snímky obrazovky nedokazuje, že kľúč nikto neskopíroval. Ak bola odhalená úplná hodnota, otočte kľúč.

Riešenie chýb API

Pri rozhodovaní o postupe integrácie vychádzajte z HTTP stavového kódu a zdokumentovaného tela odpovede.

Medzi bežné prípady patria:

• 400 Bad Request — Cesta, parameter alebo telo JSON nespĺňa zmluvu koncového bodu. Porovnajte požiadavku so schémou OpenAPI.
• 401 Unauthorized — Hlavička X-API-Key chýba, je prázdna alebo neplatná, kľúč bol odstránený alebo po rotácii obsahuje starú hodnotu.
• 403 Forbidden — Overený kľúč nemá povolenie na danú operáciu.
• 404 Not Found — Cesta alebo odkazovaný zdroj v tomto účte neexistuje.
• 429 Too Many Requests — Integrácia dosiahla limit frekvencie API. Pozastavte požiadavky a rešpektujte hlavičku Retry-After, ak je prítomná.
• 5xx — Maildroppa nedokázala požiadavku dokončiť. Bezpečné operácie opakujte s obmedzeným exponenciálnym ústupom a protokolovaním, ktoré vylučuje API kľúč.

Každé zlyhanie neopakujte naslepo. Pred opätovným odoslaním rovnakej požiadavky opravte odpovede 400, 401, 403 a väčšinu odpovedí 404.

Pri mutujúcich požiadavkách si pred automatickým opakovaním overte správanie koncového bodu pri opakovaní a jeho idempotenciu. Zlyhanie spojenia nemusí vždy znamenať, že Maildroppa nevykonala žiadnu zmenu.

Riešenie problémov

„Create API key“ je stále viditeľné

V účte momentálne neexistuje žiadny kľúč. Kliknite na tlačidlo raz a počkajte na dokončenie požiadavky.

Ak vytvorenie zlyhá, pred ďalším pokusom stránku znova načítajte. Iná stránka alebo nastavenie Automation už mohli vytvoriť kľúč účtu.

Kľúč na stránke vyzerá príliš krátky

Stránka zámerne zobrazuje iba prvých päť znakov a *****. Kliknutím na „Copy“ skopírujete úplnú hodnotu. Maskovaný text v požiadavke neposielajte.

„Copy“ sa nezmení na „Copied!“

Prehliadač mohol zablokovať prístup do schránky. Nechajte stránku v aktívnej karte, ak sa zobrazí výzva, povoľte prístup do schránky a znova kliknite na „Copy“.

Nepokúšajte sa kľúč rekonštruovať z maskovaného textu.

Požiadavka vracia 401 Unauthorized

Skontrolujte, či:

• Názov hlavičky je presne X-API-Key.
• Hlavička obsahuje úplnú hodnotu bez viditeľných hviezdičiek.
• Integrácia namiesto toho neposiela Authorization: Bearer.
• Do tajomstva neboli pridané medzery, úvodzovky ani nový riadok.
• Nikto neotočil ani neodstránil kľúč účtu.
• Služba bola reštartovaná, ak načítava premenné prostredia iba pri spustení.
• Požiadavka sa odosiela do správneho prostredia Maildroppa API.

Jedna integrácia funguje, ale druhá po rotácii prestala

Druhá integrácia pravdepodobne stále používa starý kľúč. Neexistuje obdobie prekrytia. Aktualizujte jej tajomstvo a reštartujte každý proces, ktorý ukladá konfiguráciu do vyrovnávacej pamäte.

Stránka OpenAPI funguje, ale koncový bod vracia 403

Nie každý aplikačný koncový bod podporuje overenie pomocou API kľúča. Použite operáciu zdokumentovanú pre zákaznícke API a na stránke OpenAPI overte jej požiadavky na overenie.

Požiadavky vracajú 429 Too Many Requests

Obmedzte nárazové odosielanie požiadaviek, zaraďte prácu do frontu a opakujte ju po oneskorení vrátenom API. Vyhnite sa paralelným vlnám opakovaných pokusov. Ak jeden kľúč účtu zdieľa viac aplikácií, koordinujte objem ich požiadaviek, pretože zdieľajú limity účtu API.

Kontrolný zoznam odporúčaného nastavenia

Pred pravidelným používaním integrácie overte, že:

• Kľúč je uložený iba v serverovej konfigurácii tajomstiev.
• Požiadavky používajú hlavičku X-API-Key.
• Integrácia v produkcii používa https://api.maildroppa.com.
• Každá metóda, cesta, parameter a telo JSON zodpovedajú dokumentácii OpenAPI.
• Protokoly a hlásenia chýb redigujú kľúč.
• Sú nakonfigurované časové limity a obmedzené opakovania.
• Sledujú sa chyby 401, 403, 429 a chyby servera.
• Je zaznamenaný vlastník integrácie.
• Každý systém zdieľajúci kľúč účtu je zahrnutý do plánu rotácie.
• Kompromitovaný kľúč možno rýchlo otočiť.

Stránka API kľúča je zámerne malá, no jej akcie ovplyvňujú každú API integráciu pripojenú k účtu. Kľúč vytvorte iba vtedy, keď je potrebný, uchovávajte ho na dôveryhodných serveroch a rotáciu plánujte ako zmenu poverenia platnú pre celý účet.