Creați și gestionați cheia API

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

Pagina Cheie API oferă unui sistem extern acces autentificat la endpointurile API Maildroppa acceptate din contul dvs.

Puteți crea o cheie API, îi puteți copia valoarea secretă completă, o puteți reseta în siguranță prin rotire sau o puteți șterge când nu mai este necesară. Aceeași cheie de cont poate fi utilizată de integrările server-side și de declanșatoarele de solicitări API din Automatizările Maildroppa.

O cheie API reprezintă contul dvs. Maildroppa. Tratați-o ca pe o parolă: orice persoană care obține cheia poate apela endpointurile API disponibile pentru acea cheie până când o rotiți sau o ștergeți.

Pentru ce este utilizată cheia API

Utilizați cheia API atunci când un software din afara Maildroppa trebuie să interacționeze cu Maildroppa fără autentificarea interactivă a unui utilizator.

Exemple obișnuite:

• Sincronizarea abonaților cu un CRM, un magazin, un sistem de membri sau o bază de date internă.
• Crearea sau actualizarea abonaților dintr-o aplicație server-side.
• Citirea sau gestionarea etichetelor, câmpurilor, valorilor câmpurilor și segmentelor prin endpointurile acceptate.
• Trimiterea de evenimente personalizate către un declanșator de solicitări API dintr-o Automatizare.
• Trimiterea mesajelor de e-mail tranzacționale prin API.
• Gestionarea abonamentelor webhook bazate pe API.

Cheia API este destinată comunicării server-la-server. Nu este destinată codului care rulează în browserul unui vizitator, pe un site public, într-o aplicație mobilă sau într-un formular de înscriere încorporat.

Pagina este în prezent marcată „beta”. Utilizați documentația OpenAPI asociată ca sursă pentru endpointurile, corpurile solicitărilor, parametrii și schemele de răspuns acceptate în prezent de API.

Deschiderea paginii Cheie API

Deschideți „Settings”, extindeți „Developers” și selectați „API key”.

Puteți deschide pagina și direct la:

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

Pagina conține:

• Un panou pentru cheia API cu o insignă beta.
• Un link „View OpenAPI docs”.
• O stare goală și butonul „Create API key” atunci când nu există nicio cheie.
• O reprezentare mascată a cheii curente atunci când există una.
• Un buton „Copy” care copiază cheia completă.
• Acțiunile „Rotate API key” și „Delete API key” pentru înlocuirea sau eliminarea cheii curente.

Maildroppa permite o singură cheie API per cont. Pagina nu creează chei separate pentru aplicații, medii sau membri ai echipei individuale.

Crearea unei chei API

Când pagina afișează „No API key yet”, faceți clic pe „Create API key”.

Maildroppa creează cheia imediat. Pentru această primă creare nu există un dialog de confirmare. În timp ce solicitarea se execută, butonul devine „Creating API key”, iar pagina dezactivează temporar acțiunile ulterioare asupra cheii.

După crearea cheii:

• Starea goală dispare.
• Apare o cheie mascată.
• Acțiunile „Copy”, „Rotate API key” și „Delete API key” devin disponibile.
• Maildroppa afișează un mesaj de succes „API key updated”.

Dacă există deja o altă cheie pentru cont, Maildroppa nu creează una a doua. Utilizați cheia existentă sau rotiți-o.

Înțelegerea cheii mascate

Pagina nu afișează secretul complet ca text obișnuit. Sunt afișate primele cinci caractere urmate de cinci asteriscuri, de exemplu:

a1b2c*****

Aceasta este doar o mască vizuală. Asteriscurile nu reprezintă lungimea reală a cheii, iar valoarea mascată nu poate fi utilizată pentru o solicitare API.

Faceți clic pe „Copy” pentru a copia cheia curentă completă în clipboard. După copierea cu succes, butonul devine pentru scurt timp „Copied!”.

Cheia rămâne mascată când reveniți la pagină, însă „Copy” continuă să copieze valoarea curentă completă. Prin urmare, nu trebuie să rotiți o cheie validă doar pentru că nu ați salvat-o în timpul creării.

Stocarea în siguranță a cheii

Transferați cheia copiată direct în spațiul de stocare pentru secrete utilizat de integrare.

Locații potrivite includ:

• Un manager de secrete administrat.
• Configurația protejată a mediului serverului.
• Un secret de implementare criptat.
• Un manager de parole utilizat pentru recuperarea operațională.

Nu stocați cheia în:

• JavaScript rulat în browser sau în alt pachet frontend descărcabil.
• Un fișier public sau privat de cod sursă introdus într-un repository.
• Un URL sau un parametru de interogare.
• Documentație publică, capturi de ecran, mesaje de asistență sau sisteme de urmărire a problemelor.
• Jurnale partajate ale aplicației, evenimente de analiză sau rapoarte de erori.
• O foaie de calcul necriptată sau un chat obișnuit al echipei.

Nu adăugați cheia într-un exemplu curl care va fi copiat în documentație sau în istoricul shell partajat cu alte persoane. Preferați o variabilă de mediu precum MAILDROPPA_API_KEY.

Utilizarea cheii API

Trimiteți cheia completă în antetul solicitării HTTP X-API-Key:

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

Nu o trimiteți ca token Bearer. Maildroppa așteaptă X-API-Key, nu Authorization: Bearer ....

API-ul de producție și documentația OpenAPI interactivă sunt disponibile la:

https://api.maildroppa.com

Faceți clic pe „View OpenAPI docs” pe pagina Cheie API pentru a deschide documentația într-o filă nouă a browserului. Selectați un endpoint pentru a-i examina metoda, calea, parametrii, corpul solicitării, tipul răspunsului și posibilele coduri de stare.

Exemplu de solicitare

Următorul exemplu preia prima pagină de abonați. Cheia este citită dintr-o variabilă de mediu în loc să fie introdusă direct în comandă:

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

Setați variabila în mediul securizat în care rulează integrarea. Metoda, calea, parametrii de interogare și corpul exacte depind de endpoint. Copiați aceste detalii din documentația OpenAPI, în loc să le deduceți din acțiunile disponibile în aplicația Maildroppa.

Solicitări cu corpuri JSON

Pentru o solicitare care trimite JSON, includeți și:

Content-Type: application/json

De exemplu, structura de bază este:

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 și corpul acestuia sunt substituenți. Înlocuiți-le cu un endpoint documentat și schema de solicitare documentată a acestuia.

La ce poate avea acces cheia

Cheia funcționează numai cu endpointurile care acceptă autentificarea prin cheie API. O pagină sau o solicitare utilizată intern de aplicația Maildroppa nu face automat parte din API-ul public pentru clienți.

Documentația OpenAPI prezintă API-ul pentru clienți acceptat. Dacă o cale nu este documentată pentru utilizarea cheii API, nu presupuneți că cheia o poate accesa.

Pagina Cheie API nu oferă domenii de acces sau casete de selectare pentru permisiuni per endpoint. Prin urmare, cheia curentă a contului trebuie gestionată ca o acreditare de mare valoare, chiar dacă o integrare utilizează un singur endpoint.

Limite de rată

Contractul OpenAPI actual documentează următoarele limite pentru cheia API:

• API-ul implicit pentru clienți: 300 de solicitări pe minut și 2.000 de solicitări pe oră.
• API-ul Events la /events: 100 de solicitări pe secundă, cu o capacitate de rafală de 500 de solicitări.

Aceste limite se aplică contului Maildroppa, nu fiecărui script care îi partajează cheia în mod independent. Prin urmare, mai multe integrări pot consuma aceeași limită.

Când Maildroppa returnează 429 Too Many Requests, opriți trimiterea de solicitări noi și respectați antetul de răspuns Retry-After atunci când este prezent. Utilizați o coadă și o revenire controlată, în loc să porniți multe reîncercări paralele.

Politicile privind limitele de rată se pot modifica cât timp API-ul este în versiune beta. Verificați informațiile din partea de sus a documentației OpenAPI înainte de a proiecta integrări cu volum mare.

Utilizarea cheii pentru solicitările API din Automatizări

O Automatizare poate începe atunci când sistemul dvs. trimite un eveniment personalizat către API-ul Events al Maildroppa.

Când configurați un declanșator „API request”, Maildroppa utilizează aceeași cheie API a contului gestionată pe această pagină. Configurarea declanșatorului poate crea cheia dacă nu există și poate copia o solicitare curl pregătită care conține cheia completă.

Acest lucru are două consecințe importante:

• Rotirea sau ștergerea cheii contului afectează și sistemele care trimit evenimente personalizate către Automatizări.
• Un exemplu de solicitare Automation copiat conține secretul în clipboard, chiar dacă cheia este mascată pe ecran.

Înainte de a roti sau șterge cheia, includeți în inventarul integrărilor fiecare declanșator de solicitări API și fiecare expeditor extern de evenimente.

Resetarea sau înlocuirea cheii API

Utilizați „Rotate API key” atunci când trebuie să resetați sau să înlocuiți acreditarea curentă. Maildroppa creează o cheie nouă și invalidează cheia anterioară ca parte a aceleiași acțiuni.

Utilizați rotirea atunci când:

• Este posibil ca cheia să fi fost expusă.
• O persoană sau un furnizor care cunoștea cheia nu mai are nevoie de acces.
• Politica dvs. de securitate impune înlocuirea periodică a acreditărilor.
• Doriți să înlocuiți o cheie stocată într-o locație veche sau nesigură.

Faceți clic pe „Rotate API key” sub cheia mascată. Maildroppa deschide un dialog de avertizare care explică faptul că cheia existentă nu va mai putea fi utilizată.

Faceți clic pe „Rotate API key” în dialog pentru a continua sau pe „Cancel” pentru a păstra cheia curentă.

Rotirea nu are perioadă de grație

După confirmarea rotirii, cheia veche încetează să funcționeze imediat. Maildroppa nu păstrează simultan valide cheia veche și cea nouă.

Deoarece contul are o singură cheie, rotirea afectează fiecare server, activitate programată, integrare, script și expeditor de evenimente Automation care o utilizează.

Utilizați următoarea succesiune pentru o rotire planificată:

1. Enumerați fiecare integrare care utilizează cheia curentă.
2. Pregătiți accesul la configurația secretelor și procesul de implementare pentru fiecare integrare.
3. Alegeți o scurtă fereastră de mentenanță dacă este important ca accesul API să fie neîntrerupt.
4. Faceți clic pe „Rotate API key”, apoi confirmați avertismentul cu „Rotate API key” în dialog.
5. Faceți clic pe „Copy” pentru a copia cheia nouă completă.
6. Înlocuiți imediat secretul în fiecare integrare.
7. Reporniți sau reimplementați serviciile care încarcă secretele doar la pornire.
8. Trimiteți o solicitare documentată, inofensivă, pentru a verifica fiecare integrare.
9. Verificați răspunsurile 401 Unauthorized de la un serviciu uitat care utilizează încă cheia veche.

Dacă se consideră că cheia curentă a fost compromisă, rotiți-o imediat și acceptați scurta întrerupere necesară pentru actualizarea sistemelor legitime.

Ștergerea cheii API

Ștergeți cheia atunci când contul nu ar mai trebui să accepte solicitări autentificate prin cheie API.

Faceți clic pe „Delete API key” sub cheia mascată. Maildroppa deschide un dialog de avertizare care explică faptul că cheia va fi eliminată definitiv din cont.

Faceți clic pe „Delete API key” în dialog pentru a o șterge sau pe „Cancel” pentru a o păstra.

După ștergere:

• Cheia curentă încetează să funcționeze imediat.
• Pagina revine la starea „No API key yet”.
• Integrările server care utilizează cheia ștearsă nu se mai pot autentifica.
• Expeditorii de solicitări API din Automatizări care utilizează cheia nu mai pot livra evenimente.

Ștergerea unei chei nu șterge abonați, campanii, etichete, câmpuri, segmente, Automatizări sau alte date ale contului. Elimină acreditarea utilizată pentru accesarea endpointurilor API acceptate.

Puteți face clic ulterior pe „Create API key” pentru a crea o acreditare nouă. Valoarea ștearsă nu este restaurată. Fiecare integrare trebuie actualizată înainte de a putea utiliza cheia nouă.

Resetare sau ștergere: ce ar trebui să alegeți?

Alegeți „Rotate API key” atunci când accesul API trebuie să continue cu o acreditare nouă.

Alegeți ștergerea atunci când accesul API trebuie oprit complet, cel puțin pentru moment.

Ambele acțiuni invalidează imediat cheia curentă. Rotirea creează înlocuitorul ca parte a aceleiași acțiuni; ștergerea lasă contul fără cheie.

Recomandări de securitate

Păstrați apelurile API pe serverul dvs.

Un browser sau o aplicație mobilă nu poate păstra în mod fiabil un secret încorporat. Un utilizator poate inspecta aplicația, antetele solicitărilor, hărțile sursă sau traficul de rețea și poate extrage cheia.

Dacă un site sau o aplicație trebuie să declanșeze o acțiune, trimiteți mai întâi solicitarea către propriul backend autentificat. Lăsați backendul să valideze utilizatorul și să apeleze Maildroppa cu cheia stocată pe server.

Utilizați expunerea minimă posibilă

Oferiți cheia doar sistemelor care au nevoie de ea. Nu o distribuiți fiecărui dezvoltator și nu o introduceți în mai multe fișiere locale de configurare.

Deoarece pagina gestionează în prezent o singură cheie la nivelul contului, nu mai multe chei denumite sau cu domeniu de acces, utilizați un serviciu intern de integrare sau un proxy dacă mai multe aplicații au nevoie de o izolare mai puternică între ele.

Redactați antetele solicitărilor

Configurați clienții HTTP, proxy-urile inverse, instrumentele de observabilitate și sistemele de raportare a erorilor pentru a redacta X-API-Key. O solicitare poate funcționa corect, dar poate divulga totuși acreditarea prin jurnalele de depanare.

Păstrați mediile separate

Nu reutilizați o cheie de producție în dezvoltarea locală, în cod de exemplu, în capturi de ecran sau în fixture-uri de testare. Stocați secretele specifice mediului în spații de stocare pentru secrete specifice mediului.

Linkul „View OpenAPI docs” direcționează automat utilizatorii de producție către documentația API de producție. Verificați întotdeauna numele gazdei înainte de a trimite o cheie reală.

Rotiți cheia după orice expunere suspectată

Ștergerea unui mesaj, a unui commit dintr-un repository, a unei linii de jurnal sau a unei capturi de ecran nu dovedește că nimeni nu a copiat cheia. Dacă valoarea completă a fost expusă, rotiți cheia.

Gestionarea erorilor API

Utilizați starea HTTP și corpul de răspuns documentat pentru a decide ce trebuie să facă integrarea.

Cazurile frecvente includ:

• 400 Bad Request — Calea, parametrul sau corpul JSON nu respectă contractul endpointului. Comparați solicitarea cu schema OpenAPI.
• 401 Unauthorized — Antetul X-API-Key lipsește, este gol, invalid, șters sau conține o valoare veche după rotire.
• 403 Forbidden — Cheia autentificată nu are permisiunea de a utiliza operațiunea respectivă.
• 404 Not Found — Calea sau resursa indicată nu există în acest cont.
• 429 Too Many Requests — Integrarea a atins o limită de rată API. Opriți temporar solicitările și respectați antetul Retry-After atunci când este prezent.
• 5xx — Maildroppa nu a putut finaliza solicitarea. Reîncercați operațiunile sigure cu revenire exponențială limitată și cu jurnale care exclud cheia API.

Nu reîncercați orbește orice eroare. Corectați răspunsurile 400, 401, 403 și majoritatea răspunsurilor 404 înainte de a trimite din nou aceeași solicitare.

Pentru solicitările care modifică date, confirmați comportamentul endpointului privind reîncercarea și idempotența înainte de a repeta automat o solicitare. O eroare de conexiune nu dovedește întotdeauna că Maildroppa nu a efectuat nicio modificare.

Depanare

„Create API key” este încă vizibil

În prezent nu există nicio cheie în cont. Faceți clic o dată pe buton și așteptați finalizarea solicitării.

Dacă crearea eșuează, reîncărcați pagina înainte de a încerca din nou. Este posibil ca o altă pagină sau configurare Automation să fi creat deja cheia contului.

Cheia de pe pagină pare prea scurtă

Pagina afișează intenționat doar primele cinci caractere și *****. Faceți clic pe „Copy” pentru a copia valoarea completă. Nu trimiteți textul mascat într-o solicitare.

„Copy” nu se schimbă în „Copied!”

Este posibil ca browserul să fi blocat accesul la clipboard. Păstrați pagina în fila activă, permiteți accesul la clipboard dacă vi se solicită și faceți clic din nou pe „Copy”.

Nu încercați să reconstruiți cheia din textul mascat.

O solicitare returnează 401 Unauthorized

Verificați că:

• Numele antetului este exact X-API-Key.
• Antetul conține valoarea completă, fără asteriscurile vizibile.
• Integrarea nu trimite în schimb Authorization: Bearer.
• În secret nu au fost adăugate spații albe, ghilimele sau o linie nouă.
• Nimeni nu a rotit sau șters cheia contului.
• Un serviciu a fost repornit dacă citește variabilele de mediu doar la pornire.
• Solicitarea este trimisă către mediul API Maildroppa corect.

O integrare funcționează, dar alta s-a oprit după rotire

Probabil că a doua integrare utilizează încă cheia veche. Nu există o perioadă de suprapunere. Actualizați secretul și reporniți orice proces care memorează configurația în cache.

Pagina OpenAPI funcționează, dar un endpoint returnează 403

Nu orice endpoint al aplicației acceptă autentificarea prin cheie API. Utilizați o operațiune documentată pentru API-ul destinat clienților și confirmați cerințele de autentificare pe pagina OpenAPI.

Solicitările returnează 429 Too Many Requests

Reduceți rafalele de solicitări, puneți activitățile în coadă și reîncercați după întârzierea returnată de API. Evitați rafalele de reîncercări paralele. Dacă mai multe aplicații partajează aceeași cheie de cont, coordonați volumul solicitărilor deoarece împart limitele API ale contului.

Listă de verificare pentru configurarea recomandată

Înainte de a utiliza în mod regulat o integrare, confirmați că:

• Cheia este stocată numai în configurația de secrete server-side.
• Solicitările utilizează antetul X-API-Key.
• Integrarea utilizează https://api.maildroppa.com în producție.
• Fiecare metodă, cale, parametru și corp JSON respectă documentația OpenAPI.
• Jurnalele și rapoartele de erori redactează cheia.
• Sunt configurate timeouturi și reîncercări limitate.
• Sunt monitorizate erorile 401, 403, 429 și erorile de server.
• Este înregistrat responsabilul integrării.
• Fiecare sistem care partajează cheia contului este inclus în planul de rotire.
• O cheie compromisă poate fi rotită rapid.

Pagina Cheie API este intenționat simplă, dar acțiunile sale afectează fiecare integrare API conectată la cont. Creați cheia doar atunci când este necesară, păstrați-o pe servere de încredere și planificați rotirea ca pe o schimbare a acreditării la nivelul întregului cont.