Izradite i upravljajte svojim API ključem

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

Stranica API ključa vanjskom sustavu omogućuje autentificirani pristup podržanim krajnjim točkama Maildroppa API-ja u vašem računu.

Možete izraditi jedan API ključ, kopirati njegovu potpunu tajnu vrijednost, sigurno ga poništiti rotiranjem ili ga izbrisati kada vam više nije potreban. Isti ključ računa mogu upotrebljavati integracije na strani poslužitelja i okidači API zahtjeva u Maildroppa Automatizacijama.

API ključ predstavlja vaš Maildroppa račun. Tretirajte ga kao lozinku: svatko tko dođe do ključa može pozivati krajnje točke API-ja dostupne tom ključu dok ga ne rotirate ili izbrišete.

Čemu služi API ključ

Upotrijebite API ključ kada softver izvan Maildroppa treba raditi s Maildroppom bez interaktivne prijave korisnika.

Uobičajeni primjeri uključuju:

• Sinkronizaciju pretplatnika s CRM-om, trgovinom, članskim sustavom ili internom bazom podataka.
• Izradu ili ažuriranje pretplatnika iz aplikacije na strani poslužitelja.
• Čitanje ili upravljanje oznakama, poljima, vrijednostima polja i segmentima putem podržanih krajnjih točaka.
• Slanje prilagođenih događaja okidaču API zahtjeva u Automatizaciji.
• Slanje transakcijskih poruka e-pošte putem API-ja.
• Upravljanje pretplatama na webhookove temeljene na API-ju.

API ključ namijenjen je komunikaciji između poslužitelja. Nije namijenjen kodu koji se izvršava u pregledniku posjetitelja, javnom web-mjestu, mobilnoj aplikaciji ili ugrađenom obrascu za prijavu.

Stranica je trenutačno označena kao „beta”. Povezanu OpenAPI dokumentaciju upotrebljavajte kao izvor za krajnje točke, tijela zahtjeva, parametre i sheme odgovora koje API trenutačno podržava.

Otvaranje stranice API ključa

Otvorite „Postavke”, proširite „Razvojni programeri” i odaberite „API ključ”.

Stranicu možete otvoriti i izravno na:

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

Stranica sadrži:

• Ploče API ključa s oznakom beta.
• Poveznicu „Prikaži OpenAPI dokumentaciju”.
• Prazno stanje i gumb „Izradi API ključ” kada ne postoji nijedan ključ.
• Maskirani prikaz trenutačnog ključa kada ključ postoji.
• Gumb „Kopiraj” koji kopira cijeli ključ.
• Radnje „Rotiraj API ključ” i „Izbriši API ključ” za zamjenu ili uklanjanje trenutačnog ključa.

Maildroppa dopušta jedan API ključ po računu. Stranica ne izrađuje zasebne ključeve za pojedinačne aplikacije, okruženja ili članove tima.

Izrada API ključa

Kada se na stranici prikaže „Još nema API ključa”, kliknite „Izradi API ključ”.

Maildroppa odmah izrađuje ključ. Pri prvom stvaranju nema dijaloškog okvira za potvrdu. Dok je zahtjev u tijeku, gumb se mijenja u „Izrada API ključa”, a stranica privremeno onemogućuje daljnje radnje s ključem.

Nakon izrade ključa:

• Prazno stanje nestaje.
• Prikazuje se maskirani ključ.
• Postaju dostupne radnje „Kopiraj”, „Rotiraj API ključ” i „Izbriši API ključ”.
• Maildroppa prikazuje poruku o uspjehu „API ključ ažuriran”.

Ako za račun već postoji drugi ključ, Maildroppa neće izraditi drugi. Upotrijebite postojeći ključ ili ga rotirajte.

Razumijevanje maskiranog ključa

Stranica ne ispisuje cijelu tajnu kao običan tekst. Prikazuje prvih pet znakova, a zatim pet zvjezdica, na primjer:

a1b2c*****

Ovo je samo vizualno maskiranje. Zvjezdice ne predstavljaju stvarnu duljinu ključa, a maskirana vrijednost ne može se upotrijebiti za API zahtjev.

Kliknite „Kopiraj” kako biste cijeli trenutačni ključ kopirali u međuspremnik. Nakon uspješnog kopiranja gumb se nakratko mijenja u „Kopirano!”.

Ključ ostaje maskiran kada se vratite na stranicu, ali „Kopiraj” i dalje kopira cijelu trenutačnu vrijednost. Stoga ne morate rotirati valjani ključ samo zato što ga niste spremili prilikom izrade.

Sigurno pohranjivanje ključa

Kopirani ključ odmah premjestite u sigurno spremište koje upotrebljava integracija.

Prikladne lokacije uključuju:

• Upravljani upravitelj tajni.
• Zaštićenu konfiguraciju okruženja poslužitelja.
• Šifriranu tajnu za implementaciju.
• Upravitelj lozinki koji se upotrebljava za operativni oporavak.

Ne pohranjujte ključ u:

• JavaScript na strani preglednika ili drugi frontend paket koji se može preuzeti.
• Javnu ili privatnu datoteku izvornog koda predanu u repozitorij.
• URL ili parametar upita.
• Javnu dokumentaciju, snimke zaslona, poruke podršci ili sustave za praćenje problema.
• Dijeljene zapisnike aplikacije, analitičke događaje ili izvješća o pogreškama.
• Nešifriranu proračunsku tablicu ili običan timski razgovor.

Ne dodajte ključ u primjer curl naredbe koji će se kopirati u dokumentaciju ili zajedničku povijest ljuske. Umjesto toga upotrijebite varijablu okruženja kao što je MAILDROPPA_API_KEY.

Upotreba API ključa

Cijeli ključ pošaljite u HTTP zaglavlju zahtjeva X-API-Key:

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

Nemojte ga slati kao Bearer token. Maildroppa očekuje X-API-Key, a ne Authorization: Bearer ....

Produkcijski API i njegova interaktivna OpenAPI dokumentacija dostupni su na:

https://api.maildroppa.com

Kliknite „Prikaži OpenAPI dokumentaciju” na stranici API ključa kako biste dokumentaciju otvorili u novoj kartici preglednika. Ondje odaberite krajnju točku kako biste pregledali njezinu metodu, putanju, parametre, tijelo zahtjeva, vrstu odgovora i moguće statusne kodove.

Primjer zahtjeva

Sljedeći primjer dohvaća prvu stranicu pretplatnika. Ključ čita iz varijable okruženja umjesto da tajnu izravno postavlja u naredbu:

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

Varijablu postavite u sigurnom okruženju u kojem se integracija izvršava. Točna metoda, putanja, parametri upita i tijelo ovise o krajnjoj točki. Te pojedinosti kopirajte iz OpenAPI dokumentacije, umjesto da ih nagađate na temelju radnji dostupnih u aplikaciji Maildroppa.

Zahtjevi s JSON tijelima

Za zahtjev koji šalje JSON uključite i:

Content-Type: application/json

Na primjer, osnovna struktura je:

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 njegovo tijelo rezervirane su vrijednosti. Zamijenite ih dokumentiranom krajnjom točkom i njezinom dokumentiranom shemom zahtjeva.

Čemu ključ može pristupiti

Ključ funkcionira samo s krajnjim točkama koje podržavaju autentifikaciju API ključem. Stranica ili zahtjev koji se interno upotrebljava u aplikaciji Maildroppa nije automatski dio javnog API-ja za korisnike.

OpenAPI dokumentacija prikazuje podržani API za korisnike. Ako putanja nije dokumentirana za upotrebu API ključa, nemojte pretpostaviti da joj ključ može pristupiti.

Stranica API ključa ne nudi opsege ni potvrdne okvire za dopuštenja po krajnjim točkama. Stoga se s trenutačnim ključem računa treba postupati kao s vjerodajnicom visoke vrijednosti, čak i ako jedna integracija upotrebljava samo jednu krajnju točku.

Ograničenja brzine

Trenutačni OpenAPI ugovor dokumentira ova ograničenja za API ključ:

• Zadani API za korisnike: 300 zahtjeva u minuti i 2.000 zahtjeva u satu.
• API za događaje na /events: 100 zahtjeva u sekundi uz kapacitet burst-a od 500 zahtjeva.

Ta se ograničenja primjenjuju na račun Maildroppa, a ne neovisno na svaku skriptu koja dijeli njegov ključ. Stoga više integracija može trošiti isto dopuštenje.

Kada Maildroppa vrati 429 Too Many Requests, prestanite slati nove zahtjeve i poštujte zaglavlje odgovora Retry-After kada je prisutno. Upotrijebite red čekanja i kontrolirano postupno povećavanje čekanja umjesto pokretanja brojnih paralelnih ponovnih pokušaja.

Pravila ograničenja brzine mogu se mijenjati dok je API u beta verziji. Prije projektiranja integracija velikog opsega provjerite informacije na vrhu OpenAPI dokumentacije.

Upotreba ključa za API zahtjeve Automatizacije

Automatizacija se može pokrenuti kada vaš sustav pošalje prilagođeni događaj Maildroppa Events API-ju.

Kada konfigurirate okidač „API zahtjev”, Maildroppa upotrebljava isti API ključ računa kojim se upravlja na ovoj stranici. Postavljanje okidača može izraditi ključ kada ne postoji i kopirati pripremljeni curl zahtjev koji sadrži cijeli ključ.

To ima dvije važne posljedice:

• Rotiranje ili brisanje ključa računa utječe i na sustave koji šalju prilagođene događaje Automatizacijama.
• Kopirani primjer zahtjeva Automatizacije sadrži tajnu u međuspremniku iako je ključ na zaslonu maskiran.

Prije rotiranja ili brisanja ključa u svoj popis integracija uključite svaki okidač API zahtjeva i svakog vanjskog pošiljatelja događaja.

Poništavanje ili zamjena API ključa

Upotrijebite „Rotiraj API ključ” kada trebate poništiti ili zamijeniti trenutačnu vjerodajnicu. Maildroppa izrađuje novi ključ i poništava prethodni kao dio iste radnje.

Rotaciju upotrijebite kada:

• Ključ je možda bio izložen.
• Osoba ili pružatelj koji su znali ključ više ne trebaju pristup.
• Vaša sigurnosna politika zahtijeva periodičnu zamjenu vjerodajnica.
• Želite zamijeniti ključ pohranjen na staroj ili nesigurnoj lokaciji.

Kliknite „Rotiraj API ključ” ispod maskiranog ključa. Maildroppa otvara dijaloški okvir upozorenja koji objašnjava da se postojeći ključ više neće moći upotrebljavati.

Kliknite „Rotiraj API ključ” u dijaloškom okviru za nastavak ili kliknite „Odustani” kako biste zadržali trenutačni ključ.

Rotacija nema prijelazno razdoblje

Nakon potvrde rotacije stari ključ odmah prestaje raditi. Maildroppa ne zadržava stari i novi ključ valjanima istodobno.

Budući da račun ima samo jedan ključ, rotacija utječe na svaki poslužitelj, zakazani zadatak, integraciju, skriptu i pošiljatelja događaja Automatizacije koji ga upotrebljava.

Za planiranu rotaciju upotrijebite ovaj slijed:

1. Navedite svaku integraciju koja upotrebljava trenutačni ključ.
2. Pripremite pristup konfiguraciji tajni i postupku implementacije svake integracije.
3. Odaberite kratki prozor održavanja ako je neprekinuti pristup API-ju važan.
4. Kliknite „Rotiraj API ključ”, a zatim potvrdite upozorenje klikom na „Rotiraj API ključ” u dijaloškom okviru.
5. Kliknite „Kopiraj” kako biste kopirali cijeli novi ključ.
6. Odmah zamijenite tajnu u svakoj integraciji.
7. Ponovno pokrenite ili ponovno implementirajte usluge koje učitavaju tajne samo pri pokretanju.
8. Pošaljite bezopasan dokumentirani zahtjev kako biste provjerili svaku integraciju.
9. Provjerite postoje li odgovori 401 Unauthorized zaboravljene usluge koja još upotrebljava stari ključ.

Ako se vjeruje da je trenutačni ključ ugrožen, odmah ga rotirajte i prihvatite kratki prekid potreban za ažuriranje legitimnih sustava.

Brisanje API ključa

Izbrišite ključ kada račun više ne bi trebao prihvaćati zahtjeve autentificirane API ključem.

Kliknite „Izbriši API ključ” ispod maskiranog ključa. Maildroppa otvara dijaloški okvir upozorenja koji objašnjava da će ključ biti trajno uklonjen iz računa.

Kliknite „Izbriši API ključ” u dijaloškom okviru kako biste ga izbrisali ili kliknite „Odustani” kako biste ga zadržali.

Nakon brisanja:

• Trenutačni ključ odmah prestaje raditi.
• Stranica se vraća u stanje „Još nema API ključa”.
• Integracije poslužitelja koje upotrebljavaju izbrisani ključ više se ne mogu autentificirati.
• Pošiljatelji API zahtjeva Automatizacije koji upotrebljavaju taj ključ više ne mogu isporučivati događaje.

Brisanje ključa ne briše pretplatnike, kampanje, oznake, polja, segmente, Automatizacije ni druge podatke računa. Uklanja vjerodajnicu koja se upotrebljava za pristup podržanim krajnjim točkama API-ja.

Kasnije možete kliknuti „Izradi API ključ” kako biste izradili novu vjerodajnicu. Izbrisana vrijednost ne vraća se. Svaka integracija mora se ažurirati prije nego što može upotrebljavati novi ključ.

Poništavanje ili brisanje: što odabrati?

Odaberite „Rotiraj API ključ” kada API pristup treba nastaviti s novom vjerodajnicom.

Odaberite brisanje kada API pristup treba potpuno prestati, barem zasad.

Obje radnje odmah poništavaju trenutačni ključ. Rotacija izrađuje zamjenu u sklopu iste radnje; brisanje ostavlja račun bez ključa.

Sigurnosne preporuke

API pozive zadržite na svom poslužitelju

Preglednik ili mobilna aplikacija ne mogu pouzdano čuvati ugrađenu tajnu. Korisnik može pregledati aplikaciju, zaglavlja zahtjeva, izvorne mape ili mrežni promet i izvući ključ.

Ako web-mjesto ili aplikacija treba pokrenuti radnju, najprije pošaljite zahtjev vlastitoj autentificiranoj pozadini. Dopustite toj pozadini da potvrdi korisnika i pozove Maildroppa ključem pohranjenim na poslužitelju.

Upotrijebite najmanju moguću izloženost

Ključ dajte samo sustavima kojima je potreban. Ne distribuirajte ga svakom programeru niti ga lijepite u više lokalnih konfiguracijskih datoteka.

Budući da stranica trenutačno upravlja jednim ključem za cijeli račun, umjesto više imenovanih ključeva ili ključeva s opsezima, upotrijebite internu integracijsku uslugu ili proxy ako je većem broju aplikacija potrebna snažnija međusobna izolacija.

Maskirajte zaglavlja zahtjeva

Konfigurirajte HTTP klijente, obrnute proxyje, alate za nadzor i alate za prijavu pogrešaka tako da maskiraju X-API-Key. Zahtjev može ispravno raditi, a da pritom i dalje otkriva vjerodajnicu putem zapisivanja za otklanjanje pogrešaka.

Odvojite okruženja

Ne upotrebljavajte produkcijski ključ ponovno u lokalnom razvoju, primjeru koda, snimkama zaslona ili testnim podacima. Tajne specifične za okruženje pohranjujte u spremištima tajni specifičnima za to okruženje.

Poveznica „Prikaži OpenAPI dokumentaciju” automatski usmjerava produkcijske korisnike na dokumentaciju produkcijskog API-ja. Uvijek provjerite naziv hosta prije slanja stvarnog ključa.

Rotirajte nakon svake sumnje na izlaganje

Brisanje poruke, predaje u repozitorij, retka zapisnika ili snimke zaslona ne dokazuje da nitko nije kopirao ključ. Ako je cijela vrijednost bila izložena, rotirajte je.

Rješavanje pogrešaka API-ja

Upotrijebite HTTP status i dokumentirano tijelo odgovora kako biste odlučili što integracija treba učiniti.

Uobičajeni slučajevi uključuju:

• 400 Bad Request — Putanja, parametar ili JSON tijelo ne zadovoljava ugovor krajnje točke. Usporedite zahtjev sa shemom OpenAPI-ja.
• 401 Unauthorized — Zaglavlje X-API-Key nedostaje, prazno je, nevažeće, izbrisano ili sadrži staru vrijednost nakon rotacije.
• 403 Forbidden — Autentificirani ključ nema dopuštenje za tu operaciju.
• 404 Not Found — Putanja ili navedeni resurs ne postoji u ovom računu.
• 429 Too Many Requests — Integracija je dosegla ograničenje brzine API-ja. Pauzirajte zahtjeve i poštujte zaglavlje Retry-After kada je prisutno.
• 5xx — Maildroppa nije mogao dovršiti zahtjev. Sigurne operacije ponovite uz ograničeno eksponencijalno povećavanje čekanja i zapisivanje koje isključuje API ključ.

Nemojte slijepo ponavljati svaki neuspjeh. Ispravite odgovore 400, 401, 403 i većinu odgovora 404 prije ponovnog slanja istog zahtjeva.

Za zahtjeve koji mijenjaju podatke potvrdite ponašanje krajnje točke pri ponovnom pokušaju i njezino ponašanje idempotentnosti prije automatskog ponavljanja zahtjeva. Neuspjeh veze ne dokazuje uvijek da Maildroppa nije napravio nikakvu promjenu.

Otklanjanje poteškoća

„Izradi API ključ” i dalje je vidljivo

U računu trenutačno ne postoji ključ. Jednom kliknite gumb i pričekajte da zahtjev završi.

Ako izrada ne uspije, ponovno učitajte stranicu prije novog pokušaja. Druga stranica ili postavljanje Automatizacije možda je već izradilo ključ računa.

Ključ na stranici izgleda prekratko

Stranica namjerno prikazuje samo prvih pet znakova i *****. Kliknite „Kopiraj” kako biste kopirali cijelu vrijednost. Maskirani tekst nemojte slati u zahtjevu.

„Kopiraj” se ne mijenja u „Kopirano!”

Preglednik je možda blokirao pristup međuspremniku. Ostavite stranicu u aktivnoj kartici, dopustite pristup međuspremniku ako se to zatraži i ponovno kliknite „Kopiraj”.

Ne pokušavajte rekonstruirati ključ iz maskiranog teksta.

Zahtjev vraća 401 Unauthorized

Provjerite sljedeće:

• Naziv zaglavlja točno je X-API-Key.
• Zaglavlje sadrži cijelu vrijednost, bez vidljivih zvjezdica.
• Integracija umjesto toga ne šalje Authorization: Bearer.
• Tajni vrijednosti nisu dodani razmaci, navodnici ili novi redak.
• Nitko nije rotirao ili izbrisao ključ računa.
• Usluga je ponovno pokrenuta ako varijable okruženja čita samo pri pokretanju.
• Zahtjev se šalje ispravnom Maildroppa API okruženju.

Jedna integracija radi, ali druga je prestala raditi nakon rotacije

Druga integracija vjerojatno još upotrebljava stari ključ. Ne postoji razdoblje preklapanja. Ažurirajte njezinu tajnu i ponovno pokrenite svaki proces koji predmemorira konfiguraciju.

Stranica OpenAPI radi, ali krajnja točka vraća 403

Ne podržavaju sve krajnje točke aplikacije autentifikaciju API ključem. Upotrijebite operaciju dokumentiranu za API za korisnike i potvrdite njezine zahtjeve za autentifikaciju na stranici OpenAPI.

Zahtjevi vraćaju 429 Too Many Requests

Smanjite burstove zahtjeva, stavite posao u red čekanja i pokušajte ponovno nakon kašnjenja koje API vrati. Izbjegavajte oluje paralelnih ponovnih pokušaja. Ako više aplikacija dijeli jedan ključ računa, uskladite njihov obujam zahtjeva jer dijele ograničenja API-ja računa.

Preporučeni kontrolni popis za postavljanje

Prije nego što integraciju počnete redovito upotrebljavati, potvrdite sljedeće:

• Ključ se pohranjuje samo u konfiguraciji tajni na strani poslužitelja.
• Zahtjevi upotrebljavaju zaglavlje X-API-Key.
• Integracija u produkciji upotrebljava https://api.maildroppa.com.
• Svaka metoda, putanja, parametar i JSON tijelo slijede OpenAPI dokumentaciju.
• Zapisnici i izvješća o pogreškama maskiraju ključ.
• Konfigurirani su vremenska ograničenja i ograničeni ponovni pokušaji.
• Prate se pogreške 401, 403, 429 i pogreške poslužitelja.
• Zabilježen je vlasnik integracije.
• Svaki sustav koji dijeli ključ računa uključen je u plan rotacije.
• Ugroženi ključ može se brzo rotirati.

Stranica API ključa namjerno je mala, ali njezine radnje utječu na svaku API integraciju povezanu s računom. Ključ izradite samo kada je potreban, čuvajte ga na pouzdanim poslužiteljima i planirajte rotaciju kao promjenu vjerodajnice na razini cijelog računa.