Kreirajte i upravljajte svojim API ključem

Published: 16. јул 2026. · Last updated: 21. јул 2026. · By Marcus Biel

Stranica API ključa omogućava eksternom sistemu autentifikovani pristup podržanim Maildroppa API endpointima na vašem nalogu.

Možete kreirati jedan API ključ, kopirati njegovu kompletnu tajnu vrednost, bezbedno ga resetovati rotiranjem ili ga obrisati kada više nije potreban. Isti ključ naloga mogu koristiti integracije na strani servera i okidači API zahteva u Maildroppa Automations.

API ključ predstavlja vaš Maildroppa nalog. Tretirajte ga kao lozinku: svako ko dođe do ključa može pozivati API endpointe dostupne tom ključu dok ga ne rotirate ili obrišete.

Čemu služi API ključ

Koristite API ključ kada softver izvan Maildroppa treba da radi sa Maildroppa bez interaktivne prijave korisnika.

Tipični primeri uključuju:

• Sinhronizaciju pretplatnika sa CRM-om, prodavnicom, sistemom članstva ili internom bazom podataka.
• Kreiranje ili ažuriranje pretplatnika iz aplikacije na strani servera.
• Čitanje ili upravljanje tagovima, poljima, vrednostima polja i segmentima putem podržanih endpointa.
• Slanje prilagođenih događaja okidaču API zahteva u Automation-u.
• Slanje transakcionih Email Messages putem API-ja.
• Upravljanje pretplatama webhookova zasnovanih na API-ju.

API ključ je namenjen komunikaciji server-sa-serverom. Nije namenjen kodu koji se izvršava u pregledaču posetioca, javnom veb-sajtu, mobilnoj aplikaciji ili ugrađenom obrascu za prijavu.

Stranica je trenutno označena kao „beta“. Koristite povezanu OpenAPI dokumentaciju kao izvor za endpointe, tela zahteva, parametre i šeme odgovora koje API trenutno podržava.

Otvaranje stranice API ključa

Otvorite „Settings“, proširite „Developers“ i izaberite „API key“.

Stranicu možete otvoriti i direktno na adresi:

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

Stranica sadrži:

• Panel API ključa sa beta oznakom.
• Link „View OpenAPI docs“.
• Prazno stanje i dugme „Create API key“ kada ključ ne postoji.
• Maskirani prikaz trenutnog ključa kada postoji.
• Dugme „Copy“ koje kopira kompletan ključ.
• Radnje „Rotate API key“ i „Delete API key“ za zamenu ili uklanjanje trenutnog ključa.

Maildroppa dozvoljava jedan API ključ po nalogu. Stranica ne kreira zasebne ključeve za pojedinačne aplikacije, okruženja ili članove tima.

Kreiranje API ključa

Kada se na stranici prikaže „No API key yet“, kliknite na „Create API key“.

Maildroppa odmah kreira ključ. Prilikom prvog kreiranja nema dijaloga za potvrdu. Dok zahtev traje, dugme se menja u „Creating API key“, a stranica privremeno onemogućava dalje radnje nad ključem.

Nakon kreiranja ključa:

• Prazno stanje nestaje.
• Pojavljuje se maskirani ključ.
• Radnje „Copy“, „Rotate API key“ i „Delete API key“ postaju dostupne.
• Maildroppa prikazuje poruku o uspehu „API key updated“.

Ako za nalog već postoji drugi ključ, Maildroppa neće kreirati drugi. Koristite postojeći ključ ili ga rotirajte.

Razumevanje maskiranog ključa

Stranica ne prikazuje kompletnu tajnu kao običan tekst. Prikazuje prvih pet znakova, a zatim pet zvezdica, na primer:

a1b2c*****

Ovo je samo vizuelna maska. Zvezdice ne predstavljaju stvarnu dužinu ključa, a maskirana vrednost ne može da se koristi za API zahtev.

Kliknite na „Copy“ da biste kompletan trenutni ključ upisali u ostavu. Nakon uspešnog kopiranja, dugme se nakratko menja u „Copied!“.

Ključ ostaje maskiran kada se vratite na stranicu, ali „Copy“ i dalje kopira kompletnu trenutnu vrednost. Zato ne morate da rotirate važeći ključ samo zato što ga niste sačuvali prilikom kreiranja.

Bezbedno čuvanje ključa

Prebacite kopirani ključ direktno u skladište tajni koje koristi integracija.

Odgovarajuće lokacije uključuju:

• Upravljani menadžer tajni.
• Zaštićenu konfiguraciju serverskog okruženja.
• Šifrovanu tajnu za deployment.
• Menadžer lozinki koji se koristi za operativni oporavak.

Ne čuvajte ključ u:

• JavaScript-u na strani pregledača ili drugom frontend paketu dostupnom za preuzimanje.
• Javnom ili privatnom izvornom fajlu koda koji je poslat u repozitorijum.
• URL-u ili parametru upita.
• Javnoj dokumentaciji, snimcima ekrana, porukama podršci ili sistemima za praćenje problema.
• Deljenim zapisima aplikacije, analitičkim događajima ili izveštajima o greškama.
• Nešifrovanoj tabeli ili običnom timskom četu.

Ne dodajte ključ u curl primer koji će biti kopiran u dokumentaciju ili deljenu istoriju komandne ljuske. Prednost dajte promenljivoj okruženja kao što je MAILDROPPA_API_KEY.

Korišćenje API ključa

Pošaljite kompletan ključ u HTTP zaglavlju zahteva X-API-Key:

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

Ne šaljite ga kao Bearer token. Maildroppa očekuje X-API-Key, a ne Authorization: Bearer ....

Produkcioni API i njegova interaktivna OpenAPI dokumentacija dostupni su na:

https://api.maildroppa.com

Kliknite na „View OpenAPI docs“ na stranici API ključa da biste otvorili dokumentaciju u novoj kartici pregledača. Tamo izaberite endpoint da biste pregledali njegov metod, putanju, parametre, telo zahteva, tip odgovora i moguće statusne kodove.

Primer zahteva

Sledeći primer preuzima prvu stranicu pretplatnika. Ključ se čita iz promenljive okruženja umesto da se tajna direktno postavi u komandu:

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

Postavite promenljivu u bezbednom okruženju u kojem integracija radi. Tačan metod, putanja, parametri upita i telo zavise od endpointa. Te detalje preuzmite iz OpenAPI dokumentacije umesto da ih pogađate na osnovu radnji dostupnih u Maildroppa aplikaciji.

Zahtevi sa JSON telima

Za zahtev koji šalje JSON uključite i:

Content-Type: application/json

Na primer, 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 telo su rezervisana mesta. Zamenite ih dokumentovanim endpointom i njegovom dokumentovanom šemom zahteva.

Čemu ključ može da pristupi

Ključ funkcioniše samo sa endpointima koji podržavaju autentifikaciju API ključem. Stranica ili zahtev koji se interno koristi u Maildroppa aplikaciji nije automatski deo javnog API-ja za korisnike.

OpenAPI dokumentacija prikazuje podržani API za korisnike. Ako putanja nije dokumentovana za korišćenje API ključa, nemojte pretpostaviti da joj ključ može pristupiti.

Stranica API ključa ne nudi opsege niti polja za potvrdu dozvola po endpointu. Zato trenutnim ključem naloga treba rukovati kao veoma vrednim akreditivom, čak i ako jedna integracija koristi samo jedan endpoint.

Ograničenja brzine

Trenutni OpenAPI ugovor dokumentuje sledeća ograničenja za API ključ:

• Podrazumevani korisnički API: 300 zahteva u minuti i 2.000 zahteva na sat.
• Events API na /events: 100 zahteva u sekundi, uz burst kapacitet od 500 zahteva.

Ova ograničenja se primenjuju na Maildroppa nalog, a ne nezavisno na svaku skriptu koja deli njegov ključ. Više integracija zato može trošiti isti dozvoljeni obim.

Kada Maildroppa vrati 429 Too Many Requests, prestanite da šaljete nove zahteve i poštujte zaglavlje odgovora Retry-After kada je prisutno. Koristite red čekanja i kontrolisano usporavanje umesto pokretanja velikog broja paralelnih ponovnih pokušaja.

Pravila ograničenja brzine mogu se menjati dok je API u beta fazi. Pre projektovanja integracija velikog obima proverite informacije na vrhu OpenAPI dokumentacije.

Korišćenje ključa za API zahteve u Automation-u

Automation može da se pokrene kada vaš sistem pošalje prilagođeni događaj Maildroppa Events API-ju.

Kada konfigurišete okidač „API request“, Maildroppa koristi isti API ključ naloga kojim se upravlja na ovoj stranici. Podešavanje okidača može da kreira ključ kada ne postoji i da kopira pripremljeni curl zahtev koji sadrži kompletan ključ.

To ima dve važne posledice:

• Rotiranje ili brisanje ključa naloga utiče i na sisteme koji šalju prilagođene događaje u Automation-e.
• Kopirani primer Automation zahteva sadrži tajnu u ostavi iako je ključ maskiran na ekranu.

Pre rotiranja ili brisanja ključa uključite svaki okidač API zahteva i svakog eksternog pošiljaoca događaja u inventar integracija.

Resetovanje ili zamena API ključa

Koristite „Rotate API key“ kada treba da resetujete ili zamenite trenutni akreditiv. Maildroppa kreira novi ključ i poništava prethodni kao deo iste radnje.

Rotirajte ključ kada:

• Ključ je možda bio izložen.
• Osobi ili provajderu koji su znali ključ više nije potreban pristup.
• Vaša bezbednosna politika zahteva periodičnu zamenu akreditiva.
• Želite da zamenite ključ sačuvan na staroj ili nebezbednoj lokaciji.

Kliknite na „Rotate API key“ ispod maskiranog ključa. Maildroppa otvara dijalog upozorenja koji objašnjava da postojeći ključ više neće moći da se koristi.

Kliknite na „Rotate API key“ u dijalogu da biste nastavili ili kliknite na „Cancel“ da biste zadržali trenutni ključ.

Rotiranje nema period tolerancije

Nakon potvrde rotiranja, stari ključ odmah prestaje da radi. Maildroppa ne održava stari i novi ključ važećim istovremeno.

Pošto nalog ima samo jedan ključ, rotiranje utiče na svaki server, zakazani posao, integraciju, skriptu i pošiljaoca Automation događaja koji ga koristi.

Za planirano rotiranje koristite sledeći redosled:

1. Navedite svaku integraciju koja koristi trenutni ključ.
2. Pripremite pristup konfiguraciji tajni svake integracije i procesu deploymenta.
3. Izaberite kratak period održavanja ako je neprekidan API pristup važan.
4. Kliknite na „Rotate API key“, a zatim potvrdite upozorenje klikom na „Rotate API key“ u dijalogu.
5. Kliknite na „Copy“ da biste kopirali kompletan novi ključ.
6. Odmah zamenite tajnu u svakoj integraciji.
7. Ponovo pokrenite ili redeployujte servise koji učitavaju tajne samo pri pokretanju.
8. Pošaljite bezopasan, dokumentovan zahtev da biste proverili svaku integraciju.
9. Proverite da li zaboravljeni servis koji i dalje koristi stari ključ vraća odgovore 401 Unauthorized.

Ako se veruje da je trenutni ključ kompromitovan, odmah ga rotirajte i prihvatite kratak prekid potreban za ažuriranje legitimnih sistema.

Brisanje API ključa

Obrišite ključ kada nalog više ne treba da prihvata zahteve autentifikovane API ključem.

Kliknite na „Delete API key“ ispod maskiranog ključa. Maildroppa otvara dijalog upozorenja koji objašnjava da će ključ biti trajno uklonjen sa naloga.

Kliknite na „Delete API key“ u dijalogu da biste ga obrisali ili kliknite na „Cancel“ da biste ga zadržali.

Nakon brisanja:

• Trenutni ključ odmah prestaje da radi.
• Stranica se vraća u stanje „No API key yet“.
• Serverske integracije koje koriste obrisani ključ više ne mogu da se autentifikuju.
• Pošiljaoci Automation API zahteva koji koriste taj ključ više ne mogu da isporučuju događaje.

Brisanje ključa ne briše pretplatnike, kampanje, tagove, polja, segmente, Automation-e niti druge podatke naloga. Uklanja akreditiv koji se koristi za pristup podržanim API endpointima.

Kasnije možete kliknuti na „Create API key“ da biste kreirali novi akreditiv. Obrisana vrednost se ne vraća. Svaka integracija mora biti ažurirana pre nego što može da koristi novi ključ.

Resetovanje ili brisanje: šta izabrati?

Izaberite „Rotate API key“ kada API pristup treba da se nastavi sa novim akreditivom.

Izaberite brisanje kada API pristup treba potpuno obustaviti, barem za sada.

Obe radnje odmah poništavaju trenutni ključ. Rotiranje kreira zamenu kao deo iste radnje; brisanje ostavlja nalog bez ključa.

Bezbednosne preporuke

API pozive držite na serveru

Pregledač ili mobilna aplikacija ne mogu pouzdano da čuvaju ugrađenu tajnu. Korisnik može da pregleda aplikaciju, zaglavlja zahteva, source mape ili mrežni saobraćaj i izdvoji ključ.

Ako veb-sajtu ili aplikaciji treba da pokrene radnju, prvo pošaljite zahtev sopstvenom autentifikovanom backendu. Dozvolite tom backendu da proveri korisnika i pozove Maildroppa ključem sačuvanim na serveru.

Koristite najmanju moguću izloženost

Dajte ključ samo sistemima kojima je potreban. Ne distribuirajte ga svakom programeru niti ga unosite u više lokalnih konfiguracionih fajlova.

Pošto stranica trenutno upravlja jednim ključem za ceo nalog, umesto više imenovanih ključeva ili ključeva sa opsezima, koristite internu integracionu uslugu ili proxy ako je većem broju aplikacija potrebna jača međusobna izolacija.

Redigujte zaglavlja zahteva

Podesite HTTP klijente, reverse proxy-je, alate za observabilnost i izveštače o greškama tako da rediguju X-API-Key. Zahtev može ispravno da radi, a da ipak procuri akreditiv kroz zapisivanje za otklanjanje grešaka.

Držite zasebna okruženja odvojenim

Ne koristite produkcioni ključ u lokalnom razvoju, primerima koda, snimcima ekrana ili testnim podacima. Tajne specifične za okruženje čuvajte u skladištima tajni specifičnim za to okruženje.

Link „View OpenAPI docs“ automatski upućuje produkcione korisnike na dokumentaciju produkcionog API-ja. Uvek proverite hostname pre slanja stvarnog ključa.

Rotirajte nakon svake sumnje na izlaganje

Brisanje poruke, commita u repozitorijumu, reda u zapisu ili snimka ekrana ne dokazuje da niko nije kopirao ključ. Ako je kompletna vrednost bila izložena, rotirajte je.

Obrada API grešaka

Koristite HTTP status i dokumentovano telo odgovora da biste odlučili šta integracija treba da uradi.

Uobičajeni slučajevi uključuju:

• 400 Bad Request — Putanja, parametar ili JSON telo ne ispunjava ugovor endpointa. Uporedite zahtev sa OpenAPI šemom.
• 401 Unauthorized — Zaglavlje X-API-Key nedostaje, prazno je, nevažeće, obrisano ili sadrži staru vrednost nakon rotiranja.
• 403 Forbidden — Autentifikovani ključ nije dozvoljen za tu operaciju.
• 404 Not Found — Putanja ili navedeni resurs ne postoji na ovom nalogu.
• 429 Too Many Requests — Integracija je dostigla ograničenje brzine API-ja. Pauzirajte zahteve i poštujte zaglavlje Retry-After kada je prisutno.
• 5xx — Maildroppa nije mogao da dovrši zahtev. Bezbedne operacije ponavljajte uz ograničeno eksponencijalno usporavanje i zapisivanje koje isključuje API ključ.

Nemojte slepo ponavljati svaki neuspeh. Ispravite odgovore 400, 401, 403 i većinu odgovora 404 pre nego što ponovo pošaljete isti zahtev.

Kod zahteva koji menjaju podatke proverite ponašanje endpointa pri ponovnom pokušaju i njegovu idempotentnost pre automatskog ponavljanja zahteva. Prekid veze ne dokazuje uvek da Maildroppa nije izvršio promenu.

Rešavanje problema

„Create API key“ je i dalje vidljivo

Na nalogu trenutno ne postoji ključ. Kliknite na dugme jednom i sačekajte da se zahtev završi.

Ako kreiranje ne uspe, ponovo učitajte stranicu pre novog pokušaja. Druga stranica ili Automation podešavanje možda su već kreirali ključ naloga.

Ključ na stranici izgleda prekratko

Stranica namerno prikazuje samo prvih pet znakova i *****. Kliknite na „Copy“ da biste kopirali kompletnu vrednost. Ne šaljite maskirani tekst u zahtevu.

„Copy“ se ne menja u „Copied!“

Pregledač je možda blokirao pristup ostavi. Ostavite stranicu u aktivnoj kartici, dozvolite pristup ostavi ako se to zatraži i ponovo kliknite na „Copy“.

Ne pokušavajte da rekonstruišete ključ iz maskiranog teksta.

Zahtev vraća 401 Unauthorized

Proverite da li:

• Naziv zaglavlja tačno glasi X-API-Key.
• Zaglavlje sadrži kompletnu vrednost, bez vidljivih zvezdica.
• Integracija umesto toga ne šalje Authorization: Bearer.
• Tajni vrednosti nisu dodati razmaci, navodnici ili novi red.
• Niko nije rotirao ili obrisao ključ naloga.
• Servis je ponovo pokrenut ako promenljive okruženja čita samo pri pokretanju.
• Zahtev se šalje ispravnom Maildroppa API okruženju.

Jedna integracija radi, a druga je prestala nakon rotiranja

Druga integracija verovatno i dalje koristi stari ključ. Ne postoji period preklapanja. Ažurirajte njenu tajnu i ponovo pokrenite svaki proces koji kešira konfiguraciju.

OpenAPI stranica radi, ali endpoint vraća 403

Ne podržava svaki endpoint aplikacije autentifikaciju API ključem. Koristite operaciju dokumentovanu za korisnički API i potvrdite njene zahteve za autentifikaciju na OpenAPI stranici.

Zahtevi vraćaju 429 Too Many Requests

Smanjite burst zahteva, stavite posao u red čekanja i pokušajte ponovo nakon kašnjenja koje API vrati. Izbegavajte oluje paralelnih ponovnih pokušaja. Ako više aplikacija deli jedan ključ naloga, uskladite njihov obim zahteva jer dele ograničenja API-ja naloga.

Preporučena kontrolna lista za podešavanje

Pre nego što integraciju počnete redovno da koristite, potvrdite da:

• Ključ se čuva samo u serverskoj konfiguraciji tajni.
• Zahtevi koriste zaglavlje X-API-Key.
• Integracija u produkciji koristi https://api.maildroppa.com.
• Svaki metod, putanja, parametar i JSON telo prate OpenAPI dokumentaciju.
• Zapisi i izveštaji o greškama rediguju ključ.
• Podešeni su vremenska ograničenja i ograničeni ponovni pokušaji.
• Prate se greške 401, 403, 429 i serverske greške.
• Vlasnik integracije je evidentiran.
• Svaki sistem koji deli ključ naloga uključen je u plan rotiranja.
• Kompromitovani ključ može brzo da se rotira.

Stranica API ključa je namerno mala, ali njene radnje utiču na svaku API integraciju povezanu sa nalogom. Kreirajte ključ samo kada je potreban, čuvajte ga na pouzdanim serverima i planirajte rotiranje kao promenu akreditiva na nivou celog naloga.