Krijoni dhe menaxhoni çelësin tuaj API

Published: 16 korrik 2026 · Last updated: 21 korrik 2026 · By Marcus Biel

Faqja e çelësit API i jep një sistemi të jashtëm akses të autentifikuar në endpoint-et e mbështetura të Maildroppa API në llogarinë tuaj.

Mund të krijoni një çelës API, të kopjoni vlerën e tij të plotë sekrete, ta rivendosni në mënyrë të sigurt duke e rrotulluar ose ta fshini kur nuk nevojitet më. I njëjti çelës i llogarisë mund të përdoret nga integrimet në anën e serverit dhe nga aktivizuesit e kërkesave API në Maildroppa Automations.

Një çelës API përfaqëson llogarinë tuaj Maildroppa. Trajtojeni si një fjalëkalim: kushdo që e merr çelësin mund të thërrasë endpoint-et API të disponueshme për atë çelës derisa ta rrotulloni ose ta fshini.

Për çfarë shërben çelësi API

Përdoreni çelësin API kur softueri jashtë Maildroppa duhet të punojë me Maildroppa pa një hyrje interaktive të përdoruesit.

Shembuj tipikë përfshijnë:

• Sinkronizimin e abonentëve me një CRM, dyqan, sistem anëtarësie ose bazë të dhënash të brendshme.
• Krijimin ose përditësimin e abonentëve nga një aplikacion në anën e serverit.
• Leximin ose menaxhimin e etiketave, fushave, vlerave të fushave dhe segmenteve përmes endpoint-eve të mbështetura.
• Dërgimin e ngjarjeve të personalizuara te një aktivizues kërkese API në një Automation.
• Dërgimin e mesazheve të email-it transaksional përmes API-së.
• Menaxhimin e abonimeve webhook të bazuara në API.

Çelësi API është menduar për komunikim server-me-server. Nuk është menduar për kod që ekzekutohet në shfletuesin e vizitorit, në një faqe publike interneti, në një aplikacion celular ose në një formular të integruar regjistrimi.

Faqja aktualisht shënohet si “beta”. Përdorni dokumentacionin OpenAPI të lidhur si burim për endpoint-et, trupat e kërkesave, parametrat dhe skemat e përgjigjeve që mbështeten aktualisht nga API-ja.

Hapja e faqes së çelësit API

Hapni “Settings”, zgjeroni “Developers” dhe zgjidhni “API key”.

Mund ta hapni faqen drejtpërdrejt edhe në:

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

Faqja përmban:

• Një panel të çelësit API me një etiketë beta.
• Një lidhje “View OpenAPI docs”.
• Një gjendje bosh dhe butonin “Create API key” kur nuk ekziston asnjë çelës.
• Një paraqitje të maskuar të çelësit aktual kur ekziston një i tillë.
• Një buton “Copy” që kopjon çelësin e plotë.
• Veprimet “Rotate API key” dhe “Delete API key” për zëvendësimin ose heqjen e çelësit aktual.

Maildroppa lejon një çelës API për llogari. Faqja nuk krijon çelësa të veçantë për aplikacione, mjedise ose anëtarë të ekipit.

Krijimi i një çelësi API

Kur faqja shfaq “No API key yet”, klikoni “Create API key”.

Maildroppa e krijon çelësin menjëherë. Për këtë krijim të parë nuk ka dialog konfirmimi. Gjatë ekzekutimit të kërkesës, butoni ndryshon në “Creating API key” dhe faqja çaktivizon përkohësisht veprimet e tjera të çelësit.

Pas krijimit të çelësit:

• Gjendja bosh zhduket.
• Shfaqet një çelës i maskuar.
• Veprimet “Copy”, “Rotate API key” dhe “Delete API key” bëhen të disponueshme.
• Maildroppa shfaq një mesazh suksesi “API key updated”.

Nëse tashmë ekziston një çelës tjetër për llogarinë, Maildroppa nuk krijon një të dytë. Përdorni çelësin ekzistues ose rrotullojeni.

Kuptimi i çelësit të maskuar

Faqja nuk e shfaq sekretin e plotë si tekst të zakonshëm. Ajo shfaq pesë karakteret e para të ndjekura nga pesë yje, për shembull:

a1b2c*****

Kjo është vetëm një maskë vizuale. Yjet nuk përfaqësojnë gjatësinë reale të çelësit dhe vlera e maskuar nuk mund të përdoret për një kërkesë API.

Klikoni “Copy” për ta shkruar çelësin e plotë aktual në kujtesën e fragmenteve. Pas një kopjimi të suksesshëm, butoni ndryshon për pak kohë në “Copied!”.

Çelësi mbetet i maskuar kur ktheheni në faqe, por “Copy” vazhdon të kopjojë vlerën e plotë aktuale. Prandaj nuk keni nevojë të rrotulloni një çelës të vlefshëm vetëm sepse nuk e ruajtët gjatë krijimit.

Ruajtja e sigurt e çelësit

Transferojeni çelësin e kopjuar drejtpërdrejt në hapësirën e ruajtjes së sekreteve që përdor integrimi.

Vendndodhje të përshtatshme përfshijnë:

• Një menaxhues të menaxhuar sekretesh.
• Konfigurimin e mbrojtur të mjedisit të serverit.
• Një sekret të enkriptuar të vendosjes.
• Një menaxhues fjalëkalimesh të përdorur për rikuperim operacional.

Mos e ruani çelësin në:

• JavaScript në anën e shfletuesit ose në një paketë tjetër frontend të shkarkueshme.
• Një skedar publik ose privat të kodit burimor të dërguar në një repository.
• Një URL ose parametër query.
• Dokumentacion publik, pamje ekrani, mesazhe mbështetjeje ose gjurmues problemesh.
• Log-e të përbashkëta të aplikacionit, ngjarje analitike ose raporte gabimesh.
• Një tabelë të pakriptuar ose bisedë të zakonshme të ekipit.

Mos e shtoni çelësin në një shembull curl që do të kopjohet në dokumentacion ose në historikun e shell-it të ndarë me persona të tjerë. Preferoni një variabël mjedisi si MAILDROPPA_API_KEY.

Përdorimi i çelësit API

Dërgojeni çelësin e plotë në kokën e kërkesës HTTP X-API-Key:

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

Mos e dërgoni si token Bearer. Maildroppa pret X-API-Key, jo Authorization: Bearer ....

API-ja e prodhimit dhe dokumentacioni interaktiv OpenAPI janë të disponueshme në:

https://api.maildroppa.com

Klikoni “View OpenAPI docs” në faqen e çelësit API për ta hapur dokumentacionin në një skedë të re të shfletuesit. Zgjidhni një endpoint aty për të shqyrtuar metodën, shtegun, parametrat, trupin e kërkesës, llojin e përgjigjes dhe kodet e mundshme të statusit.

Shembull kërkese

Shembulli i mëposhtëm merr faqen e parë të abonentëve. Ai e lexon çelësin nga një variabël mjedisi në vend që ta vendosë sekretin drejtpërdrejt në komandë:

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

Vendoseni variablën në mjedisin e sigurt ku ekzekutohet integrimi. Metoda, shtegu, parametrat query dhe trupi i saktë varen nga endpoint-i. Kopjojini këto detaje nga dokumentacioni OpenAPI në vend që t’i hamendësoni nga veprimet e disponueshme në aplikacionin Maildroppa.

Kërkesa me trupa JSON

Për një kërkesë që dërgon JSON, përfshini gjithashtu:

Content-Type: application/json

Për shembull, struktura bazë është:

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 dhe trupi i tij janë mbajtëse vendi. Zëvendësojini me një endpoint të dokumentuar dhe skemën e dokumentuar të kërkesës së tij.

Çfarë mund të aksesojë çelësi

Çelësi funksionon vetëm me endpoint-et që mbështesin autentifikimin me çelës API. Një faqe ose kërkesë e përdorur brenda nga aplikacioni Maildroppa nuk bëhet automatikisht pjesë e API-së publike të klientit.

Dokumentacioni OpenAPI tregon API-në e mbështetur për klientët. Nëse një shteg nuk është dokumentuar për përdorim me çelës API, mos supozoni se çelësi mund ta aksesojë.

Faqja e çelësit API nuk ofron fusha veprimi ose kuti lejesh për endpoint-e individuale. Prandaj çelësi aktual i llogarisë duhet të trajtohet si kredencial me vlerë të lartë, edhe nëse një integrim përdor vetëm një endpoint.

Kufijtë e shpejtësisë

Kontrata aktuale OpenAPI dokumenton këta kufij për çelësat API:

• API-ja e parazgjedhur e klientit: 300 kërkesa në minutë dhe 2,000 kërkesa në orë.
• Events API në /events: 100 kërkesa në sekondë me kapacitet shpërthimi prej 500 kërkesash.

Këta kufij zbatohen për llogarinë Maildroppa, jo në mënyrë të pavarur për çdo skript që ndan çelësin e saj. Prandaj disa integrime mund të konsumojnë të njëjtën kuotë.

Kur Maildroppa kthen 429 Too Many Requests, ndaloni dërgimin e kërkesave të reja dhe respektoni kokën e përgjigjes Retry-After kur është e pranishme. Përdorni një radhë dhe tërheqje graduale të kontrolluar në vend që të nisni shumë riprovime paralele.

Politikat e kufizimit të shpejtësisë mund të ndryshojnë ndërsa API-ja është në beta. Kontrolloni informacionin në krye të dokumentacionit OpenAPI para se të projektoni integrime me volum të lartë.

Përdorimi i çelësit për kërkesat API të Automation

Një Automation mund të nisë kur sistemi juaj dërgon një ngjarje të personalizuar te Events API e Maildroppa.

Kur konfiguroni një aktivizues “API request”, Maildroppa përdor të njëjtin çelës API të llogarisë të menaxhuar në këtë faqe. Konfigurimi i aktivizuesit mund ta krijojë çelësin kur nuk ekziston asnjë dhe mund të kopjojë një kërkesë të përgatitur curl që përmban çelësin e plotë.

Kjo ka dy pasoja të rëndësishme:

• Rrotullimi ose fshirja e çelësit të llogarisë ndikon gjithashtu te sistemet që dërgojnë ngjarje të personalizuara te Automations.
• Një shembull kërkese i kopjuar nga Automation përmban sekretin në kujtesën e fragmenteve, edhe pse çelësi është i maskuar në ekran.

Para se ta rrotulloni ose fshini çelësin, përfshini çdo aktivizues kërkese API dhe çdo dërgues të jashtëm ngjarjesh në inventarin e integrimeve.

Rivendosja ose zëvendësimi i çelësit API

Përdorni “Rotate API key” kur duhet të rivendosni ose zëvendësoni kredencialin aktual. Maildroppa krijon një çelës të ri dhe e zhvlefshmon çelësin e mëparshëm si pjesë të të njëjtit veprim.

Përdorni rrotullimin kur:

• Çelësi mund të jetë ekspozuar.
• Një person ose ofrues që e dinte çelësin nuk ka më nevojë për akses.
• Politika juaj e sigurisë kërkon zëvendësim periodik të kredencialeve.
• Dëshironi të zëvendësoni një çelës të ruajtur në një vend të vjetër ose të pasigurt.

Klikoni “Rotate API key” poshtë çelësit të maskuar. Maildroppa hap një dialog paralajmërimi që shpjegon se çelësi ekzistues nuk do të jetë më i përdorshëm.

Klikoni “Rotate API key” në dialog për të vazhduar ose “Cancel” për ta mbajtur çelësin aktual.

Rrotullimi nuk ka periudhë tolerance

Pasi të konfirmoni rrotullimin, çelësi i vjetër ndalon së funksionuari menjëherë. Maildroppa nuk i mban të vlefshëm njëkohësisht çelësin e vjetër dhe të ri.

Meqë llogaria ka vetëm një çelës, rrotullimi ndikon te çdo server, detyrë e planifikuar, integrim, skript dhe dërgues ngjarjesh të Automation që e përdor atë.

Përdorni këtë sekuencë për një rrotullim të planifikuar:

1. Renditni çdo integrim që përdor çelësin aktual.
2. Përgatitni aksesin në konfigurimin sekret dhe procesin e vendosjes së secilit integrim.
3. Zgjidhni një dritare të shkurtër mirëmbajtjeje nëse aksesi i pandërprerë në API është i rëndësishëm.
4. Klikoni “Rotate API key”, pastaj konfirmoni paralajmërimin me “Rotate API key” në dialog.
5. Klikoni “Copy” për të kopjuar çelësin e ri të plotë.
6. Zëvendësoni menjëherë sekretin në çdo integrim.
7. Rinisni ose vendosni përsëri shërbimet që ngarkojnë sekretet vetëm gjatë nisjes.
8. Dërgoni një kërkesë të padëmshme dhe të dokumentuar për të verifikuar çdo integrim.
9. Kontrolloni për përgjigje 401 Unauthorized nga një shërbim i harruar që ende përdor çelësin e vjetër.

Nëse çelësi aktual besohet se është komprometuar, rrotullojeni menjëherë dhe pranoni ndërprerjen e shkurtër të nevojshme për përditësimin e sistemeve legjitime.

Fshirja e çelësit API

Fshijeni çelësin kur llogaria nuk duhet të pranojë më kërkesa të autentifikuara me çelës API.

Klikoni “Delete API key” poshtë çelësit të maskuar. Maildroppa hap një dialog paralajmërimi që shpjegon se çelësi do të hiqet përgjithmonë nga llogaria.

Klikoni “Delete API key” në dialog për ta fshirë ose “Cancel” për ta mbajtur.

Pas fshirjes:

• Çelësi aktual ndalon së funksionuari menjëherë.
• Faqja kthehet në gjendjen “No API key yet”.
• Integrimet e serverit që përdorin çelësin e fshirë nuk mund të autentifikohen më.
• Dërguesit e kërkesave API të Automation që përdorin atë çelës nuk mund të dorëzojnë më ngjarje.

Fshirja e një çelësi nuk fshin abonentët, fushatat, etiketat, fushat, segmentet, Automations ose të dhëna të tjera të llogarisë. Ajo heq kredencialin e përdorur për të aksesuar endpoint-et e mbështetura API.

Mund të klikoni “Create API key” më vonë për të krijuar një kredencial të ri. Vlera e fshirë nuk rikthehet. Çdo integrim duhet të përditësohet para se të mund të përdorë çelësin e ri.

Rivendosja ose fshirja: cilën duhet të zgjidhni?

Zgjidhni “Rotate API key” kur aksesi në API duhet të vazhdojë me një kredencial të ri.

Zgjidhni fshirjen kur aksesi në API duhet të ndalojë plotësisht, të paktën për momentin.

Të dyja veprimet e zhvlefshmojnë menjëherë çelësin aktual. Rrotullimi krijon zëvendësimin si pjesë të të njëjtit veprim; fshirja e lë llogarinë pa çelës.

Rekomandime sigurie

Mbajini thirrjet API në serverin tuaj

Një shfletues ose aplikacion celular nuk mund ta mbajë në mënyrë të besueshme një sekret të integruar. Përdoruesi mund të inspektojë aplikacionin, kokat e kërkesave, hartat e burimit ose trafikun e rrjetit dhe ta nxjerrë çelësin.

Nëse një faqe interneti ose aplikacion duhet të aktivizojë një veprim, dërgojeni fillimisht kërkesën në backend-in tuaj të autentifikuar. Lëreni backend-in të verifikojë përdoruesin dhe të thërrasë Maildroppa me çelësin e ruajtur në server.

Përdorni ekspozimin minimal të mundshëm

Jepjani çelësin vetëm sistemeve që kanë nevojë për të. Mos ua shpërndani çdo zhvilluesi dhe mos e ngjisni në skedarë të shumtë konfigurimi lokal.

Meqë faqja aktualisht menaxhon një çelës në nivel llogarie dhe jo disa çelësa të emërtuar ose me fusha veprimi, përdorni një shërbim të brendshëm integrimi ose proxy nëse disa aplikacione kanë nevojë për izolim më të fortë nga njëri-tjetri.

Maskoni kokat e kërkesave

Konfiguroni klientët HTTP, proxy-t e kundërt, mjetet e vëzhgueshmërisë dhe raportuesit e gabimeve që të maskojnë X-API-Key. Një kërkesë mund të funksionojë siç duhet dhe megjithatë të rrjedhë kredenciali përmes regjistrimit të debug-ut.

Mbajini mjediset të ndara

Mos ripërdorni një çelës prodhimi në zhvillimin lokal, kod shembull, pamje ekrani ose të dhëna testimi. Ruajini sekretet specifike për mjedisin në hapësira sekretesh specifike për mjedisin.

Lidhja “View OpenAPI docs” i drejton automatikisht përdoruesit e prodhimit te dokumentacioni i API-së së prodhimit. Verifikoni gjithmonë emrin e hostit para se të dërgoni një çelës real.

Rrotullojeni pas çdo ekspozimi të dyshuar

Fshirja e një mesazhi, commit-i të repository-t, rreshti log-u ose pamjeje ekrani nuk provon se askush nuk e ka kopjuar çelësin. Nëse vlera e plotë është ekspozuar, rrotullojeni.

Trajtimi i gabimeve API

Përdorni statusin HTTP dhe trupin e dokumentuar të përgjigjes për të vendosur se çfarë duhet të bëjë integrimi.

Raste të zakonshme përfshijnë:

• 400 Bad Request — Shtegu, parametri ose trupi JSON nuk përmbush kontratën e endpoint-it. Krahasoni kërkesën me skemën OpenAPI.
• 401 Unauthorized — Koka X-API-Key mungon, është bosh, e pavlefshme, e fshirë ose përmban një vlerë të vjetër pas rrotullimit.
• 403 Forbidden — Çelësi i autentifikuar nuk lejohet ta përdorë atë veprim.
• 404 Not Found — Shtegu ose burimi i referuar nuk ekziston në këtë llogari.
• 429 Too Many Requests — Integrimi ka arritur një kufi shpejtësie të API-së. Ndaloni kërkesat dhe respektoni kokën Retry-After kur është e pranishme.
• 5xx — Maildroppa nuk mund ta përfundonte kërkesën. Përsëritni operacionet e sigurta me tërheqje eksponenciale të kufizuar dhe regjistrim që përjashton çelësin API.

Mos e riprovoni verbërisht çdo dështim. Korrigjoni përgjigjet 400, 401, 403 dhe shumicën e përgjigjeve 404 para se të dërgoni përsëri të njëjtën kërkesë.

Për kërkesat që ndryshojnë të dhëna, konfirmoni sjelljen e endpoint-it për riprovim dhe idempotencën para se të përsëritni automatikisht një kërkesë. Një dështim i lidhjes nuk provon gjithmonë se Maildroppa nuk bëri asnjë ndryshim.

Zgjidhja e problemeve

“Create API key” është ende i dukshëm

Aktualisht nuk ekziston asnjë çelës në llogari. Klikoni butonin një herë dhe prisni që kërkesa të përfundojë.

Nëse krijimi dështon, ringarkoni faqen para se të provoni përsëri. Një faqe tjetër ose konfigurim Automation mund ta ketë krijuar tashmë çelësin e llogarisë.

Çelësi në faqe duket shumë i shkurtër

Faqja shfaq qëllimisht vetëm pesë karakteret e para dhe *****. Klikoni “Copy” për të kopjuar vlerën e plotë. Mos e dërgoni tekstin e maskuar në një kërkesë.

“Copy” nuk ndryshon në “Copied!”

Shfletuesi mund të ketë bllokuar aksesin në kujtesën e fragmenteve. Mbajeni faqen në skedën aktive, lejoni aksesin në kujtesën e fragmenteve nëse kërkohet dhe klikoni përsëri “Copy”.

Mos u përpiqni ta rindërtoni çelësin nga teksti i maskuar.

Një kërkesë kthen 401 Unauthorized

Kontrolloni që:

• Emri i kokës është saktësisht X-API-Key.
• Koka përmban vlerën e plotë, pa yjet e dukshëm.
• Integrimi nuk po dërgon Authorization: Bearer në vend të tij.
• Në sekret nuk janë shtuar hapësira, thonjëza ose një rresht i ri.
• Askush nuk e ka rrotulluar ose fshirë çelësin e llogarisë.
• Një shërbim është rinisur nëse lexon variablat e mjedisit vetëm gjatë nisjes.
• Kërkesa dërgohet në mjedisin e saktë API të Maildroppa.

Një integrim funksionon, por një tjetër ndaloi pas rrotullimit

Integrimi i dytë ndoshta ende përdor çelësin e vjetër. Nuk ka periudhë mbivendosjeje. Përditësoni sekretin dhe rinisni çdo proces që ruan konfigurimin në cache.

Faqja OpenAPI funksionon, por një endpoint kthen 403

Jo çdo endpoint i aplikacionit mbështet autentifikimin me çelës API. Përdorni një operacion të dokumentuar për API-në e klientit dhe konfirmoni kërkesat e tij të autentifikimit në faqen OpenAPI.

Kërkesat kthejnë 429 Too Many Requests

Zvogëloni shpërthimet e kërkesave, vendosni punën në radhë dhe riprovoni pas vonesës së kthyer nga API-ja. Shmangni stuhitë e riprovimeve paralele. Nëse disa aplikacione ndajnë të njëjtin çelës llogarie, koordinoni volumin e kërkesave sepse ndajnë kufijtë API të llogarisë.

Lista e rekomanduar e kontrollit për konfigurimin

Para se ta vendosni një integrim në përdorim të rregullt, konfirmoni që:

• Çelësi ruhet vetëm në konfigurimin e sekreteve në anën e serverit.
• Kërkesat përdorin kokën X-API-Key.
• Integrimi përdor https://api.maildroppa.com në prodhim.
• Çdo metodë, shteg, parametër dhe trup JSON ndjek dokumentacionin OpenAPI.
• Log-et dhe raportet e gabimeve e maskojnë çelësin.
• Janë konfiguruar afate kohore dhe riprovime të kufizuara.
• Monitorohen gabimet 401, 403, 429 dhe gabimet e serverit.
• Është regjistruar pronari i integrimit.
• Çdo sistem që ndan çelësin e llogarisë përfshihet në planin e rrotullimit.
• Një çelës i komprometuar mund të rrotullohet shpejt.

Faqja e çelësit API është qëllimisht e vogël, por veprimet e saj ndikojnë te çdo integrim API i lidhur me llogarinë. Krijojeni çelësin vetëm kur nevojitet, mbajeni në serverë të besuar dhe planifikojeni rrotullimin si ndryshim të një kredenciali në nivel llogarie.