API-võtme loomine ja haldamine

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

API-võtme leht annab välisele süsteemile autentitud juurdepääsu teie konto toetatud Maildroppa API lõpp-punktidele.

Saate luua ühe API-võtme, kopeerida selle täieliku salajase väärtuse, lähtestada selle turvaliselt pööramise teel või kustutada, kui seda enam vaja pole. Sama konto võtit saab kasutada serveripoolsetes integratsioonides ja Maildroppa Automationsi API-päringu päästikutes.

API-võti esindab teie Maildroppa kontot. Kohelge seda nagu parooli: igaüks, kes võtme hangib, saab kasutada sellele võtmele kättesaadavaid API lõpp-punkte seni, kuni te võtme pöörate või kustutate.

Milleks API-võti on mõeldud

Kasutage API-võtit siis, kui Maildroppast väljas olev tarkvara peab Maildroppaga töötama ilma interaktiivse kasutaja sisselogimiseta.

Tüüpilised näited:

• Tellijate sünkroonimine CRM-i, poe, liikmesussüsteemi või siseandmebaasiga.
• Tellijate loomine või uuendamine serveripoolsest rakendusest.
• Siltide, väljade, väljade väärtuste ja segmentide lugemine või haldamine toetatud lõpp-punktide kaudu.
• Kohandatud sündmuste saatmine Automationsi API-päringu päästikule.
• Tehinguliste Email Messagesi saatmine API kaudu.
• API-põhiste veebikonksu tellimuste haldamine.

API-võti on mõeldud serveritevaheliseks suhtluseks. See ei ole mõeldud koodile, mis töötab külastaja brauseris, avalikul veebisaidil, mobiilirakenduses või manustatud registreerumisvormis.

Leht on praegu tähistatud märkega „beta”. Kasutage lingitud OpenAPI dokumentatsiooni praegu API toetatud lõpp-punktide, päringukehade, parameetrite ja vastuseskeemide allikana.

API-võtme lehe avamine

Avage „Settings”, laiendage „Developers” ja valige „API key”.

Lehe saate avada ka otse aadressil:

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

Lehel on:

• API-võtme paneel beeta-märgisega.
• Link „View OpenAPI docs”.
• Tühi olek ja nupp „Create API key”, kui võtit pole.
• Praeguse võtme maskeeritud esitus, kui võti on olemas.
• Nupp „Copy”, mis kopeerib täieliku võtme.
• Toimingud „Rotate API key” ja „Delete API key” praeguse võtme asendamiseks või eemaldamiseks.

Maildroppa lubab konto kohta ühe API-võtme. Leht ei loo eraldi võtmeid üksikute rakenduste, keskkondade ega meeskonnaliikmete jaoks.

API-võtme loomine

Kui lehel kuvatakse „No API key yet”, klõpsake „Create API key”.

Maildroppa loob võtme kohe. Esmakordsel loomisel kinnituse dialoogi ei kuvata. Päringu töötlemise ajal muutub nupu tekstiks „Creating API key” ja leht keelab ajutiselt edasised võtmega seotud toimingud.

Pärast võtme loomist:

• Tühi olek kaob.
• Kuvatakse maskeeritud võti.
• Saadaval on toimingud „Copy”, „Rotate API key” ja „Delete API key”.
• Maildroppa kuvab eduteate „API key updated”.

Kui kontol on juba teine võti, ei loo Maildroppa teist võtit. Kasutage olemasolevat võtit või pöörake seda.

Maskeeritud võtme mõistmine

Leht ei kuva täielikku salajast väärtust tavalise tekstina. Kuvatakse viis esimest märki, millele järgneb viis tärni, näiteks:

a1b2c*****

See on ainult visuaalne mask. Tärnid ei tähista võtme tegelikku pikkust ja maskeeritud väärtust ei saa API-päringus kasutada.

Klõpsake „Copy”, et kirjutada praegune täielik võti lõikelauale. Pärast edukat kopeerimist muutub nupu tekst lühikeseks ajaks kujule „Copied!”.

Lehele naastes jääb võti maskeerituks, kuid „Copy” kopeerib endiselt praeguse täieliku väärtuse. Seetõttu ei pea kehtivat võtit pöörama üksnes sellepärast, et te ei salvestanud seda loomise ajal.

Võtme turvaline salvestamine

Viige kopeeritud võti otse integratsiooni kasutatavasse saladuste hoidlasse.

Sobivad asukohad on näiteks:

• Hallatav saladuste haldur.
• Kaitstud serveri keskkonnakonfiguratsioon.
• Krüptitud juurutussaladus.
• Operatiivseks taastamiseks kasutatav paroolihaldur.

Ärge salvestage võtit:

• Brauseripoolsesse JavaScripti ega muusse allalaaditavasse kasutajaliidese paketti.
• Avalikku või privaatsesse lähtekoodifaili, mis on hoidlasse sisse kantud.
• URL-i või päringuparameetrisse.
• Avalikku dokumentatsiooni, ekraanipiltidesse, tugisõnumitesse või probleemijälgijatesse.
• Jagatud rakenduse logidesse, analüütikasündmustesse või veateadetesse.
• Krüptimata tabelarvutustabelisse või tavalisse meeskonnavestlusse.

Ärge lisage võtit curl-i näitesse, mida kopeeritakse dokumentatsiooni või teistega jagatud shelli ajalukku. Eelistage keskkonnamuutujat, näiteks MAILDROPPA_API_KEY.

API-võtme kasutamine

Saatke täielik võti HTTP-päringu päises X-API-Key:

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

Ärge saatke seda Beareri märgina. Maildroppa ootab päist X-API-Key, mitte päist Authorization: Bearer ....

Tootmis-API ja interaktiivne OpenAPI dokumentatsioon on saadaval aadressil:

https://api.maildroppa.com

Klõpsake API-võtme lehel „View OpenAPI docs”, et avada dokumentatsioon uuel brauserivahekaardil. Valige seal lõpp-punkt, et vaadata selle meetodit, teed, parameetreid, päringu keha, vastuse tüüpi ja võimalikke olekukoode.

Näidispäring

Järgnev näide hangib tellijate esimese lehekülje. See loeb võtme keskkonnamuutujast, selle asemel et paigutada saladus otse käsusse:

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

Määrake muutuja turvalises keskkonnas, kus integratsioon töötab. Täpne meetod, tee, päringuparameetrid ja keha sõltuvad lõpp-punktist. Kopeerige need üksikasjad OpenAPI dokumentatsioonist, mitte ärge tuletage neid Maildroppa rakenduses saadaolevatest toimingutest.

JSON-kehaga päringud

JSON-i saatva päringu korral lisage ka:

Content-Type: application/json

Näiteks on põhistruktuur järgmine:

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 ja selle keha on kohatäited. Asendage need dokumenteeritud lõpp-punkti ja selle dokumenteeritud päringuskeemiga.

Millele võtmel on juurdepääs

Võti töötab ainult lõpp-punktidega, mis toetavad API-võtmepõhist autentimist. Maildroppa rakendusesiseselt kasutatav leht või päring ei kuulu automaatselt avalikku kliendi-API-sse.

OpenAPI dokumentatsioon näitab toetatud kliendi-API-t. Kui tee ei ole API-võtme kasutamiseks dokumenteeritud, ärge eeldage, et võtmel on sellele juurdepääs.

API-võtme leht ei paku skoope ega lõpp-punktipõhiseid õiguste märkeruute. Seetõttu tuleb praegust kontovõtit käsitleda suure väärtusega autentimisvahendina isegi siis, kui üks integratsioon kasutab ainult üht lõpp-punkti.

Päringupiirangud

Praegune OpenAPI leping dokumenteerib järgmised API-võtme piirangud:

• Kliendi vaike-API: 300 päringut minutis ja 2 000 päringut tunnis.
• Events API aadressil /events: 100 päringut sekundis, purskevõimega 500 päringut.

Neid piiranguid rakendatakse Maildroppa kontole, mitte eraldi igale võtmega jagatud skriptile. Seetõttu võivad mitu integratsiooni sama lubatud mahtu kasutada.

Kui Maildroppa tagastab 429 Too Many Requests, lõpetage uute päringute saatmine ja järgige vastuse päist Retry-After, kui see on olemas. Paljude paralleelsete korduskatsete alustamise asemel kasutage järjekorda ja kontrollitud tagasipöördumist.

Päringupiirangute eeskirjad võivad API beetaversiooni ajal muutuda. Enne suure mahuga integratsioonide kavandamist kontrollige OpenAPI dokumentatsiooni ülaosas olevat teavet.

Võtme kasutamine Automationsi API-päringute jaoks

Automation võib käivituda, kui teie süsteem saadab Maildroppa Eventsi API-le kohandatud sündmuse.

Kui seadistate „API request” päästiku, kasutab Maildroppa sama konto API-võtit, mida sellel lehel hallatakse. Kui võtit pole, võib päästiku seadistus võtme luua ning kopeerida ettevalmistatud curl-päringu, mis sisaldab täielikku võtit.

Sellel on kaks olulist tagajärge:

• Konto võtme pööramine või kustutamine mõjutab ka süsteeme, mis saadavad Automationsile kohandatud sündmusi.
• Kopeeritud Automationi päringunäide sisaldab saladust lõikelaual, kuigi võti on ekraanil maskeeritud.

Enne võtme pööramist või kustutamist lisage oma integratsioonide loendisse kõik API-päringu päästikud ja kõik välised sündmuste saatjad.

API-võtme lähtestamine või asendamine

Kasutage „Rotate API key”, kui peate praeguse autentimisvahendi lähtestama või asendama. Maildroppa loob uue võtme ja muudab eelmise võtme kehtetuks sama toimingu käigus.

Kasutage pööramist, kui:

• Võti võis lekkida.
• Isik või teenusepakkuja, kes võtit teadis, ei vaja enam juurdepääsu.
• Teie turvapoliitika nõuab autentimisvahendi regulaarset asendamist.
• Soovite asendada vanasse või ebaturvalisse asukohta salvestatud võtme.

Klõpsake maskeeritud võtme all „Rotate API key”. Maildroppa avab hoiatusdialoogi, mis selgitab, et olemasolevat võtit ei saa enam kasutada.

Jätkamiseks klõpsake dialoogis „Rotate API key” või praeguse võtme säilitamiseks „Cancel”.

Pööramisel ajapikendust ei ole

Pärast pööramise kinnitamist lakkab vana võti kohe töötamast. Maildroppa ei hoia vana ja uut võtit samal ajal kehtivana.

Kuna kontol on ainult üks võti, mõjutab pööramine kõiki servereid, ajastatud tööülesandeid, integratsioone, skripte ja Automationi sündmuste saatjaid, mis seda kasutavad.

Kavandatud pööramisel kasutage järgmist järjestust:

1. Loetlege kõik integratsioonid, mis praegust võtit kasutavad.
2. Valmistage ette juurdepääs iga integratsiooni saladuste konfiguratsioonile ja juurutusprotsessile.
3. Kui katkestusteta API-juurdepääs on oluline, valige lühike hooldusaken.
4. Klõpsake „Rotate API key” ja kinnitage hoiatus, klõpsates dialoogis „Rotate API key”.
5. Klõpsake „Copy”, et kopeerida täielik uus võti.
6. Asendage saladus kohe igas integratsioonis.
7. Taaskäivitage või juurutage uuesti teenused, mis laadivad saladusi ainult käivitamisel.
8. Saatke iga integratsiooni kontrollimiseks ohutu ja dokumenteeritud päring.
9. Otsige 401 Unauthorized vastuseid unustatud teenuselt, mis kasutab endiselt vana võtit.

Kui arvate, et praegune võti on sattunud ohtu, pöörake seda kohe ja arvestage lühikese katkestusega, mis on vajalik õiguspäraste süsteemide uuendamiseks.

API-võtme kustutamine

Kustutage võti siis, kui konto ei peaks enam API-võtmepõhiseid autentitud päringuid vastu võtma.

Klõpsake maskeeritud võtme all „Delete API key”. Maildroppa avab hoiatusdialoogi, mis selgitab, et võti eemaldatakse kontolt jäädavalt.

Kustutamiseks klõpsake dialoogis „Delete API key” või võtme säilitamiseks „Cancel”.

Pärast kustutamist:

• Praegune võti lakkab kohe töötamast.
• Leht naaseb olekusse „No API key yet”.
• Kustutatud võtit kasutavad serveriintegratsioonid ei saa enam autentida.
• Seda võtit kasutavad Automationi API-päringu saatjad ei saa enam sündmusi edastada.

Võtme kustutamine ei kustuta tellijaid, kampaaniaid, silte, välju, segmente, Automationsi ega muid kontoandmeid. See eemaldab toetatud API lõpp-punktidele juurdepääsuks kasutatud autentimisvahendi.

Uue autentimisvahendi loomiseks võite hiljem klõpsata „Create API key”. Kustutatud väärtust ei taastata. Iga integratsiooni tuleb enne uue võtme kasutamist uuendada.

Lähtestamine või kustutamine: kumma peaksite valima?

Valige „Rotate API key”, kui API-juurdepääs peaks uue autentimisvahendiga jätkuma.

Valige kustutamine, kui API-juurdepääs peaks vähemalt praegu täielikult lõppema.

Mõlemad toimingud muudavad praeguse võtme kohe kehtetuks. Pööramine loob asendusvõtme sama toimingu käigus; kustutamine jätab konto võtmeta.

Turvasoovitused

Hoidke API-päringud oma serveris

Brauser või mobiilirakendus ei suuda manustatud saladust usaldusväärselt kaitsta. Kasutaja saab rakendust, päringupäiseid, lähtekaarte või võrguliiklust uurida ja võtme kätte saada.

Kui veebisait või rakendus peab toimingu käivitama, saatke päring esmalt oma autentitud taustateenusele. Laske sellel taustateenusel kasutaja valideerida ja kutsuda Maildroppat serverisse salvestatud võtmega.

Minimeerige kokkupuude

Andke võti ainult süsteemidele, mis seda vajavad. Ärge jagage seda iga arendajaga ega kleepige mitmesse kohalikku konfiguratsioonifaili.

Kuna leht haldab praegu mitme nimega või skoopidega võtmete asemel üht kogu kontot hõlmavat võtit, kasutage sisemist integratsiooniteenust või puhverserverit, kui mitu rakendust vajavad üksteisest tugevamat isoleeritust.

Peitke päringupäised

Seadistage HTTP-kliendid, pöördpuhverserverid, jälgitavustööriistad ja veateadete saatjad nii, et X-API-Key oleks logides varjatud. Päring võib õigesti töötada, kuid selle autentimisvahend võib siiski silumislogide kaudu lekkida.

Hoidke keskkonnad eraldi

Ärge kasutage tootmisvõtit kohalikus arenduses, näidiskoodis, ekraanipiltides ega testandmetes. Salvestage keskkonnapõhised saladused keskkonnapõhistesse saladuste hoidlatesse.

Link „View OpenAPI docs” suunab tootmiskasutajad automaatselt tootmis-API dokumentatsiooni. Enne tegeliku võtme saatmist kontrollige alati hostinime.

Pöörake võtit pärast võimalikku leket

Sõnumi, hoidla sissekande, logirea või ekraanipildi kustutamine ei tõesta, et keegi võtit ei kopeerinud. Kui täielik väärtus lekkis, pöörake võtit.

API-vigade käsitlemine

Kasutage HTTP olekut ja dokumenteeritud vastuse keha, et otsustada, mida integratsioon peaks tegema.

Levinud juhud on järgmised:

• 400 Bad Request — Tee, parameeter või JSON-keha ei vasta lõpp-punkti lepingule. Võrrelge päringut OpenAPI skeemiga.
• 401 Unauthorized — X-API-Key päis puudub, on tühi või kehtetu, võti on kustutatud või pärast pööramist kasutatakse vana väärtust.
• 403 Forbidden — Autenditud võtmel pole selle toimingu kasutamiseks õigust.
• 404 Not Found — Teed või viidatud ressurssi selles kontos ei ole.
• 429 Too Many Requests — Integratsioon on jõudnud API päringupiiranguni. Peatage päringud ja järgige päist Retry-After, kui see on olemas.
• 5xx — Maildroppa ei saanud päringut lõpule viia. Korrake ohutuid toiminguid piiratud eksponentsiaalse tagasipöördumisega ja logimisega, mis välistab API-võtme.

Ärge korrake pimesi iga ebaõnnestunud päringut. Parandage 400, 401, 403 ja enamik 404 vastuseid enne sama päringu uuesti saatmist.

Muudatusi tegevate päringute korral kontrollige enne automaatset kordamist lõpp-punkti korduskatsete ja idempotentsuse käitumist. Ühenduse katkemine ei tõesta alati, et Maildroppa muudatust ei teinud.

Tõrkeotsing

„Create API key” on endiselt nähtav

Kontol pole praegu võtit. Klõpsake nuppu üks kord ja oodake päringu lõppemist.

Kui loomine ebaõnnestub, laadige leht enne uut katset uuesti. Mõni teine leht või Automationi seadistus võis konto võtme juba luua.

Lehel olev võti tundub liiga lühike

Leht kuvab sihilikult ainult viis esimest märki ja *****. Täieliku väärtuse kopeerimiseks klõpsake „Copy”. Ärge saatke päringus maskeeritud teksti.

„Copy” ei muutu tekstiks „Copied!”

Brauser võis lõikelaua juurdepääsu blokeerida. Hoidke leht aktiivsel vahekaardil, lubage küsimise korral lõikelaua juurdepääs ja klõpsake uuesti „Copy”.

Ärge proovige võtit maskeeritud teksti põhjal taastada.

Päring tagastab 401 Unauthorized

Kontrollige järgmist:

• Päise nimi on täpselt X-API-Key.
• Päis sisaldab täielikku väärtust ilma nähtavate tärnideta.
• Integratsioon ei saada selle asemel Authorization: Bearer päist.
• Saladusele ei lisatud tühikuid, jutumärke ega reavahetust.
• Keegi ei ole konto võtit pööranud ega kustutanud.
• Teenus taaskäivitati, kui see loeb keskkonnamuutujaid ainult käivitamisel.
• Päring saadetakse õigesse Maildroppa API-keskkonda.

Üks integratsioon töötab, kuid teine lakkas pärast pööramist

Teine integratsioon kasutab tõenäoliselt endiselt vana võtit. Üleminekuperioodi ei ole. Uuendage selle saladus ja taaskäivitage kõik konfiguratsiooni vahemällu salvestavad protsessid.

OpenAPI leht töötab, kuid lõpp-punkt tagastab 403

Mitte iga rakenduse lõpp-punkt ei toeta API-võtmepõhist autentimist. Kasutage kliendi-API jaoks dokumenteeritud toimingut ja kinnitage selle autentimisnõuded OpenAPI lehel.

Päringud tagastavad 429 Too Many Requests

Vähendage päringupurskeid, pange töö järjekorda ja korrake päringut pärast API tagastatud viivitust. Vältige paralleelsete korduskatsete torme. Kui mitu rakendust jagavad üht konto võtit, koordineerige nende päringumahtu, sest nad jagavad konto API piiranguid.

Soovitatav seadistuse kontrollnimekiri

Enne integratsiooni regulaarset kasutuselevõttu veenduge, et:

• Võti on salvestatud ainult serveripoolsesse saladuste konfiguratsiooni.
• Päringud kasutavad päist X-API-Key.
• Integratsioon kasutab tootmises aadressi https://api.maildroppa.com.
• Iga meetod, tee, parameeter ja JSON-keha vastab OpenAPI dokumentatsioonile.
• Logid ja veateated varjavad võtme.
• Ajalõpud ja piiratud korduskatsed on seadistatud.
• 401, 403, 429 ja serverivead on jälgimise all.
• Integratsiooni omanik on registreeritud.
• Kõik süsteemid, mis konto võtit jagavad, on pööramisplaani kaasatud.
• Ohustatud võtit saab kiiresti pöörata.

API-võtme leht on teadlikult väike, kuid selle toimingud mõjutavad kõiki kontoga ühendatud API-integratsioone. Looge võti ainult siis, kui seda vaja on, hoidke seda usaldusväärsetes serverites ja kavandage pööramine kogu kontot hõlmava autentimisvahendi muudatusena.