Izveidojiet un pārvaldiet savu API atslēgu

Published: 2026. gada 16. jūlijs · Last updated: 2026. gada 21. jūlijs · By Marcus Biel

API atslēgas lapa nodrošina ārējai sistēmai autentificētu piekļuvi jūsu kontā atbalstītajiem Maildroppa API galapunktiem.

Varat izveidot vienu API atslēgu, nokopēt tās pilno slepeno vērtību, droši atiestatīt to, veicot rotāciju, vai izdzēst, kad tā vairs nav nepieciešama. To pašu konta atslēgu var izmantot servera puses integrācijas un API pieprasījumu aktivizētāji programmā Maildroppa Automations.

API atslēga pārstāv jūsu Maildroppa kontu. Izturieties pret to kā pret paroli: ikviens, kurš iegūst atslēgu, var izsaukt šai atslēgai pieejamos API galapunktus, līdz jūs to nomaināt vai izdzēšat.

Kam paredzēta API atslēga

Izmantojiet API atslēgu, kad programmatūrai ārpus Maildroppa ir jādarbojas ar Maildroppa bez interaktīvas lietotāja pieteikšanās.

Tipiski piemēri:

• Abonentu sinhronizēšana ar CRM, veikalu, dalības sistēmu vai iekšējo datubāzi.
• Abonentu izveide vai atjaunināšana no servera puses lietojumprogrammas.
• Taga, lauku, lauku vērtību un segmentu lasīšana vai pārvaldība, izmantojot atbalstītos galapunktus.
• Pielāgotu notikumu nosūtīšana uz API pieprasījuma aktivizētāju programmā Automation.
• Transakciju e-pasta ziņojumu nosūtīšana, izmantojot API.
• Uz API balstītu tīmekļa āķu abonementu pārvaldība.

API atslēga ir paredzēta saziņai starp serveriem. Tā nav paredzēta kodam, kas darbojas apmeklētāja pārlūkprogrammā, publiskā tīmekļa vietnē, mobilajā lietotnē vai iegultā reģistrēšanās veidlapā.

Lapa pašlaik ir atzīmēta kā “beta”. Izmantojiet saistīto OpenAPI dokumentāciju kā avotu par API pašlaik atbalstītajiem galapunktiem, pieprasījumu pamattekstiem, parametriem un atbilžu shēmām.

API atslēgas lapas atvēršana

Atveriet “Settings”, izvērsiet “Developers” un atlasiet “API key”.

Lapu varat atvērt arī tieši:

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

Lapā ir:

• API atslēgas panelis ar beta emblēmu.
• Saite “View OpenAPI docs”.
• Tukšs stāvoklis un poga “Create API key”, ja atslēga nepastāv.
• Pašreizējās atslēgas maskēts attēlojums, ja tā pastāv.
• Poga “Copy”, kas nokopē pilno atslēgu.
• Darbības “Rotate API key” un “Delete API key” pašreizējās atslēgas aizstāšanai vai noņemšanai.

Maildroppa atļauj vienu API atslēgu katram kontam. Lapa neveido atsevišķas atslēgas individuālām lietotnēm, vidēm vai komandas dalībniekiem.

API atslēgas izveide

Kad lapā redzams “No API key yet”, noklikšķiniet uz “Create API key”.

Maildroppa atslēgu izveido nekavējoties. Pirmajai izveidei nav apstiprinājuma dialoga. Kamēr pieprasījums tiek apstrādāts, poga mainās uz “Creating API key”, un lapa uz laiku atspējo turpmākās darbības ar atslēgu.

Pēc atslēgas izveides:

• Tukšais stāvoklis pazūd.
• Tiek parādīta maskēta atslēga.
• Ir pieejamas darbības “Copy”, “Rotate API key” un “Delete API key”.
• Maildroppa parāda veiksmīgas darbības ziņojumu “API key updated”.

Ja kontam jau pastāv cita atslēga, Maildroppa otru atslēgu neizveido. Izmantojiet esošo atslēgu vai veiciet tās rotāciju.

Maskētās atslēgas izpratne

Lapa neparāda pilno slepeno vērtību kā parastu tekstu. Tiek parādītas pirmās piecas rakstzīmes, kam seko piecas zvaigznītes, piemēram:

a1b2c*****

Tas ir tikai vizuāls maskējums. Zvaigznītes neatspoguļo atslēgas faktisko garumu, un maskēto vērtību nevar izmantot API pieprasījumam.

Noklikšķiniet uz “Copy”, lai pilno pašreizējo atslēgu ierakstītu starpliktuvē. Pēc veiksmīgas kopēšanas poga uz īsu brīdi mainās uz “Copied!”.

Atgriežoties lapā, atslēga joprojām ir maskēta, taču “Copy” turpina kopēt pilno pašreizējo vērtību. Tāpēc nav jāveic derīgas atslēgas rotācija tikai tādēļ, ka to nesaglabājāt izveides laikā.

Atslēgas droša glabāšana

Nekavējoties pārvietojiet nokopēto atslēgu uz integrācijas izmantoto slepeno datu glabātuvi.

Piemērotas vietas ir:

• Pārvaldīts slepeno datu pārvaldnieks.
• Aizsargāta servera vides konfigurācija.
• Šifrēts izvietošanas noslēpums.
• Paroļu pārvaldnieks, ko izmanto darbības atjaunošanai.

Neglabājiet atslēgu:

• Pārlūkprogrammas puses JavaScript vai citā lejupielādējamā frontend komplektā.
• Publiskā vai privātā pirmkoda failā, kas iesniegts repozitorijā.
• URL vai vaicājuma parametrā.
• Publiskā dokumentācijā, ekrānuzņēmumos, atbalsta ziņojumos vai problēmu izsekotājos.
• Koplietojamos lietotnes žurnālos, analītikas notikumos vai kļūdu pārskatos.
• Nešifrētā izklājlapā vai parastā komandas tērzētavā.

Nepievienojiet atslēgu curl piemēram, kas tiks kopēts dokumentācijā vai koplietotā čaulas vēsturē. Dodiet priekšroku vides mainīgajam, piemēram, MAILDROPPA_API_KEY.

API atslēgas izmantošana

Nosūtiet pilno atslēgu HTTP pieprasījuma galvenē X-API-Key:

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

Nesūtiet to kā Bearer pilnvaru. Maildroppa sagaida X-API-Key, nevis Authorization: Bearer ....

Produkcijas API un tā interaktīvā OpenAPI dokumentācija ir pieejama:

https://api.maildroppa.com

API atslēgas lapā noklikšķiniet uz “View OpenAPI docs”, lai dokumentāciju atvērtu jaunā pārlūkprogrammas cilnē. Tur atlasiet galapunktu, lai pārskatītu tā metodi, ceļu, parametrus, pieprasījuma pamattekstu, atbildes tipu un iespējamos statusa kodus.

Pieprasījuma piemērs

Šajā piemērā tiek izgūta pirmā abonentu lapa. Atslēga tiek nolasīta no vides mainīgā, nevis slepeni ievietota tieši komandā:

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

Iestatiet mainīgo drošajā vidē, kurā darbojas integrācija. Precīzā metode, ceļš, vaicājuma parametri un pamatteksts ir atkarīgi no galapunkta. Kopējiet šo informāciju no OpenAPI dokumentācijas, nevis mēģiniet to uzminēt pēc Maildroppa lietotnē pieejamajām darbībām.

Pieprasījumi ar JSON pamattekstu

Pieprasījumam, kas nosūta JSON, pievienojiet arī:

Content-Type: application/json

Pamata struktūra, piemēram:

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 un tā pamatteksts ir vietturi. Aizstājiet tos ar dokumentētu galapunktu un tā dokumentēto pieprasījuma shēmu.

Kam atslēga var piekļūt

Atslēga darbojas tikai ar galapunktiem, kas atbalsta autentifikāciju ar API atslēgu. Lapa vai pieprasījums, ko iekšēji izmanto Maildroppa lietotne, automātiski nav daļa no publiskā klientu API.

OpenAPI dokumentācijā ir redzams atbalstītais klientu API. Ja ceļš nav dokumentēts izmantošanai ar API atslēgu, neuzskatiet, ka atslēga tam var piekļūt.

API atslēgas lapa nepiedāvā tvērumus vai katram galapunktam atsevišķas atļauju izvēles rūtiņas. Tāpēc pašreizējā konta atslēga jāapstrādā kā augstas vērtības akreditācijas dati, pat ja viena integrācija izmanto tikai vienu galapunktu.

Ātruma ierobežojumi

Pašreizējais OpenAPI līgums dokumentē šādus API atslēgu ierobežojumus:

• Noklusējuma klientu API: 300 pieprasījumu minūtē un 2 000 pieprasījumu stundā.
• Events API galapunktā /events: 100 pieprasījumu sekundē ar 500 pieprasījumu sērijveida ietilpību.

Šie ierobežojumi tiek piemēroti Maildroppa kontam, nevis neatkarīgi katram skriptam, kas koplieto tā atslēgu. Tāpēc vairākas integrācijas var izmantot vienu un to pašu limitu.

Kad Maildroppa atgriež 429 Too Many Requests, pārtrauciet jaunu pieprasījumu sūtīšanu un ievērojiet atbildes galveni Retry-After, ja tā ir iekļauta. Izmantojiet rindu un kontrolētu atkāpšanos, nevis sākat daudzus paralēlus atkārtotus mēģinājumus.

Ātruma ierobežojumu politika var mainīties, kamēr API ir beta stadijā. Pirms liela apjoma integrāciju izstrādes pārbaudiet informāciju OpenAPI dokumentācijas augšdaļā.

Atslēgas izmantošana Automation API pieprasījumiem

Automation var sākties, kad jūsu sistēma nosūta pielāgotu notikumu uz Maildroppa Events API.

Konfigurējot “API request” aktivizētāju, Maildroppa izmanto to pašu konta API atslēgu, kas tiek pārvaldīta šajā lapā. Aktivizētāja iestatīšana var izveidot atslēgu, ja tā nepastāv, un nokopēt sagatavotu curl pieprasījumu, kurā ir pilnā atslēga.

Tam ir divas svarīgas sekas:

• Konta atslēgas rotācija vai dzēšana ietekmē arī sistēmas, kas sūta pielāgotus notikumus uz Automations.
• Nokopēts Automation pieprasījuma piemērs satur slepeno vērtību starpliktuvē, lai gan atslēga ekrānā ir maskēta.

Pirms atslēgas rotācijas vai dzēšanas iekļaujiet savas integrācijas uzskaitē katru API pieprasījuma aktivizētāju un katru ārējo notikumu sūtītāju.

API atslēgas atiestatīšana vai aizstāšana

Izmantojiet “Rotate API key”, kad nepieciešams atiestatīt vai aizstāt pašreizējos akreditācijas datus. Maildroppa izveido jaunu atslēgu un tās pašas darbības laikā padara iepriekšējo atslēgu nederīgu.

Veiciet rotāciju, ja:

• Atslēga varētu būt atklāta.
• Personai vai pakalpojumu sniedzējam, kas zināja atslēgu, piekļuve vairs nav nepieciešama.
• Jūsu drošības politika pieprasa periodisku akreditācijas datu nomaiņu.
• Vēlaties aizstāt atslēgu, kas glabājas vecā vai nedrošā vietā.

Zem maskētās atslēgas noklikšķiniet uz “Rotate API key”. Maildroppa atver brīdinājuma dialogu, kurā paskaidrots, ka esošā atslēga vairs nebūs izmantojama.

Lai turpinātu, dialogā noklikšķiniet uz “Rotate API key”, vai noklikšķiniet uz “Cancel”, lai saglabātu pašreizējo atslēgu.

Rotācijai nav pārejas perioda

Pēc rotācijas apstiprināšanas vecā atslēga nekavējoties pārstāj darboties. Maildroppa neuztur veco un jauno atslēgu derīgumu vienlaikus.

Tā kā kontam ir tikai viena atslēga, rotācija ietekmē katru serveri, ieplānoto uzdevumu, integrāciju, skriptu un Automation notikumu sūtītāju, kas to izmanto.

Plānotai rotācijai izmantojiet šādu secību:

1. Uzskaitiet katru integrāciju, kas izmanto pašreizējo atslēgu.
2. Sagatavojiet piekļuvi katras integrācijas slepeno datu konfigurācijai un izvietošanas procesam.
3. Ja nepārtraukta API piekļuve ir svarīga, izvēlieties īsu apkopes logu.
4. Noklikšķiniet uz “Rotate API key” un pēc tam brīdinājuma dialogā apstipriniet ar “Rotate API key”.
5. Noklikšķiniet uz “Copy”, lai nokopētu pilno jauno atslēgu.
6. Nekavējoties aizstājiet slepeno vērtību katrā integrācijā.
7. Restartējiet vai atkārtoti izvietojiet pakalpojumus, kas slepenās vērtības ielādē tikai startēšanas laikā.
8. Nosūtiet nekaitīgu, dokumentētu pieprasījumu, lai pārbaudītu katru integrāciju.
9. Pārbaudiet, vai kāds aizmirsts pakalpojums, kas joprojām izmanto veco atslēgu, nesaņem 401 Unauthorized atbildes.

Ja pastāv aizdomas, ka pašreizējā atslēga ir apdraudēta, nekavējoties veiciet tās rotāciju un pieņemiet īso pārtraukumu, kas nepieciešams likumīgo sistēmu atjaunināšanai.

API atslēgas dzēšana

Dzēsiet atslēgu, kad kontam vairs nevajadzētu pieņemt ar API atslēgu autentificētus pieprasījumus.

Zem maskētās atslēgas noklikšķiniet uz “Delete API key”. Maildroppa atver brīdinājuma dialogu, kurā paskaidrots, ka atslēga tiks neatgriezeniski noņemta no konta.

Lai to dzēstu, dialogā noklikšķiniet uz “Delete API key”, vai noklikšķiniet uz “Cancel”, lai to saglabātu.

Pēc dzēšanas:

• Pašreizējā atslēga nekavējoties pārstāj darboties.
• Lapa atgriežas stāvoklī “No API key yet”.
• Servera integrācijas, kas izmanto dzēsto atslēgu, vairs nevar autentificēties.
• Automation API pieprasījumu sūtītāji, kas izmanto šo atslēgu, vairs nevar piegādāt notikumus.

Atslēgas dzēšana neizdzēš abonentus, kampaņas, tagus, laukus, segmentus, Automations vai citus konta datus. Tā noņem akreditācijas datus, kas izmantoti piekļuvei atbalstītajiem API galapunktiem.

Vēlāk varat noklikšķināt uz “Create API key”, lai izveidotu jaunus akreditācijas datus. Dzēstā vērtība netiek atjaunota. Katra integrācija ir jāatjaunina, pirms tā var izmantot jauno atslēgu.

Atiestatīt vai dzēst: ko izvēlēties?

Izvēlieties “Rotate API key”, kad API piekļuvei jāturpinās ar jauniem akreditācijas datiem.

Izvēlieties dzēšanu, kad API piekļuvei pilnībā jāapstājas, vismaz pagaidām.

Abas darbības nekavējoties padara pašreizējo atslēgu nederīgu. Rotācija tās pašas darbības ietvaros izveido aizstājēju; dzēšana atstāj kontu bez atslēgas.

Drošības ieteikumi

API izsaukumus veiciet savā serverī

Pārlūkprogramma vai mobilā lietotne nespēj droši glabāt iegultu noslēpumu. Lietotājs var pārbaudīt lietotni, pieprasījumu galvenes, avota kartes vai tīkla datplūsmu un iegūt atslēgu.

Ja tīmekļa vietnei vai lietotnei jāaktivizē darbība, vispirms nosūtiet pieprasījumu uz savu autentificēto backend. Ļaujiet šim backend validēt lietotāju un izsaukt Maildroppa, izmantojot serverī glabāto atslēgu.

Izmantojiet iespējami mazāku eksponēšanu

Piešķiriet atslēgu tikai sistēmām, kurām tā nepieciešama. Neizplatiet to katram izstrādātājam un neielīmējiet vairākos lokālos konfigurācijas failos.

Tā kā lapa pašlaik pārvalda vienu visam kontam paredzētu atslēgu, nevis vairākas nosauktas vai ierobežota tvēruma atslēgas, izmantojiet iekšēju integrācijas pakalpojumu vai starpniekserveri, ja vairākām lietotnēm nepieciešama stingrāka savstarpējā izolācija.

Rediģējiet pieprasījumu galvenes

Konfigurējiet HTTP klientus, reversos starpniekserverus, novērojamības rīkus un kļūdu ziņotājus, lai tie rediģētu X-API-Key. Pieprasījums var darboties pareizi, vienlaikus nopludinot akreditācijas datus atkļūdošanas žurnālos.

Nodrošiniet atsevišķas vides

Neizmantojiet produkcijas atslēgu lokālajā izstrādē, paraugkodā, ekrānuzņēmumos vai testu datos. Vides specifiskos noslēpumus glabājiet vides specifiskās slepeno datu krātuvēs.

Saite “View OpenAPI docs” automātiski novirza produkcijas lietotājus uz produkcijas API dokumentāciju. Pirms īstas atslēgas nosūtīšanas vienmēr pārbaudiet resursdatora nosaukumu.

Veiciet rotāciju pēc jebkādas iespējamas atklāšanas

Ziņojuma, repozitorija iesnieguma, žurnāla rindas vai ekrānuzņēmuma dzēšana nepierāda, ka neviens nav nokopējis atslēgu. Ja pilnā vērtība tika atklāta, veiciet rotāciju.

API kļūdu apstrāde

Izmantojiet HTTP statusu un dokumentēto atbildes pamattekstu, lai izlemtu, kā integrācijai jārīkojas.

Biežākie gadījumi:

• 400 Bad Request — Ceļš, parametrs vai JSON pamatteksts neatbilst galapunkta līgumam. Salīdziniet pieprasījumu ar OpenAPI shēmu.
• 401 Unauthorized — Galvene X-API-Key trūkst, ir tukša vai nederīga, atslēga ir dzēsta, vai pēc rotācijas tiek izmantota veca vērtība.
• 403 Forbidden — Autentificētajai atslēgai nav atļauts izmantot šo darbību.
• 404 Not Found — Ceļš vai norādītais resurss šajā kontā nepastāv.
• 429 Too Many Requests — Integrācija ir sasniegusi API ātruma ierobežojumu. Apturiet pieprasījumus un ievērojiet galveni Retry-After, ja tā ir iekļauta.
• 5xx — Maildroppa nevarēja pabeigt pieprasījumu. Drošas darbības atkārtojiet ar ierobežotu eksponenciālu atkāpšanos un žurnalēšanu, kas neietver API atslēgu.

Neatkārtojiet katru kļūmi akli. Pirms tā paša pieprasījuma atkārtotas nosūtīšanas novērsiet 400, 401, 403 un lielāko daļu 404 atbilžu cēloņu.

Mainošiem pieprasījumiem pirms automātiskas atkārtošanas pārbaudiet galapunkta atkārtošanas un idempotences darbību. Savienojuma kļūme ne vienmēr nozīmē, ka Maildroppa neveica nekādas izmaiņas.

Problēmu novēršana

Joprojām redzams “Create API key”

Kontā pašlaik nepastāv neviena atslēga. Vienreiz noklikšķiniet uz pogas un gaidiet, līdz pieprasījums tiek pabeigts.

Ja izveide neizdodas, pirms atkārtota mēģinājuma atkārtoti ielādējiet lapu. Iespējams, cita lapa vai Automation iestatīšana jau ir izveidojusi konta atslēgu.

Atslēga lapā izskatās pārāk īsa

Lapa apzināti parāda tikai pirmās piecas rakstzīmes un *****. Noklikšķiniet uz “Copy”, lai nokopētu pilno vērtību. Nesūtiet pieprasījumā maskēto tekstu.

“Copy” nemainās uz “Copied!”

Pārlūkprogramma, iespējams, ir bloķējusi piekļuvi starpliktuvei. Atstājiet lapu aktīvajā cilnē, ja tiek prasīts, atļaujiet piekļuvi starpliktuvei un vēlreiz noklikšķiniet uz “Copy”.

Nemēģiniet rekonstruēt atslēgu no maskētā teksta.

Pieprasījums atgriež 401 Unauthorized

Pārbaudiet, vai:

• Galvenes nosaukums ir tieši X-API-Key.
• Galvene satur pilno vērtību bez redzamajām zvaigznītēm.
• Integrācija nesūta Authorization: Bearer.
• Slepenajai vērtībai nav pievienotas atstarpes, pēdiņas vai jauna rinda.
• Neviens nav veicis konta atslēgas rotāciju vai to izdzēsis.
• Pakalpojums tika restartēts, ja tas vides mainīgos nolasa tikai startēšanas laikā.
• Pieprasījums tiek nosūtīts uz pareizo Maildroppa API vidi.

Viena integrācija darbojas, bet otra pēc rotācijas pārstāja darboties

Otrā integrācija, visticamāk, joprojām izmanto veco atslēgu. Pārklāšanās perioda nav. Atjauniniet tās slepeno vērtību un restartējiet procesu, kas kešo konfigurāciju.

OpenAPI lapa darbojas, bet galapunkts atgriež 403

Ne katrs lietotnes galapunkts atbalsta autentifikāciju ar API atslēgu. Izmantojiet klientu API dokumentētu darbību un OpenAPI lapā apstipriniet tās autentifikācijas prasības.

Pieprasījumi atgriež 429 Too Many Requests

Samaziniet pieprasījumu sērijas, ievietojiet darbu rindā un atkārtojiet pēc API atgrieztās aizkaves. Izvairieties no paralēlu atkārtojumu vētrām. Ja vairākas lietotnes koplieto vienu konta atslēgu, saskaņojiet pieprasījumu apjomu, jo tās koplieto konta API ierobežojumus.

Ieteicamās iestatīšanas kontrolsaraksts

Pirms integrācijas regulāras izmantošanas pārliecinieties, ka:

• Atslēga tiek glabāta tikai servera puses slepeno datu konfigurācijā.
• Pieprasījumi izmanto galveni X-API-Key.
• Produkcijā integrācija izmanto https://api.maildroppa.com.
• Katra metode, ceļš, parametrs un JSON pamatteksts atbilst OpenAPI dokumentācijai.
• Žurnāli un kļūdu pārskati rediģē atslēgu.
• Ir konfigurēti noildzes termiņi un ierobežoti atkārtoti mēģinājumi.
• Tiek uzraudzītas 401, 403, 429 un servera kļūdas.
• Ir reģistrēts integrācijas īpašnieks.
• Katrs konta atslēgu koplietojošais serveris ir iekļauts rotācijas plānā.
• Apdraudētu atslēgu var ātri nomainīt.

API atslēgas lapa ir apzināti neliela, taču tās darbības ietekmē visas kontam pievienotās API integrācijas. Izveidojiet atslēgu tikai tad, kad tā nepieciešama, glabājiet to uzticamos serveros un plānojiet rotāciju kā konta līmeņa akreditācijas datu maiņu.