Vytvoření a správa API klíče

Published: 16. července 2026 · Last updated: 21. července 2026 · By Marcus Biel

Stránka API klíče poskytuje externímu systému ověřený přístup k podporovaným koncovým bodům Maildroppa API ve vašem účtu.

Můžete vytvořit jeden API klíč, zkopírovat jeho úplnou tajnou hodnotu, bezpečně jej resetovat rotací nebo jej smazat, když už není potřeba. Stejný klíč účtu lze použít pro serverové integrace i pro spouštěče API požadavků v Maildroppa Automations.

API klíč reprezentuje váš účet Maildroppa. Zacházejte s ním jako s heslem: kdokoli, kdo klíč získá, může volat koncové body API dostupné pro tento klíč, dokud jej nezrotujete nebo nesmažete.

K čemu API klíč slouží

API klíč použijte, když software mimo Maildroppa potřebuje pracovat s Maildroppou bez interaktivního přihlášení uživatele.

Typické příklady:

• Synchronizace odběratelů s CRM, obchodem, členským systémem nebo interní databází.
• Vytváření nebo aktualizace odběratelů ze serverové aplikace.
• Čtení nebo správa štítků, polí, hodnot polí a segmentů prostřednictvím podporovaných koncových bodů.
• Odesílání vlastních událostí do spouštěče API požadavků v Automation.
• Odesílání transakčních e-mailových zpráv prostřednictvím API.
• Správa odběrů webhooků založených na API.

API klíč je určen pro komunikaci mezi servery. Není určen pro kód běžící v prohlížeči návštěvníka, na veřejném webu, v mobilní aplikaci ani ve vloženém registračním formuláři.

Stránka je momentálně označena jako „beta“. Pro aktuálně podporované koncové body, těla požadavků, parametry a schémata odpovědí použijte odkazovanou dokumentaci OpenAPI.

Otevření stránky API klíče

Otevřete „Settings“, rozbalte „Developers“ a vyberte „API key“.

Stránku můžete otevřít také přímo na adrese:

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

Stránka obsahuje:

• Panel API klíče s odznakem beta.
• Odkaz „View OpenAPI docs“.
• Prázdný stav a tlačítko „Create API key“, pokud žádný klíč neexistuje.
• Maskovanou podobu aktuálního klíče, pokud existuje.
• Tlačítko „Copy“, které zkopíruje úplný klíč.
• Akce „Rotate API key“ a „Delete API key“ pro nahrazení nebo odebrání aktuálního klíče.

Maildroppa povoluje jeden API klíč na účet. Stránka nevytváří samostatné klíče pro jednotlivé aplikace, prostředí ani členy týmu.

Vytvoření API klíče

Když stránka zobrazuje „No API key yet“, klikněte na „Create API key“.

Maildroppa klíč vytvoří okamžitě. Při prvním vytvoření se nezobrazuje potvrzovací dialog. Během zpracování požadavku se tlačítko změní na „Creating API key“ a stránka dočasně deaktivuje další akce s klíčem.

Po vytvoření klíče:

• Prázdný stav zmizí.
• Zobrazí se maskovaný klíč.
• Zpřístupní se akce „Copy“, „Rotate API key“ a „Delete API key“.
• Maildroppa zobrazí úspěšnou zprávu „API key updated“.

Pokud pro účet již existuje jiný klíč, Maildroppa nevytvoří druhý. Použijte stávající klíč nebo jej zrotujte.

Porozumění maskovanému klíči

Stránka nezobrazuje úplný tajný klíč jako běžný text. Zobrazuje prvních pět znaků následovaných pěti hvězdičkami, například:

a1b2c*****

Jde pouze o vizuální maskování. Hvězdičky nepředstavují skutečnou délku klíče a maskovanou hodnotu nelze použít pro API požadavek.

Kliknutím na „Copy“ zapíšete úplný aktuální klíč do schránky. Po úspěšném zkopírování se tlačítko krátce změní na „Copied!“.

Po návratu na stránku zůstane klíč maskovaný, ale tlačítko „Copy“ nadále kopíruje úplnou aktuální hodnotu. Platný klíč proto nemusíte rotovat jen proto, že jste si jej při vytvoření neuložili.

Bezpečné uložení klíče

Zkopírovaný klíč ihned přesuňte do úložiště tajných údajů, které integrace používá.

Vhodná místa zahrnují:

• Spravovaný správce tajných údajů.
• Chráněnou konfiguraci serverového prostředí.
• Šifrovaný tajný údaj nasazení.
• Správce hesel používaný pro provozní obnovu.

Klíč neukládejte do:

• JavaScriptu na straně prohlížeče ani jiného frontendového balíčku ke stažení.
• Veřejného ani soukromého souboru zdrojového kódu uloženého v repozitáři.
• URL ani parametru dotazu.
• Veřejné dokumentace, snímků obrazovky, zpráv podpoře ani systémů pro sledování problémů.
• Sdílených aplikačních protokolů, analytických událostí ani hlášení chyb.
• Nešifrované tabulky ani běžného týmového chatu.

Nepřidávejte klíč do příkladu curl, který bude kopírován do dokumentace nebo sdílené historie shellu. Upřednostněte proměnnou prostředí, například MAILDROPPA_API_KEY.

Použití API klíče

Úplný klíč odešlete v HTTP hlavičce požadavku X-API-Key:

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

Neposílejte jej jako Bearer token. Maildroppa očekává X-API-Key, nikoli Authorization: Bearer ....

Produkční API a jeho interaktivní dokumentace OpenAPI jsou dostupné na adrese:

https://api.maildroppa.com

Kliknutím na „View OpenAPI docs“ na stránce API klíče otevřete dokumentaci v nové kartě prohlížeče. Zde vyberte koncový bod a prohlédněte si jeho metodu, cestu, parametry, tělo požadavku, typ odpovědi a možné stavové kódy.

Příklad požadavku

Následující příklad načte první stránku odběratelů. Klíč čte z proměnné prostředí, místo aby tajný údaj vkládal přímo do příkazu:

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

Proměnnou nastavte v zabezpečeném prostředí, ve kterém integrace běží. Přesná metoda, cesta, parametry dotazu a tělo závisí na koncovém bodu. Tyto údaje přebírejte z dokumentace OpenAPI, místo abyste je odhadovali podle akcí dostupných v aplikaci Maildroppa.

Požadavky s těly JSON

U požadavku, který odesílá JSON, uveďte také:

Content-Type: application/json

Základní struktura například vypadá 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 tělo jsou zástupné hodnoty. Nahraďte je zdokumentovaným koncovým bodem a jeho zdokumentovaným schématem požadavku.

K čemu má klíč přístup

Klíč funguje pouze s koncovými body, které podporují ověřování pomocí API klíče. Stránka nebo požadavek používaný interně aplikací Maildroppa není automaticky součástí veřejného API pro zákazníky.

Dokumentace OpenAPI zobrazuje podporované zákaznické API. Pokud cesta není zdokumentována pro použití s API klíčem, nepředpokládejte, že k ní klíč může přistupovat.

Stránka API klíče nenabízí rozsahy oprávnění ani zaškrtávací políčka oprávnění pro jednotlivé koncové body. S aktuálním klíčem účtu je proto nutné zacházet jako s vysoce hodnotným přihlašovacím údajem, i když jedna integrace používá pouze jediný koncový bod.

Limity rychlosti

Aktuální smlouva OpenAPI dokumentuje tyto limity pro API klíče:

• Výchozí zákaznické API: 300 požadavků za minutu a 2 000 požadavků za hodinu.
• Events API na /events: 100 požadavků za sekundu s kapacitou špičky 500 požadavků.

Tyto limity se uplatňují na účet Maildroppa, nikoli nezávisle na každý skript, který jeho klíč sdílí. Několik integrací proto může spotřebovávat stejný limit.

Když Maildroppa vrátí 429 Too Many Requests, přestaňte odesílat nové požadavky a dodržte hlavičku odpovědi Retry-After, pokud je přítomna. Použijte frontu a řízené postupné prodlužování prodlev namísto spouštění mnoha paralelních opakování.

Zásady limitů rychlosti se mohou během beta provozu API měnit. Před návrhem integrací s vysokým objemem zkontrolujte informace v horní části dokumentace OpenAPI.

Použití klíče pro API požadavky Automation

Automation se může spustit, když váš systém odešle vlastní událost do Events API Maildroppa.

Když nakonfigurujete spouštěč „API request“, Maildroppa použije stejný klíč účtu API spravovaný na této stránce. Nastavení spouštěče může klíč vytvořit, pokud žádný neexistuje, a může zkopírovat připravený požadavek curl obsahující úplný klíč.

To má dva důležité důsledky:

• Rotace nebo smazání klíče účtu ovlivní také systémy, které odesílají vlastní události do Automations.
• Zkopírovaný příklad požadavku Automation obsahuje tajný údaj ve schránce, přestože je klíč na obrazovce maskovaný.

Před rotací nebo smazáním klíče zahrňte do inventáře integrací každý spouštěč API požadavků i každý externí odesílač událostí.

Resetování nebo nahrazení API klíče

K resetování nebo nahrazení aktuálního přihlašovacího údaje použijte „Rotate API key“. Maildroppa v rámci stejné akce vytvoří nový klíč a zneplatní předchozí.

Rotaci použijte, když:

• Klíč mohl být odhalen.
• Osoba nebo poskytovatel, který klíč znal, již přístup nepotřebuje.
• Vaše bezpečnostní zásady vyžadují pravidelnou výměnu přihlašovacích údajů.
• Chcete nahradit klíč uložený na starém nebo nezabezpečeném místě.

Klikněte na „Rotate API key“ pod maskovaným klíčem. Maildroppa otevře varovný dialog s vysvětlením, že stávající klíč již nebude použitelný.

Pokračujte kliknutím na „Rotate API key“ v dialogu, nebo kliknutím na „Cancel“ ponechte aktuální klíč.

Rotace nemá přechodné období

Po potvrzení rotace přestane starý klíč okamžitě fungovat. Maildroppa neponechává starý a nový klíč platné současně.

Protože účet má pouze jeden klíč, rotace ovlivní každý server, plánovanou úlohu, integraci, skript a odesílač událostí Automation, který jej používá.

Při plánované rotaci postupujte takto:

1. Sepište všechny integrace, které používají aktuální klíč.
2. Připravte přístup ke konfiguraci tajných údajů a procesu nasazení každé integrace.
3. Pokud je důležitý nepřerušený přístup k API, zvolte krátké servisní okno.
4. Klikněte na „Rotate API key“ a poté potvrďte varování kliknutím na „Rotate API key“ v dialogu.
5. Kliknutím na „Copy“ zkopírujte úplný nový klíč.
6. Okamžitě nahraďte tajný údaj ve všech integracích.
7. Restartujte nebo znovu nasaďte služby, které načítají tajné údaje pouze při spuštění.
8. Odesláním neškodného zdokumentovaného požadavku ověřte každou integraci.
9. Zkontrolujte odpovědi 401 Unauthorized od zapomenuté služby, která stále používá starý klíč.

Pokud se domníváte, že aktuální klíč byl kompromitován, okamžitě jej zrotujte a přijměte krátké přerušení nutné k aktualizaci oprávněných systémů.

Smazání API klíče

Klíč smažte, když účet již nemá přijímat požadavky ověřené pomocí API klíče.

Klikněte na „Delete API key“ pod maskovaným klíčem. Maildroppa otevře varovný dialog s vysvětlením, že klíč bude z účtu trvale odstraněn.

Klíč smažete kliknutím na „Delete API key“ v dialogu, nebo jej ponecháte kliknutím na „Cancel“.

Po smazání:

• Aktuální klíč přestane okamžitě fungovat.
• Stránka se vrátí do stavu „No API key yet“.
• Serverové integrace používající smazaný klíč se již nemohou ověřit.
• Odesílače API požadavků Automation používající tento klíč již nemohou doručovat události.

Smazání klíče nesmaže odběratele, kampaně, štítky, pole, segmenty, Automations ani jiná data účtu. Odstraní přihlašovací údaj používaný pro přístup k podporovaným koncovým bodům API.

Později můžete kliknutím na „Create API key“ vytvořit nový přihlašovací údaj. Smazaná hodnota nebude obnovena. Každou integraci je nutné aktualizovat, než bude moci nový klíč používat.

Resetovat, nebo smazat: co zvolit?

„Rotate API key“ zvolte, když má přístup k API pokračovat s novým přihlašovacím údajem.

Smazání zvolte, když má být přístup k API úplně zastaven, alespoň prozatím.

Obě akce okamžitě zneplatní aktuální klíč. Rotace vytvoří náhradu v rámci stejné akce; smazání ponechá účet bez klíče.

Bezpečnostní doporučení

API volání provádějte na serveru

Prohlížeč ani mobilní aplikace nedokážou spolehlivě uchovat vložený tajný údaj. Uživatel může prozkoumat aplikaci, hlavičky požadavků, zdrojové mapy nebo síťový provoz a klíč získat.

Pokud web nebo aplikace potřebuje spustit akci, odešlete požadavek nejprve na vlastní ověřený backend. Backend ověří uživatele a zavolá Maildroppa s klíčem uloženým na serveru.

Minimalizujte vystavení

Klíč poskytujte pouze systémům, které jej potřebují. Nerozdávejte jej každému vývojáři ani jej nevkládejte do více místních konfiguračních souborů.

Protože stránka aktuálně spravuje jeden klíč pro celý účet namísto více pojmenovaných klíčů nebo klíčů s omezeným rozsahem, použijte interní integrační službu nebo proxy, pokud několik aplikací potřebuje silnější vzájemné oddělení.

Redigujte hlavičky požadavků

Nastavte HTTP klienty, reverzní proxy, nástroje pro observabilitu a hlášení chyb tak, aby redigovaly X-API-Key. Požadavek může fungovat správně a přitom odhalit přihlašovací údaj prostřednictvím ladicích protokolů.

Udržujte prostředí oddělená

Produkční klíč znovu nepoužívejte v lokálním vývoji, ukázkovém kódu, snímcích obrazovky ani testovacích případech. Tajné údaje pro jednotlivá prostředí ukládejte do úložišť tajných údajů určených pro daná prostředí.

Odkaz „View OpenAPI docs“ automaticky směruje uživatele v produkci na dokumentaci produkčního API. Před odesláním skutečného klíče vždy ověřte název hostitele.

Po jakémkoli podezření na odhalení klíč zrotujte

Smazání zprávy, commitu v repozitáři, řádku protokolu nebo snímku obrazovky nedokazuje, že klíč nikdo nezkopíroval. Pokud byla odhalena úplná hodnota, zrotujte ji.

Řešení chyb API

Podle HTTP stavového kódu a zdokumentovaného těla odpovědi rozhodněte, co má integrace udělat.

Mezi běžné případy patří:

• 400 Bad Request — Cesta, parametr nebo tělo JSON nesplňuje smlouvu koncového bodu. Porovnejte požadavek se schématem OpenAPI.
• 401 Unauthorized — Hlavička X-API-Key chybí, je prázdná, neplatná, smazaná nebo po rotaci obsahuje starou hodnotu.
• 403 Forbidden — Ověřený klíč nemá oprávnění tuto operaci použít.
• 404 Not Found — Cesta nebo odkazovaný zdroj v tomto účtu neexistuje.
• 429 Too Many Requests — Integrace dosáhla limitu rychlosti API. Pozastavte požadavky a dodržte hlavičku Retry-After, pokud je přítomna.
• 5xx — Maildroppa nemohla požadavek dokončit. Bezpečné operace opakujte s omezeným exponenciálním prodlužováním prodlev a s protokolováním, které vylučuje API klíč.

Neopakujte slepě každé selhání. Před opětovným odesláním stejného požadavku opravte odpovědi 400, 401, 403 a většinu odpovědí 404.

U požadavků měnících data si před automatickým opakováním ověřte chování koncového bodu při opakování a jeho idempotenci. Selhání připojení neznamená vždy, že Maildroppa neprovedla žádnou změnu.

Řešení problémů

„Create API key“ je stále viditelné

V účtu aktuálně neexistuje žádný klíč. Jednou klikněte na tlačítko a počkejte na dokončení požadavku.

Pokud vytvoření selže, před dalším pokusem stránku znovu načtěte. Jiná stránka nebo nastavení Automation již mohly klíč účtu vytvořit.

Klíč na stránce vypadá příliš krátký

Stránka záměrně zobrazuje pouze prvních pět znaků a *****. Kliknutím na „Copy“ zkopírujete úplnou hodnotu. Maskovaný text v požadavku neposílejte.

„Copy“ se nezmění na „Copied!“

Prohlížeč mohl zablokovat přístup ke schránce. Ponechte stránku v aktivní kartě, případně povolte přístup ke schránce a znovu klikněte na „Copy“.

Nepokoušejte se klíč rekonstruovat z maskovaného textu.

Požadavek vrací 401 Unauthorized

Zkontrolujte, že:

• Název hlavičky je přesně X-API-Key.
• Hlavička obsahuje úplnou hodnotu bez viditelných hvězdiček.
• Integrace místo toho neodesílá Authorization: Bearer.
• Do tajného údaje nebyly přidány mezery, uvozovky ani nový řádek.
• Nikdo klíč účtu nezrotoval ani nesmazal.
• Služba byla restartována, pokud načítá proměnné prostředí pouze při spuštění.
• Požadavek je odesílán do správného prostředí Maildroppa API.

Jedna integrace funguje, ale druhá po rotaci přestala

Druhá integrace pravděpodobně stále používá starý klíč. Neexistuje období překryvu. Aktualizujte její tajný údaj a restartujte každý proces, který ukládá konfiguraci do mezipaměti.

Stránka OpenAPI funguje, ale koncový bod vrací 403

Ne každý koncový bod aplikace podporuje ověřování pomocí API klíče. Použijte operaci zdokumentovanou pro zákaznické API a na stránce OpenAPI ověřte její požadavky na ověřování.

Požadavky vracejí 429 Too Many Requests

Omezte špičky požadavků, zařaďte práci do fronty a opakujte požadavky až po prodlevě vrácené API. Vyhněte se paralelním lavinám opakování. Pokud jeden klíč účtu sdílí několik aplikací, koordinujte objem jejich požadavků, protože sdílejí limity účtu API.

Doporučený kontrolní seznam nastavení

Před uvedením integrace do běžného provozu ověřte, že:

• Klíč je uložen pouze v konfiguraci tajných údajů na straně serveru.
• Požadavky používají hlavičku X-API-Key.
• Integrace v produkci používá https://api.maildroppa.com.
• Každá metoda, cesta, parametr a tělo JSON odpovídá dokumentaci OpenAPI.
• Protokoly a hlášení chyb klíč redigují.
• Jsou nastaveny timeouty a omezená opakování.
• Jsou monitorovány chyby 401, 403, 429 a chyby serveru.
• Je zaznamenán vlastník integrace.
• Každý systém sdílející klíč účtu je zahrnut do plánu rotace.
• Kompromitovaný klíč lze rychle zrotovat.

Stránka API klíče je záměrně malá, ale její akce ovlivňují každou integraci API připojenou k účtu. Klíč vytvářejte pouze v případě potřeby, uchovávejte jej na důvěryhodných serverech a plánujte rotaci jako změnu přihlašovacího údaje pro celý účet.