Ustvarite in upravljajte svoj ključ API

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

Stran Ključ API zunanjemu sistemu omogoča preverjen dostop do podprtih končnih točk API-ja Maildroppa v vašem računu.

Ustvarite lahko en ključ API, kopirate njegovo celotno skrivno vrednost, ga varno ponastavite z zamenjavo ali izbrišete, ko ga ne potrebujete več. Isti ključ računa lahko uporabljajo integracije na strani strežnika in sprožilci zahtev API v avtomatizacijah Maildroppa.

Ključ API predstavlja vaš račun Maildroppa. Obravnavajte ga kot geslo: vsak, ki pridobi ključ, lahko kliče končne točke API-ja, ki so temu ključu na voljo, dokler ga ne zamenjate ali izbrišete.

Čemu je ključ API namenjen

Ključ API uporabite, ko mora programska oprema zunaj Maildrope delovati z Maildroppo brez interaktivne prijave uporabnika.

Tipični primeri vključujejo:

• Sinhronizacijo naročnikov s CRM-jem, trgovino, članskim sistemom ali notranjo zbirko podatkov.
• Ustvarjanje ali posodabljanje naročnikov iz strežniške aplikacije.
• Branje ali upravljanje oznak, polj, vrednosti polj in segmentov prek podprtih končnih točk.
• Pošiljanje dogodkov po meri sprožilcu zahtev API v avtomatizaciji.
• Pošiljanje transakcijskih e-poštnih sporočil prek API-ja.
• Upravljanje naročnin na spletne kavlje, ki temeljijo na API-ju.

Ključ API je namenjen komunikaciji med strežniki. Ni namenjen kodi, ki se izvaja v brskalniku obiskovalca, na javnem spletnem mestu, v mobilni aplikaciji ali v vdelanem obrazcu za prijavo.

Stran je trenutno označena kot »beta«. Povezano dokumentacijo OpenAPI uporabite kot vir za končne točke, telesa zahtev, parametre in sheme odgovorov, ki jih API trenutno podpira.

Odpiranje strani Ključ API

Odprite »Settings«, razširite »Developers« in izberite »API key«.

Stran lahko odprete tudi neposredno na naslovu:

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

Stran vsebuje:

• Ploščo ključa API z značko beta.
• Povezavo »View OpenAPI docs«.
• Prazno stanje in gumb »Create API key«, ko ključ ne obstaja.
• Maskirano predstavitev trenutnega ključa, ko ključ obstaja.
• Gumb »Copy«, ki kopira celoten ključ.
• Dejanja »Rotate API key« in »Delete API key« za zamenjavo ali odstranitev trenutnega ključa.

Maildroppa dovoljuje en ključ API na račun. Stran ne ustvarja ločenih ključev za posamezne aplikacije, okolja ali člane ekipe.

Ustvarjanje ključa API

Ko stran prikaže »No API key yet«, kliknite »Create API key«.

Maildroppa ključ ustvari takoj. Pri prvem ustvarjanju ni potrditvenega pogovornega okna. Med izvajanjem zahteve se gumb spremeni v »Creating API key«, stran pa začasno onemogoči nadaljnja dejanja s ključem.

Ko je ključ ustvarjen:

• Prazno stanje izgine.
• Prikaže se maskirani ključ.
• Na voljo postanejo dejanja »Copy«, »Rotate API key« in »Delete API key«.
• Maildroppa prikaže sporočilo o uspehu »API key updated«.

Če za račun že obstaja drug ključ, Maildroppa ne ustvari drugega. Uporabite obstoječi ključ ali ga zamenjajte.

Razumevanje maskiranega ključa

Stran celotne skrivne vrednosti ne izpiše kot običajno besedilo. Prikaže prvih pet znakov, ki jim sledi pet zvezdic, na primer:

a1b2c*****

To je le vizualna maska. Zvezdice ne predstavljajo dejanske dolžine ključa, maskirane vrednosti pa ni mogoče uporabiti za zahtevo API.

Kliknite »Copy«, da celoten trenutni ključ zapišete v odložišče. Po uspešnem kopiranju se gumb za kratek čas spremeni v »Copied!«.

Ko se vrnete na stran, ključ ostane maskiran, vendar »Copy« še naprej kopira celotno trenutno vrednost. Veljavnega ključa zato ni treba zamenjati samo zato, ker ga ob ustvarjanju niste shranili.

Varno shranjevanje ključa

Kopirani ključ neposredno prenesite v shrambo skrivnosti, ki jo uporablja integracija.

Primerna mesta vključujejo:

• Upravljalnik skrivnosti.
• Zaščiteno konfiguracijo okolja strežnika.
• Šifrirano skrivnost za namestitev.
• Upravitelja gesel, ki se uporablja za operativno obnovitev.

Ključa ne shranjujte v:

• JavaScriptu na strani brskalnika ali drugem prenosljivem paketu frontend kode.
• Javni ali zasebni datoteki izvorne kode, predani v repozitorij.
• URL-ju ali parametru poizvedbe.
• Javni dokumentaciji, posnetkih zaslona, sporočilih podpori ali sledilnikih težav.
• Dnevnikih aplikacije v skupni rabi, analitičnih dogodkih ali poročilih o napakah.
• Nešifrirani preglednici ali običajnem skupinskem klepetu.

Ključa ne dodajajte v primer curl, ki bo kopiran v dokumentacijo ali zgodovino lupine, do katere imajo dostop drugi. Raje uporabite spremenljivko okolja, kot je MAILDROPPA_API_KEY.

Uporaba ključa API

Celoten ključ pošljite v glavi HTTP-zahteve X-API-Key:

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

Ne pošiljajte ga kot žeton Bearer. Maildroppa pričakuje X-API-Key, ne Authorization: Bearer ....

Produkcijski API in njegova interaktivna dokumentacija OpenAPI sta na voljo na naslovu:

https://api.maildroppa.com

Na strani Ključ API kliknite »View OpenAPI docs«, da se dokumentacija odpre v novem zavihku brskalnika. Tam izberite končno točko in preglejte njeno metodo, pot, parametre, telo zahteve, vrsto odgovora in možne statusne kode.

Primer zahteve

Naslednji primer pridobi prvo stran naročnikov. Ključ prebere iz spremenljivke okolja, namesto da bi skrivnost vstavil neposredno v ukaz:

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

Spremenljivko nastavite v varnem okolju, v katerem se integracija izvaja. Natančna metoda, pot, parametri poizvedbe in telo so odvisni od končne točke. Te podrobnosti kopirajte iz dokumentacije OpenAPI, namesto da bi jih ugibali na podlagi dejanj, ki so na voljo v aplikaciji Maildroppa.

Zahteve z JSON-telesi

Pri zahtevi, ki pošilja JSON, vključite tudi:

Content-Type: application/json

Osnovna struktura je na primer:

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 in njegovo telo sta nadomestni vrednosti. Zamenjajte ju z dokumentirano končno točko in njeno dokumentirano shemo zahteve.

Do česa lahko ključ dostopa

Ključ deluje samo s končnimi točkami, ki podpirajo preverjanje pristnosti s ključem API. Stran ali zahteva, ki jo interno uporablja aplikacija Maildroppa, ni samodejno del javnega API-ja za stranke.

Dokumentacija OpenAPI prikazuje podprti API za stranke. Če pot ni dokumentirana za uporabo s ključem API, ne predpostavljajte, da ima ključ do nje dostop.

Stran Ključ API ne ponuja obsegov ali potrditvenih polj za dovoljenja po končnih točkah. Trenutni ključ računa je zato treba obravnavati kot zelo pomembno poverilnico, tudi če ena integracija uporablja samo eno končno točko.

Omejitve hitrosti

Trenutna pogodba OpenAPI dokumentira naslednje omejitve za ključ API:

• Privzeti API za stranke: 300 zahtev na minuto in 2.000 zahtev na uro.
• API dogodkov na /events: 100 zahtev na sekundo z zmogljivostjo rafala 500 zahtev.

Te omejitve veljajo za račun Maildroppa in ne ločeno za vsak skript, ki uporablja njegov ključ. Več integracij lahko zato porablja isti dovoljeni obseg.

Ko Maildroppa vrne 429 Too Many Requests, prenehajte pošiljati nove zahteve in upoštevajte glavo odgovora Retry-After, kadar je prisotna. Namesto številnih vzporednih ponovnih poskusov uporabite čakalno vrsto in nadzorovan umik.

Pravila omejevanja hitrosti se lahko med beta obdobjem API-ja spreminjajo. Pred načrtovanjem integracij z velikim obsegom preverite informacije na vrhu dokumentacije OpenAPI.

Uporaba ključa za zahteve API avtomatizacij

Avtomatizacija se lahko začne, ko vaš sistem pošlje dogodek po meri v API dogodkov Maildroppa.

Ko nastavite sprožilec »API request«, Maildroppa uporabi isti ključ API računa, ki ga upravljate na tej strani. Nastavitev sprožilca lahko ustvari ključ, če ta ne obstaja, in kopira pripravljen zahtevek curl, ki vsebuje celoten ključ.

To ima dve pomembni posledici:

• Zamenjava ali brisanje ključa računa vpliva tudi na sisteme, ki pošiljajo dogodke po meri v avtomatizacije.
• Kopiran primer zahteve avtomatizacije vsebuje skrivnost v odložišču, čeprav je ključ na zaslonu maskiran.

Pred zamenjavo ali brisanjem ključa v inventar integracij vključite vsak sprožilec zahteve API in vsakega zunanjega pošiljatelja dogodkov.

Ponastavitev ali zamenjava ključa API

Uporabite »Rotate API key«, ko morate ponastaviti ali zamenjati trenutno poverilnico. Maildroppa v okviru istega dejanja ustvari nov ključ in razveljavi prejšnjega.

Zamenjavo uporabite, ko:

• Je bil ključ morda razkrit.
• Oseba ali ponudnik, ki je poznal ključ, dostopa ne potrebuje več.
• Vaša varnostna politika zahteva občasno zamenjavo poverilnic.
• Želite zamenjati ključ, shranjen na starem ali nezaščitenem mestu.

Pod maskiranim ključem kliknite »Rotate API key«. Maildroppa odpre opozorilno pogovorno okno, ki pojasnjuje, da obstoječega ključa ne bo več mogoče uporabljati.

Za nadaljevanje v pogovornem oknu kliknite »Rotate API key« ali kliknite »Cancel«, da obdržite trenutni ključ.

Zamenjava nima prehodnega obdobja

Ko potrdite zamenjavo, stari ključ takoj preneha delovati. Maildroppa ne ohrani starega in novega ključa veljavnih hkrati.

Ker ima račun samo en ključ, zamenjava vpliva na vsak strežnik, načrtovano opravilo, integracijo, skript in pošiljatelja dogodkov avtomatizacij, ki ga uporablja.

Za načrtovano zamenjavo uporabite naslednje zaporedje:

1. Naštejte vsako integracijo, ki uporablja trenutni ključ.
2. Pripravite dostop do konfiguracije skrivnosti vsake integracije in njenega postopka namestitve.
3. Če je neprekinjen dostop do API-ja pomemben, izberite kratko vzdrževalno obdobje.
4. Kliknite »Rotate API key«, nato v pogovornem oknu potrdite opozorilo s klikom na »Rotate API key«.
5. Kliknite »Copy«, da kopirate celoten novi ključ.
6. Skrivnost takoj zamenjajte v vsaki integraciji.
7. Znova zaženite ali namestite storitve, ki skrivnosti naložijo samo ob zagonu.
8. Pošljite neškodljivo dokumentirano zahtevo, da preverite vsako integracijo.
9. Preverite odzive 401 Unauthorized pozabljene storitve, ki še vedno uporablja stari ključ.

Če menite, da je trenutni ključ ogrožen, ga takoj zamenjajte in sprejmite kratko prekinitev, potrebno za posodobitev legitimnih sistemov.

Brisanje ključa API

Ključ izbrišite, ko račun ne sme več sprejemati zahtev, preverjenih s ključem API.

Pod maskiranim ključem kliknite »Delete API key«. Maildroppa odpre opozorilno pogovorno okno, ki pojasnjuje, da bo ključ trajno odstranjen iz računa.

Za brisanje v pogovornem oknu kliknite »Delete API key« ali kliknite »Cancel«, da ga obdržite.

Po brisanju:

• Trenutni ključ takoj preneha delovati.
• Stran se vrne v stanje »No API key yet«.
• Strežniške integracije, ki uporabljajo izbrisani ključ, se ne morejo več preveriti.
• Pošiljatelji zahtev API avtomatizacij, ki uporabljajo ta ključ, ne morejo več dostavljati dogodkov.

Brisanje ključa ne izbriše naročnikov, kampanj, oznak, polj, segmentov, avtomatizacij ali drugih podatkov računa. Odstrani poverilnico, ki se uporablja za dostop do podprtih končnih točk API-ja.

Pozneje lahko kliknete »Create API key« in ustvarite novo poverilnico. Izbrisana vrednost ni obnovljena. Vsako integracijo je treba posodobiti, preden lahko uporablja novi ključ.

Ponastavitev ali brisanje: kaj izbrati?

Izberite »Rotate API key«, ko naj se dostop do API-ja nadaljuje z novo poverilnico.

Izberite brisanje, ko naj se dostop do API-ja popolnoma ustavi, vsaj za zdaj.

Obe dejanji trenutni ključ takoj razveljavita. Zamenjava ustvari nadomestni ključ v okviru istega dejanja; brisanje pusti račun brez ključa.

Varnostna priporočila

Klice API izvajajte na strežniku

Brskalnik ali mobilna aplikacija ne moreta zanesljivo varovati vdelane skrivnosti. Uporabnik lahko pregleda aplikacijo, glave zahtev, izvorne preslikave ali omrežni promet ter pridobi ključ.

Če mora spletno mesto ali aplikacija sprožiti dejanje, zahtevo najprej pošljite v svoje preverjeno zaledje. Zaledje naj preveri uporabnika in pokliče Maildroppa s ključem, shranjenim na strežniku.

Uporabite najmanjšo možno izpostavljenost

Ključ omogočite samo sistemom, ki ga potrebujejo. Ne razdeljujte ga vsakemu razvijalcu in ga ne prilepite v več lokalnih konfiguracijskih datotek.

Ker stran trenutno upravlja en ključ za celoten račun namesto več imenovanih ključev ali ključev z omejenimi obsegi, uporabite notranjo integracijsko storitev ali posredniški strežnik, če več aplikacij potrebuje močnejšo medsebojno izolacijo.

Maskirajte glave zahtev

Odjemalce HTTP, povratne posredniške strežnike, orodja za opazljivost in poročevalnike napak nastavite tako, da maskirajo X-API-Key. Zahteva lahko deluje pravilno, hkrati pa poverilnico razkrije prek beleženja za odpravljanje napak.

Okolja naj bodo ločena

Produkcijskega ključa ne uporabljajte v lokalnem razvoju, vzorčni kodi, posnetkih zaslona ali testnih pripomočkih. Skrivnosti, specifične za okolje, shranjujte v shrambah skrivnosti, specifičnih za okolje.

Povezava »View OpenAPI docs« uporabnike produkcije samodejno usmeri na dokumentacijo produkcijskega API-ja. Pred pošiljanjem dejanskega ključa vedno preverite ime gostitelja.

Zamenjajte ključ po vsakem sumu razkritja

Brisanje sporočila, potrditve repozitorija, vrstice dnevnika ali posnetka zaslona ne dokazuje, da ključa ni nihče kopiral. Če je bila celotna vrednost razkrita, jo zamenjajte.

Obravnava napak API-ja

S pomočjo statusa HTTP in dokumentiranega telesa odgovora določite, kaj naj integracija stori.

Pogosti primeri vključujejo:

• 400 Bad Request — Pot, parameter ali telo JSON ne ustreza pogodbi končne točke. Zahtevo primerjajte s shemo OpenAPI.
• 401 Unauthorized — Glava X-API-Key manjka, je prazna, neveljavna, izbrisana ali po zamenjavi vsebuje staro vrednost.
• 403 Forbidden — Preverjeni ključ ni dovoljen za to operacijo.
• 404 Not Found — Pot ali navedeni vir v tem računu ne obstaja.
• 429 Too Many Requests — Integracija je dosegla omejitev hitrosti API-ja. Začasno ustavite zahteve in upoštevajte glavo Retry-After, kadar je prisotna.
• 5xx — Maildroppa ni mogel dokončati zahteve. Varne operacije ponovite z omejenim eksponentnim umikom in beleženjem, ki izključi ključ API.

Ne ponavljajte slepo vsake neuspešne zahteve. Preden isto zahtevo pošljete znova, odpravite napake 400, 401, 403 in večino napak 404.

Pri zahtevah, ki spreminjajo podatke, pred samodejnim ponavljanjem preverite vedenje končne točke glede ponovnih poskusov in idempotentnosti. Napaka povezave ne pomeni vedno, da Maildroppa ni izvedel nobene spremembe.

Odpravljanje težav

»Create API key« je še vedno viden

V računu trenutno ni ključa. Enkrat kliknite gumb in počakajte, da se zahteva konča.

Če ustvarjanje ne uspe, pred ponovnim poskusom osvežite stran. Druga stran ali nastavitev avtomatizacije je morda že ustvarila ključ računa.

Ključ na strani je videti prekratek

Stran namerno prikaže samo prvih pet znakov in *****. Kliknite »Copy«, da kopirate celotno vrednost. Maskiranega besedila ne pošiljajte v zahtevi.

»Copy« se ne spremeni v »Copied!«

Brskalnik je morda blokiral dostop do odložišča. Stran pustite v aktivnem zavihku, po pozivu dovolite dostop do odložišča in znova kliknite »Copy«.

Ključa ne poskušajte sestaviti iz maskiranega besedila.

Zahteva vrne 401 Unauthorized

Preverite, ali:

• je ime glave natančno X-API-Key;
• glava vsebuje celotno vrednost brez vidnih zvezdic;
• integracija namesto tega ne pošilja Authorization: Bearer;
• skrivnosti niso bili dodani presledki, narekovaji ali nova vrstica;
• nihče ni zamenjal ali izbrisal ključa računa;
• je bila storitev znova zagnana, če spremenljivke okolja bere samo ob zagonu;
• je zahteva poslana v pravilno okolje API-ja Maildroppa.

Ena integracija deluje, druga pa se je po zamenjavi ustavila

Druga integracija verjetno še vedno uporablja stari ključ. Obdobja prekrivanja ni. Posodobite njeno skrivnost in znova zaženite vsak proces, ki predpomni konfiguracijo.

Stran OpenAPI deluje, vendar končna točka vrne 403

Vsaka končna točka aplikacije ne podpira preverjanja pristnosti s ključem API. Uporabite operacijo, dokumentirano za API za stranke, in na strani OpenAPI preverite njene zahteve glede preverjanja pristnosti.

Zahteve vrnejo 429 Too Many Requests

Zmanjšajte rafale zahtev, postavite delo v čakalno vrsto in ponovite zahtevo po zakasnitvi, ki jo vrne API. Izogibajte se nevihtam vzporednih ponovnih poskusov. Če več aplikacij uporablja isti ključ računa, uskladite obseg zahtev, saj si delijo omejitve API-ja računa.

Priporočeni kontrolni seznam nastavitev

Preden integracijo začnete redno uporabljati, potrdite, da:

• je ključ shranjen samo v strežniški konfiguraciji skrivnosti;
• zahteve uporabljajo glavo X-API-Key;
• integracija v produkciji uporablja https://api.maildroppa.com;
• vsaka metoda, pot, parameter in telo JSON sledijo dokumentaciji OpenAPI;
• dnevniki in poročila o napakah maskirajo ključ;
• so nastavljene časovne omejitve in omejeni ponovni poskusi;
• se spremljajo napake 401, 403, 429 in napake strežnika;
• je zabeležen lastnik integracije;
• je vsak sistem, ki uporablja isti ključ računa, vključen v načrt zamenjave;
• je ogroženi ključ mogoče hitro zamenjati.

Stran Ključ API je namerno majhna, vendar njena dejanja vplivajo na vsako integracijo API-ja, povezano z računom. Ključ ustvarite samo, ko ga potrebujete, hranite ga na zaupanja vrednih strežnikih in zamenjavo načrtujte kot spremembo poverilnice za celoten račun.