Creează și gestionează cheia API

Publicat: 16 iulie 2026 · Ultima actualizare: 12 septembrie 2026 · De Marcus Biel

Pagina „API key” permite unui sistem extern să acceseze, prin autentificare, endpointurile API Maildroppa acceptate pentru contul tău.

Poți crea o singură cheie API, îi poți copia valoarea secretă completă, o poți reseta în siguranță prin rotire sau o poți șterge când nu mai este necesară. Aceeași cheie a contului poate fi folosită atât de integrările care rulează pe server, cât și de declanșatoarele „API request” din automatizările Maildroppa.

O cheie API reprezintă contul tău Maildroppa. Trateaz-o ca pe o parolă: oricine obține cheia poate apela endpointurile API disponibile pentru aceasta până când o rotești sau o ștergi.

La ce folosește cheia API

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

Exemple frecvente:

• Sincronizarea abonaților cu un CRM, un magazin, un sistem de gestionare a membrilor sau o bază de date internă.
• Crearea sau actualizarea abonaților dintr-o aplicație care rulează pe server.
• Citirea sau gestionarea etichetelor, câmpurilor, valorilor câmpurilor și segmentelor prin endpointurile acceptate.
• Trimiterea de evenimente personalizate către un declanșator „API request” dintr-o automatizare.
• Trimiterea de e-mailuri tranzacționale prin API.
• Gestionarea abonamentelor la webhookuri prin API.

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

Pagina este marcată în prezent „beta”. Consultă documentația OpenAPI accesibilă prin linkul de pe pagină pentru a verifica endpointurile, corpurile solicitărilor, parametrii și schemele de răspuns acceptate în prezent de API.

Cum deschizi pagina „API key”

Deschide „Settings”, extinde secțiunea „Developers” și selectează „API key”.

Poți deschide pagina și direct la:

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

Pagina conține:

• Un panou pentru cheia API, marcat cu o insignă beta.
• Un link „View OpenAPI docs”.
• O stare fără cheie ș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 pentru fiecare cont. Pagina nu creează chei separate pentru fiecare aplicație, mediu sau membru al echipei.

Cum creezi o cheie API

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

Maildroppa creează cheia imediat. La prima creare nu apare o fereastră de confirmare. Cât timp solicitarea este în curs, textul butonului devine „Creating API key”, iar celelalte acțiuni asupra cheii sunt dezactivate temporar.

După crearea cheii:

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

Dacă există deja o cheie pentru cont, Maildroppa nu creează o a doua cheie. Folosește cheia existentă sau rotește-o.

Cum este afișată cheia mascată

Pagina nu afișează valoarea secretă completă în clar. Sunt afișate primele cinci caractere, urmate de cinci asteriscuri, de exemplu:

a1b2c*****

Aceasta este doar o mască vizuală. Asteriscurile nu indică lungimea reală a cheii, iar valoarea mascată nu poate fi folosită într-o solicitare API.

Dă clic pe „Copy” pentru a copia cheia curentă completă în clipboard. După copierea cu succes, textul butonului devine pentru scurt timp „Copied!”.

Cheia rămâne mascată când revii pe pagină, dar „Copy” copiază în continuare valoarea curentă completă. Așadar, nu trebuie să rotești o cheie validă doar pentru că nu ai salvat-o la creare.

Cum stochezi cheia în siguranță

Transferă cheia copiată direct în spațiul de stocare a secretelor folosit de integrare.

Locuri potrivite pentru stocare:

• Un serviciu administrat de gestionare a secretelor.
• Configurația protejată a mediului serverului.
• Un secret criptat folosit la implementare.
• Un manager de parole folosit pentru recuperare operațională.

Nu stoca cheia în:

• Cod JavaScript care rulează în browser sau alte pachete frontend care pot fi descărcate.
• Fișiere de cod sursă publice sau private salvate prin commit într-un repository.
• URL-uri sau parametri de interogare.
• Documentație publică, capturi de ecran, mesaje către asistență sau sisteme de urmărire a problemelor.
• Jurnale partajate ale aplicației, evenimente de analiză sau rapoarte de erori.
• Foi de calcul necriptate sau conversații obișnuite în chatul echipei.

Nu adăuga cheia într-un exemplu curl care va fi copiat în documentație sau într-un istoric shell partajat cu alte persoane. Folosește de preferință o variabilă de mediu, precum MAILDROPPA_API_KEY.

Cum folosești cheia API

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

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

Nu o trimite 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

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

Exemplu de solicitare

Exemplul următor preia prima pagină de abonați. Cheia este citită dintr-o variabilă de mediu, în loc ca valoarea secretă 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}"

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

Solicitări cu corp JSON

Pentru o solicitare care trimite JSON, include ș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 solicitării sunt valori de exemplu. Înlocuiește-le cu un endpoint documentat și cu schema documentată a solicitării pentru acel endpoint.

Ce poate accesa cheia

Cheia funcționează doar cu endpointuri care acceptă autentificarea prin cheie API. O pagină sau o solicitare folosită intern de aplicația Maildroppa nu face automat parte din API-ul public destinat clienților.

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

Pagina „API key” nu oferă domenii de acces (scopes) sau casete de bifat pentru permisiuni la nivel de endpoint. Prin urmare, cheia curentă a contului trebuie tratată ca o credențială de acces deosebit de sensibilă, chiar dacă o integrare folosește un singur endpoint.

Limite de solicitări

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 de evenimente la /events: 100 de solicitări pe secundă, cu o capacitate de 500 de solicitări în rafală.

Aceste limite se aplică la nivelul contului Maildroppa, nu separat fiecărui script care folosește cheia. Prin urmare, mai multe integrări pot consuma aceeași cotă de solicitări.

Când Maildroppa returnează 429 Too Many Requests, oprește trimiterea de solicitări noi și respectă antetul de răspuns Retry-After, dacă este prezent. Folosește o coadă de așteptare și temporizarea controlată a reîncercărilor, în loc să lansezi multe reîncercări în paralel.

Politicile privind limitele de solicitări se pot modifica atât timp cât API-ul este în versiune beta. Verifică informațiile de la începutul documentației OpenAPI înainte de a proiecta integrări cu volum mare.

Folosirea cheii pentru solicitările API din automatizări

O automatizare poate porni când sistemul tău trimite un eveniment personalizat către API-ul de evenimente Maildroppa.

Când configurezi un declanșator „API request”, Maildroppa folosește aceeași cheie API a contului, gestionată pe această pagină. La configurarea declanșatorului se poate crea cheia, dacă nu există, și se 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 pentru o automatizare, odată copiat, conține valoarea secretă în clipboard, chiar dacă cheia este mascată pe ecran.

Înainte să rotești sau să ștergi cheia, include în inventarul integrărilor fiecare declanșator „API request” și fiecare sistem extern care trimite evenimente.

Cum resetezi sau înlocuiești cheia API

Folosește „Rotate API key” când trebuie să resetezi sau să înlocuiești credențiala curentă. Maildroppa creează o cheie nouă și invalidează cheia anterioară în cadrul aceleiași acțiuni.

Rotește cheia când:

• Este posibil să fi fost expusă.
• O persoană sau un furnizor care cunoștea cheia nu mai are nevoie de acces.
• Politica de securitate impune înlocuirea periodică a credențialelor.
• Vrei să înlocuiești o cheie stocată într-un loc vechi sau nesigur.

Dă clic pe „Rotate API key” sub cheia mascată. Maildroppa deschide o fereastră de avertizare care explică faptul că cheia existentă nu va mai putea fi folosită.

Dă clic pe „Rotate API key” în fereastră pentru a continua sau pe „Cancel” pentru a păstra cheia curentă.

Rotirea nu include o perioadă de grație

După ce confirmi rotirea, cheia veche nu mai funcționează, cu efect imediat. Maildroppa nu menține simultan valabile cheia veche și cheia nouă.

Deoarece contul are o singură cheie, rotirea afectează fiecare server, sarcină programată, integrare, script și sistem care trimite evenimente către automatizări folosind acea cheie.

Pentru o rotire planificată, urmează acești pași:

1. Fă o listă cu toate integrările care folosesc cheia curentă.
2. Pregătește accesul la configurația secretelor și la procesul de implementare al fiecărei integrări.
3. Alege un interval scurt de mentenanță dacă accesul neîntrerupt la API este important.
4. Dă clic pe „Rotate API key”, apoi confirmă avertizarea apăsând „Rotate API key” în fereastră.
5. Dă clic pe „Copy” pentru a copia cheia nouă completă.
6. Înlocuiește imediat valoarea secretă în fiecare integrare.
7. Repornește sau reimplementează serviciile care încarcă secretele doar la pornire.
8. Trimite o solicitare documentată, fără efecte dăunătoare, pentru a verifica fiecare integrare.
9. Verifică dacă apar răspunsuri 401 Unauthorized de la vreun serviciu omis, care folosește încă cheia veche.

Dacă suspectezi că cheia curentă a fost compromisă, rotește-o imediat și acceptă scurta întrerupere necesară pentru actualizarea sistemelor legitime.

Cum ștergi cheia API

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

Dă clic pe „Delete API key” sub cheia mascată. Maildroppa deschide o fereastră de avertizare care explică faptul că cheia va fi eliminată definitiv din cont.

Dă clic pe „Delete API key” în fereastră pentru a o șterge sau pe „Cancel” pentru a o păstra.

După ștergere:

• Cheia curentă nu mai funcționează, cu efect imediat.
• Pagina revine la starea „No API key yet”.
• Integrările de pe server care folosesc cheia ștearsă nu se mai pot autentifica.
• Sistemele care trimit solicitări API către automatizări folosind acea cheie nu mai pot livra evenimente.

Ștergerea unei chei nu șterge abonați, campanii, etichete, câmpuri, segmente, automatizări sau alte date din cont. Elimină doar credențiala folosită pentru accesarea endpointurilor API acceptate.

Poți da clic ulterior pe „Create API key” pentru a crea o credențială nouă. Valoarea ștearsă nu este restaurată. Fiecare integrare trebuie actualizată înainte de a putea folosi cheia nouă.

Resetare sau ștergere: ce alegi?

Alege „Rotate API key” când accesul la API trebuie să continue cu o credențială nouă.

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

Ambele acțiuni invalidează imediat cheia curentă. Rotirea creează cheia înlocuitoare în cadrul aceleiași acțiuni; ștergerea lasă contul fără cheie.

Recomandări de securitate

Efectuează apelurile API de pe server

Un browser sau o aplicație mobilă nu poate păstra în mod fiabil o valoare secretă încorporată. Un utilizator poate inspecta aplicația, antetele solicitărilor, fișierele source map sau traficul de rețea și poate extrage cheia.

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

Limitează expunerea la minimum

Oferă cheia doar sistemelor care au nevoie de ea. Nu o distribui tuturor dezvoltatorilor și nu o introduce î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 domenii de acces distincte, folosește un serviciu intern de integrare sau un proxy dacă mai multe aplicații au nevoie de o izolare mai strictă între ele.

Maschează datele sensibile din antetele solicitărilor

Configurează clienții HTTP, proxy-urile inverse, instrumentele de observabilitate și sistemele de raportare a erorilor astfel încât să mascheze X-API-Key. O solicitare poate funcționa corect și totuși poate divulga credențiala prin jurnalele de depanare.

Păstrează mediile separate

Nu reutiliza o cheie de producție în dezvoltarea locală, în codul de exemplu, în capturi de ecran sau în seturi de date și configurații pentru teste. Stochează secretele fiecărui mediu în spații de stocare dedicate acelui mediu.

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

Rotește cheia ori de câte ori suspectezi că a fost expusă

Ș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ă, rotește cheia.

Gestionarea erorilor API

Folosește codul de stare HTTP și corpul de răspuns documentat pentru a decide ce trebuie să facă integrarea.

Cazuri frecvente:

• 400 Bad Request — Calea, parametrul sau corpul JSON nu respectă contractul endpointului. Compară solicitarea cu schema OpenAPI.
• 401 Unauthorized — Antetul X-API-Key lipsește, este gol, conține o cheie invalidă sau ștearsă ori o valoare veche după rotire.
• 403 Forbidden — Cheia autentificată nu are permisiunea de a folosi 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 solicitări API. Oprește temporar solicitările și respectă antetul Retry-After, dacă este prezent.
• 5xx — Maildroppa nu a putut finaliza solicitarea. Reîncearcă operațiunile sigure cu intervale de așteptare care cresc exponențial, până la o limită stabilită, și cu jurnalizare care exclude cheia API.

Nu reîncerca automat orice solicitare eșuată, fără să verifici cauza. Remediază cauzele răspunsurilor 400, 401, 403 și ale majorității răspunsurilor 404 înainte de a trimite din nou aceeași solicitare.

Pentru solicitările care modifică date, verifică modul în care endpointul gestionează reîncercările ș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. Dă clic o singură dată pe buton și așteaptă finalizarea solicitării.

Dacă nu se poate crea cheia, reîncarcă pagina înainte de a încerca din nou. Este posibil ca cheia contului să fi fost deja creată dintr-o altă pagină sau în timpul configurării unei automatizări.

Cheia de pe pagină pare prea scurtă

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

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

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

Nu încerca să reconstruiești cheia din textul mascat.

O solicitare returnează 401 Unauthorized

Verifică dacă:

• Numele antetului este exact X-API-Key.
• Antetul conține valoarea completă, fără asteriscurile afișate.
• Integrarea nu trimite în schimb Authorization: Bearer.
• În valoarea secretă nu au fost adăugate spații albe, ghilimele sau un caracter de linie nouă.
• Nimeni nu a rotit sau șters cheia contului.
• Serviciul 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

A doua integrare folosește probabil încă cheia veche. Nu există o perioadă în care ambele chei să fie valabile. Actualizează valoarea secretă și repornește orice proces care păstrează configurația în cache.

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

Nu toate endpointurile aplicației acceptă autentificarea prin cheie API. Folosește o operațiune documentată pentru API-ul destinat clienților și verifică cerințele de autentificare pe pagina OpenAPI.

Solicitările returnează 429 Too Many Requests

Redu rafalele de solicitări, pune sarcinile în coadă și reîncearcă după intervalul de așteptare returnat de API. Evită valurile de reîncercări în paralel. Dacă mai multe aplicații folosesc aceeași cheie a contului, coordonează volumul solicitărilor, deoarece toate împart limitele API ale contului.

Listă de verificare pentru configurarea recomandată

Înainte de a folosi o integrare în mod regulat, verifică dacă:

• Cheia este stocată exclusiv în configurația de secrete de pe server.
• Solicitările folosesc antetul X-API-Key.
• Integrarea folosește https://api.maildroppa.com în producție.
• Fiecare metodă, cale, parametru și corp JSON respectă documentația OpenAPI.
• Cheia este mascată în jurnale și rapoarte de erori.
• Sunt configurate limite de timp pentru solicitări și reîncercări limitate.
• Sunt monitorizate erorile 401, 403, 429 și erorile de server.
• Persoana responsabilă de integrare este consemnată.
• Fiecare sistem care folosește cheia contului este inclus în planul de rotire.
• O cheie compromisă poate fi rotită rapid.

Pagina „API key” este intenționat simplă, dar acțiunile sale afectează fiecare integrare API conectată la cont. Creează cheia doar când ai nevoie de ea, păstreaz-o pe servere de încredere și planifică rotirea ca pe o schimbare a credențialei de acces la nivelul întregului cont.