Sukurkite ir tvarkykite savo API raktą

Published: 2026 m. liepos 16 d. · Last updated: 2026 m. liepos 21 d. · By Marcus Biel

API rakto puslapis suteikia išorinei sistemai autentifikuotą prieigą prie jūsų paskyroje palaikomų Maildroppa API galinių taškų.

Galite sukurti vieną API raktą, nukopijuoti visą jo slaptąją reikšmę, saugiai nustatyti jį iš naujo pakeisdami arba ištrinti, kai jo nebereikia. Tą patį paskyros raktą galima naudoti serverio pusės integracijose ir API užklausų paleidikliuose Maildroppa Automations.

API raktas atstovauja jūsų Maildroppa paskyrai. Elkitės su juo kaip su slaptažodžiu: kiekvienas, gavęs raktą, gali kviesti šiam raktui prieinamus API galinius taškus, kol raktą pakeisite arba ištrinsite.

Kam skirtas API raktas

Naudokite API raktą, kai už Maildroppa ribų veikianti programinė įranga turi sąveikauti su Maildroppa be interaktyvaus naudotojo prisijungimo.

Įprasti pavyzdžiai:

• Abonentų sinchronizavimas su CRM, parduotuve, narystės sistema arba vidine duomenų baze.
• Abonentų kūrimas arba atnaujinimas naudojant serverio pusės programą.
• Žymų, laukų, laukų reikšmių ir segmentų skaitymas arba tvarkymas naudojant palaikomus galinius taškus.
• Pasirinktinių įvykių siuntimas į API užklausos paleidiklį Automation.
• Transakcinių Email Messages siuntimas per API.
• API pagrindu veikiančių saityno kablių prenumeratų tvarkymas.

API raktas skirtas serverių tarpusavio ryšiui. Jis nėra skirtas kodui, veikiančiam lankytojo naršyklėje, viešoje svetainėje, mobiliojoje programėlėje ar įterptoje registracijos formoje.

Šiuo metu puslapis pažymėtas kaip „beta“. Naudokite susietą OpenAPI dokumentaciją kaip šaltinį apie API šiuo metu palaikomus galinius taškus, užklausų turinius, parametrus ir atsakymų schemas.

API rakto puslapio atidarymas

Atidarykite „Settings“, išskleiskite „Developers“ ir pasirinkite „API key“.

Puslapį taip pat galite atidaryti tiesiogiai adresu:

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

Puslapyje yra:

• API rakto skydelis su beta ženkleliu.
• Nuoroda „View OpenAPI docs“.
• Tuščia būsena ir mygtukas „Create API key“, kai rakto nėra.
• Užmaskuotas dabartinio rakto vaizdas, kai raktas yra.
• Mygtukas „Copy“, nukopijuojantis visą raktą.
• Veiksmai „Rotate API key“ ir „Delete API key“, skirti dabartiniam raktui pakeisti arba pašalinti.

Maildroppa leidžia vieną API raktą vienai paskyrai. Puslapis nekuria atskirų raktų atskiroms programoms, aplinkoms ar komandos nariams.

API rakto kūrimas

Kai puslapyje rodoma „No API key yet“, spustelėkite „Create API key“.

Maildroppa raktą sukuria iš karto. Pirmojo kūrimo metu patvirtinimo dialogo nėra. Kol vykdoma užklausa, mygtukas pasikeičia į „Creating API key“, o puslapis laikinai išjungia tolesnius veiksmus su raktu.

Sukūrus raktą:

• Tuščia būsena išnyksta.
• Parodomas užmaskuotas raktas.
• Tampa pasiekiami veiksmai „Copy“, „Rotate API key“ ir „Delete API key“.
• Maildroppa parodo sėkmės pranešimą „API key updated“.

Jei paskyroje jau yra kitas raktas, Maildroppa antro rakto nesukuria. Naudokite esamą raktą arba pakeiskite jį.

Užmaskuoto rakto supratimas

Puslapyje visa slaptoji reikšmė nerodoma kaip įprastas tekstas. Rodomi pirmieji penki simboliai, po kurių eina penkios žvaigždutės, pavyzdžiui:

a1b2c*****

Tai tik vaizdinis maskavimas. Žvaigždutės neatspindi tikrojo rakto ilgio, o užmaskuotos reikšmės negalima naudoti API užklausai.

Spustelėkite „Copy“, kad visa dabartinio rakto reikšmė būtų įrašyta į iškarpinę. Sėkmingai nukopijavus mygtukas trumpam pasikeičia į „Copied!“.

Grįžus į puslapį raktas lieka užmaskuotas, tačiau „Copy“ ir toliau nukopijuoja visą dabartinę reikšmę. Todėl nereikia keisti galiojančio rakto vien todėl, kad jo neišsaugojote kūrimo metu.

Saugus rakto saugojimas

Nukopijuotą raktą iš karto perkelkite į integracijos naudojamą slaptųjų duomenų saugyklą.

Tinkamos vietos:

• Valdoma slaptųjų duomenų tvarkyklė.
• Apsaugota serverio aplinkos konfigūracija.
• Užšifruotas diegimo slaptasis duomuo.
• Slaptažodžių tvarkyklė, naudojama veiklos atkūrimui.

Nesaugokite rakto:

• Naršyklės pusės JavaScript kode ar kitame atsisiunčiamame frontend rinkinyje.
• Viešame arba privačiame šaltinio kodo faile, įkeltame į saugyklą.
• URL adrese ar užklausos parametre.
• Viešoje dokumentacijoje, ekrano kopijose, pagalbos pranešimuose ar problemų sekimo sistemose.
• Bendruose programos žurnaluose, analitikos įvykiuose ar klaidų ataskaitose.
• Neužšifruotoje skaičiuoklėje ar įprastame komandos pokalbyje.

Nedėkite rakto į curl pavyzdį, kuris bus kopijuojamas į dokumentaciją ar bendrą kitų žmonių naudojamą apvalkalo istoriją. Verčiau naudokite aplinkos kintamąjį, pvz., MAILDROPPA_API_KEY.

API rakto naudojimas

Siųskite visą raktą HTTP užklausos antraštėje X-API-Key:

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

Nesiųskite jo kaip Bearer prieigos rakto. Maildroppa tikisi X-API-Key, o ne Authorization: Bearer ....

Gamybinis API ir interaktyvi OpenAPI dokumentacija pasiekiami adresu:

https://api.maildroppa.com

API rakto puslapyje spustelėkite „View OpenAPI docs“, kad dokumentacija būtų atidaryta naujame naršyklės skirtuke. Ten pasirinkite galinį tašką ir peržiūrėkite jo metodą, kelią, parametrus, užklausos turinį, atsakymo tipą ir galimus būsenos kodus.

Užklausos pavyzdys

Toliau pateiktas pavyzdys gauna pirmąjį abonentų puslapį. Raktas nuskaitomas iš aplinkos kintamojo, o ne įrašomas tiesiogiai į komandą:

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

Nustatykite kintamąjį saugioje aplinkoje, kurioje veikia integracija. Tikslus metodas, kelias, užklausos parametrai ir turinys priklauso nuo galinio taško. Nukopijuokite šią informaciją iš OpenAPI dokumentacijos, o ne spėkite pagal Maildroppa programoje pasiekiamus veiksmus.

Užklausos su JSON turiniais

Užklausai, siunčiančiai JSON, taip pat pridėkite:

Content-Type: application/json

Pagrindinė struktūra:

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 ir jo turinys yra vietaženkliai. Pakeiskite juos dokumentuotu galiniu tašku ir jo dokumentuota užklausos schema.

Ką gali pasiekti raktas

Raktas veikia tik su galiniais taškais, palaikančiais autentifikavimą API raktu. Maildroppa programos viduje naudojamas puslapis ar užklausa automatiškai netampa viešo klientų API dalimi.

OpenAPI dokumentacijoje pateiktas palaikomas klientų API. Jei kelias nėra dokumentuotas naudoti su API raktu, nemanykite, kad raktas gali jį pasiekti.

API rakto puslapyje nėra aprėpčių ar atskirų galinių taškų leidimų žymimųjų langelių. Todėl dabartinį paskyros raktą reikia tvarkyti kaip didelės vertės kredencialą, net jei viena integracija naudoja tik vieną galinį tašką.

Spartinių užklausų ribos

Dabartinėje OpenAPI sutartyje dokumentuotos šios API rakto ribos:

• Numatytasis klientų API: 300 užklausų per minutę ir 2 000 užklausų per valandą.
• Įvykių API adresu /events: 100 užklausų per sekundę, pliūpsnio talpa – 500 užklausų.

Šios ribos taikomos Maildroppa paskyrai, o ne kiekvienam scenarijui, naudojančiam tą patį raktą, atskirai. Todėl kelios integracijos gali naudoti tą pačią kvotą.

Kai Maildroppa grąžina 429 Too Many Requests, nustokite siųsti naujas užklausas ir laikykitės atsakymo antraštės Retry-After, jei ji pateikta. Naudokite eilę ir kontroliuojamą laukimo didinimą, užuot pradėję daug lygiagrečių pakartojimų.

Spartinių užklausų ribojimo taisyklės gali keistis, kol API yra beta versijos. Prieš kurdami didelės apimties integracijas, patikrinkite OpenAPI dokumentacijos viršuje pateiktą informaciją.

Rakto naudojimas Automation API užklausoms

Automation gali prasidėti, kai jūsų sistema išsiunčia pasirinktinį įvykį į Maildroppa Events API.

Konfigūruojant „API request“ paleidiklį, Maildroppa naudoja tą patį paskyros API raktą, tvarkomą šiame puslapyje. Jei rakto nėra, paleidiklio nustatymas gali jį sukurti ir nukopijuoti paruoštą curl užklausą, kurioje yra visas raktas.

Tai turi dvi svarbias pasekmes:

• Pakeitus arba ištrynus paskyros raktą, tai taip pat paveikia sistemas, siunčiančias pasirinktinius įvykius į Automations.
• Nukopijuotame Automation užklausos pavyzdyje slapta reikšmė yra iškarpinėje, nors ekrane raktas užmaskuotas.

Prieš keisdami arba trindami raktą į integracijų sąrašą įtraukite kiekvieną API užklausos paleidiklį ir kiekvieną išorinį įvykių siuntėją.

API rakto nustatymas iš naujo arba pakeitimas

Naudokite „Rotate API key“, kai reikia iš naujo nustatyti arba pakeisti dabartinį kredencialą. Maildroppa sukuria naują raktą ir tuo pačiu veiksmu padaro ankstesnį raktą negaliojantį.

Keiskite raktą, kai:

• Raktas galėjo būti atskleistas.
• Asmeniui arba tiekėjui, žinojusiam raktą, prieiga nebereikalinga.
• Jūsų saugumo politika reikalauja periodiškai keisti kredencialus.
• Norite pakeisti raktą, saugomą senoje arba nesaugioje vietoje.

Po užmaskuotu raktu spustelėkite „Rotate API key“. Maildroppa atidaro įspėjimo dialogą, kuriame paaiškinama, kad esamas raktas nebebus naudojamas.

Norėdami tęsti, dialoge spustelėkite „Rotate API key“, o norėdami pasilikti dabartinį raktą – „Cancel“.

Keičiant raktą nėra pereinamojo laikotarpio

Patvirtinus pakeitimą, senasis raktas nustoja veikti iš karto. Maildroppa nelaiko senojo ir naujojo raktų galiojančių vienu metu.

Kadangi paskyra turi tik vieną raktą, pakeitimas paveikia kiekvieną jį naudojantį serverį, suplanuotą užduotį, integraciją, scenarijų ir Automation įvykių siuntėją.

Planuojamam rakto pakeitimui naudokite šią seką:

1. Išvardykite visas integracijas, naudojančias dabartinį raktą.
2. Pasiruoškite prieigą prie kiekvienos integracijos slaptųjų duomenų konfigūracijos ir diegimo proceso.
3. Jei nepertraukiama API prieiga svarbi, pasirinkite trumpą priežiūros laikotarpį.
4. Spustelėkite „Rotate API key“, tada įspėjimo dialoge patvirtinkite spustelėdami „Rotate API key“.
5. Spustelėkite „Copy“, kad nukopijuotumėte visą naują raktą.
6. Nedelsdami pakeiskite slaptą reikšmę kiekvienoje integracijoje.
7. Paleiskite iš naujo arba iš naujo įdiekite paslaugas, kurios slaptąsias reikšmes įkelia tik paleidimo metu.
8. Išsiųskite nekenksmingą dokumentuotą užklausą kiekvienai integracijai patikrinti.
9. Patikrinkite, ar nebuvo 401 Unauthorized atsakymų iš pamirštos paslaugos, vis dar naudojančios senąjį raktą.

Jei manoma, kad dabartinis raktas pažeistas, pakeiskite jį nedelsdami ir priimkite trumpą pertrauką, reikalingą teisėtoms sistemoms atnaujinti.

API rakto ištrynimas

Ištrinkite raktą, kai paskyra nebeturėtų priimti API raktu autentifikuotų užklausų.

Po užmaskuotu raktu spustelėkite „Delete API key“. Maildroppa atidaro įspėjimo dialogą, kuriame paaiškinama, kad raktas bus visam laikui pašalintas iš paskyros.

Norėdami jį ištrinti, dialoge spustelėkite „Delete API key“, o norėdami pasilikti – „Cancel“.

Ištrynus:

• Dabartinis raktas nustoja veikti iš karto.
• Puslapis grįžta į būseną „No API key yet“.
• Serverio integracijos, naudojančios ištrintą raktą, nebegali autentifikuotis.
• Automation API užklausų siuntėjai, naudojantys šį raktą, nebegali pristatyti įvykių.

Rakto ištrynimas neištrina abonentų, kampanijų, žymų, laukų, segmentų, Automations ar kitų paskyros duomenų. Pašalinamas kredencialas, naudojamas prieigai prie palaikomų API galinių taškų.

Vėliau galite spustelėti „Create API key“ ir sukurti naują kredencialą. Ištrinta reikšmė neatkuriama. Kiekvieną integraciją reikia atnaujinti, kad ji galėtų naudoti naują raktą.

Nustatyti iš naujo ar ištrinti: ką pasirinkti?

Pasirinkite „Rotate API key“, kai API prieiga turi būti tęsiama naudojant naują kredencialą.

Pasirinkite ištrynimą, kai API prieiga turi būti visiškai sustabdyta, bent jau kol kas.

Abu veiksmai iš karto padaro dabartinį raktą negaliojantį. Pakeitus raktą, naujas raktas sukuriamas tuo pačiu veiksmu; ištrynus paskyra lieka be rakto.

Saugumo rekomendacijos

API užklausas vykdykite savo serveryje

Naršyklė arba mobilioji programėlė negali patikimai apsaugoti įterpto slaptojo rakto. Naudotojas gali patikrinti programą, užklausų antraštes, šaltinio žemėlapius arba tinklo srautą ir išgauti raktą.

Jei svetainei ar programėlei reikia paleisti veiksmą, pirmiausia siųskite užklausą į savo autentifikuotą backend. Leiskite jam patikrinti naudotoją ir kreiptis į Maildroppa naudojant serveryje saugomą raktą.

Naudokite kuo mažesnį atskleidimą

Suteikite raktą tik sistemoms, kurioms jo reikia. Nedistribuokite jo kiekvienam kūrėjui ir neklijuokite į kelis vietinės konfigūracijos failus.

Kadangi šiuo metu puslapyje tvarkomas vienas visai paskyrai skirtas raktas, o ne keli pavadinti ar aprėptimis apriboti raktai, naudokite vidinę integracijos paslaugą arba tarpinį serverį, jei kelioms programoms reikia didesnės izoliacijos.

Užmaskuokite užklausų antraštes

Sukonfigūruokite HTTP klientus, atvirkštinius tarpinius serverius, stebėjimo įrankius ir klaidų registravimo sistemas, kad užmaskuotų X-API-Key. Užklausa gali veikti tinkamai, tačiau kredencialas vis tiek gali nutekėti per derinimo žurnalus.

Atskirkite aplinkas

Nenaudokite gamybinio rakto vietiniam kūrimui, pavyzdiniame kode, ekrano kopijose ar testų duomenyse. Aplinkai skirtas slaptąsias reikšmes saugokite tai aplinkai skirtose slaptųjų duomenų saugyklose.

Nuoroda „View OpenAPI docs“ gamybos naudotojus automatiškai nukreipia į gamybinio API dokumentaciją. Prieš siųsdami tikrą raktą visada patikrinkite pagrindinio kompiuterio vardą.

Pakeiskite raktą po bet kokio įtariamo atskleidimo

Pranešimo, saugyklos pakeitimo, žurnalo eilutės ar ekrano kopijos ištrynimas neįrodo, kad niekas nenukopijavo rakto. Jei visa reikšmė buvo atskleista, pakeiskite raktą.

API klaidų tvarkymas

Naudokite HTTP būseną ir dokumentuotą atsakymo turinį, kad nuspręstumėte, ką turėtų daryti integracija.

Dažni atvejai:

• 400 Bad Request — Kelias, parametras arba JSON turinys neatitinka galinio taško sutarties. Palyginkite užklausą su OpenAPI schema.
• 401 Unauthorized — Trūksta X-API-Key antraštės, ji tuščia arba negaliojanti, raktas ištrintas arba po pakeitimo naudojama sena reikšmė.
• 403 Forbidden — Autentifikuotam raktui neleidžiama atlikti šio veiksmo.
• 404 Not Found — Kelias arba nurodytas išteklius šioje paskyroje neegzistuoja.
• 429 Too Many Requests — Integracija pasiekė API spartinių užklausų ribą. Pristabdykite užklausas ir laikykitės Retry-After antraštės, jei ji pateikta.
• 5xx — Maildroppa negalėjo įvykdyti užklausos. Saugias operacijas pakartokite naudodami ribotą eksponentinį laukimo didinimą ir registravimą, į kurį neįtraukiamas API raktas.

Nekartokite visų nesėkmingų užklausų aklai. Prieš siųsdami tą pačią užklausą dar kartą, ištaisykite 400, 401, 403 ir daugumą 404 atsakymų.

Keičiančioms užklausoms prieš automatiškai jas kartodami patikrinkite galinio taško pakartojimo ir idempotentiškumo elgseną. Ryšio klaida ne visada reiškia, kad Maildroppa neatliko jokio pakeitimo.

Trikčių šalinimas

„Create API key“ vis dar rodoma

Šiuo metu paskyroje rakto nėra. Spustelėkite mygtuką vieną kartą ir palaukite, kol užklausa bus baigta.

Jei kūrimas nepavyksta, prieš bandydami dar kartą iš naujo įkelkite puslapį. Kitas puslapis arba Automation nustatymas galėjo jau sukurti paskyros raktą.

Puslapyje rodomas raktas atrodo per trumpas

Puslapyje tyčia rodomi tik pirmieji penki simboliai ir *****. Spustelėkite „Copy“, kad nukopijuotumėte visą reikšmę. Nesiųskite užmaskuoto teksto užklausoje.

„Copy“ nepasikeičia į „Copied!“

Naršyklė galėjo užblokuoti prieigą prie iškarpinės. Palikite puslapį aktyviame skirtuke, jei prašoma leiskite naudoti iškarpinę ir dar kartą spustelėkite „Copy“.

Nemėginkite atkurti rakto iš užmaskuoto teksto.

Užklausa grąžina 401 Unauthorized

Patikrinkite, ar:

• Antraštės pavadinimas yra tiksliai X-API-Key.
• Antraštėje yra visa reikšmė be matomų žvaigždučių.
• Integracija nesiunčia Authorization: Bearer vietoj to.
• Prie slaptosios reikšmės nepridėta tarpų, kabučių ar naujos eilutės.
• Niekas nepakeitė arba neištrynė paskyros rakto.
• Paslauga buvo paleista iš naujo, jei aplinkos kintamuosius ji skaito tik paleidimo metu.
• Užklausa siunčiama į tinkamą Maildroppa API aplinką.

Viena integracija veikia, o kita po pakeitimo nustojo veikti

Antroji integracija tikriausiai vis dar naudoja senąjį raktą. Pereinamojo laikotarpio nėra. Atnaujinkite jos slaptąją reikšmę ir iš naujo paleiskite procesą, kuris talpina konfigūraciją.

OpenAPI puslapis veikia, bet galinis taškas grąžina 403

Ne kiekvienas programos galinis taškas palaiko autentifikavimą API raktu. Naudokite klientų API dokumentuotą operaciją ir OpenAPI puslapyje patvirtinkite jos autentifikavimo reikalavimus.

Užklausos grąžina 429 Too Many Requests

Sumažinkite užklausų pliūpsnius, sudėkite darbus į eilę ir kartokite po API grąžinto delsos laiko. Venkite lygiagrečių pakartojimų audrų. Jei kelios programos dalijasi vienu paskyros raktu, koordinuokite jų užklausų kiekį, nes jos dalijasi paskyros API ribomis.

Rekomenduojamas nustatymo kontrolinis sąrašas

Prieš pradėdami reguliariai naudoti integraciją įsitikinkite, kad:

• Raktas saugomas tik serverio pusės slaptųjų duomenų konfigūracijoje.
• Užklausose naudojama X-API-Key antraštė.
• Gamyboje integracija naudoja https://api.maildroppa.com.
• Kiekvienas metodas, kelias, parametras ir JSON turinys atitinka OpenAPI dokumentaciją.
• Žurnaluose ir klaidų ataskaitose raktas užmaskuojamas.
• Sukonfigūruoti skirtojo laiko limitai ir riboti pakartojimai.
• Stebimos 401, 403, 429 ir serverio klaidos.
• Užregistruotas integracijos savininkas.
• Kiekviena sistema, besidalijanti paskyros raktu, įtraukta į rakto keitimo planą.
• Pažeistą raktą galima greitai pakeisti.

API rakto puslapis sąmoningai yra nedidelis, tačiau jo veiksmai paveikia kiekvieną su paskyra susietą API integraciją. Sukurkite raktą tik tada, kai jo reikia, laikykite jį patikimuose serveriuose ir planuokite keitimą kaip visai paskyrai taikomą kredencialo pakeitimą.