Luo ja hallitse API-avaintasi

Published: 16. heinäkuuta 2026 · Last updated: 21. heinäkuuta 2026 · By Marcus Biel

API-avainsivu antaa ulkoiselle järjestelmälle todennetun pääsyn tilisi tuettuihin Maildroppa API -päätepisteisiin.

Voit luoda yhden API-avaimen, kopioida sen täydellisen salaisen arvon, nollata sen turvallisesti vaihtamalla sen uuteen tai poistaa sen, kun sitä ei enää tarvita. Sama tilin API-avain toimii palvelinpuolen integraatioissa ja Maildroppa Automations -automaatioiden API-pyyntöjen käynnistimissä.

API-avain edustaa Maildroppa-tiliäsi. Käsittele sitä kuten salasanaa: kuka tahansa avaimen haltuunsa saanut voi kutsua avaimen käytettävissä olevia API-päätepisteitä, kunnes vaihdat tai poistat avaimen.

Mihin API-avainta käytetään

Käytä API-avainta, kun Maildroppan ulkopuolisen ohjelmiston on työskenneltävä Maildroppan kanssa ilman vuorovaikutteista käyttäjän kirjautumista.

Tyypillisiä esimerkkejä:

• Tilaajien synkronointi CRM-järjestelmän, verkkokaupan, jäsenyyshallintajärjestelmän tai sisäisen tietokannan kanssa.
• Tilaajien luominen tai päivittäminen palvelinpuolen sovelluksesta.
• Tunnisteiden, kenttien, kenttäarvojen ja segmenttien lukeminen tai hallinta tuettujen päätepisteiden kautta.
• Mukautettujen tapahtumien lähettäminen Automationin API-pyynnön käynnistimeen.
• Transaktionaalisten Email Messages -viestien lähettäminen API:n kautta.
• API-pohjaisten webhook-tilausten hallinta.

API-avain on tarkoitettu palvelinten väliseen viestintään. Sitä ei ole tarkoitettu vierailijan selaimessa, julkisella verkkosivustolla, mobiilisovelluksessa tai upotetussa rekisteröitymislomakkeessa suoritettavalle koodille.

Sivulla näkyy tällä hetkellä merkintä “beta”. Käytä linkitettyä OpenAPI-dokumentaatiota lähteenä API:n tällä hetkellä tukemille päätepisteille, pyynnön rungoille, parametreille ja vastausskeemoille.

API-avainsivun avaaminen

Avaa “Settings”, laajenna “Developers” ja valitse “API key”.

Voit avata sivun myös suoraan osoitteessa:

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

Sivulla on:

• API-avainpaneeli, jossa on beta-merkki.
• “View OpenAPI docs” -linkki.
• Tyhjä tila ja “Create API key” -painike, kun avainta ei ole.
• Nykyisen avaimen peitetty esitys, kun avain on olemassa.
• “Copy”-painike, joka kopioi täydellisen avaimen.
• “Rotate API key”- ja “Delete API key” -toiminnot nykyisen avaimen vaihtamiseen tai poistamiseen.

Maildroppa sallii yhden API-avaimen tiliä kohden. Sivu ei luo erillisiä avaimia yksittäisille sovelluksille, ympäristöille tai tiimin jäsenille.

API-avaimen luominen

Kun sivulla näkyy “No API key yet”, napsauta “Create API key”.

Maildroppa luo avaimen välittömästi. Ensimmäisen luomisen yhteydessä ei näytetä vahvistusikkunaa. Pyynnön aikana painikkeen tekstiksi vaihtuu “Creating API key”, ja sivu poistaa muut avaintoiminnot väliaikaisesti käytöstä.

Kun avain on luotu:

• Tyhjä tila katoaa.
• Näkyviin tulee peitetty avain.
• “Copy”-, “Rotate API key”- ja “Delete API key” -toiminnot tulevat käyttöön.
• Maildroppa näyttää onnistumisviestin “API key updated”.

Jos tilille on jo olemassa toinen avain, Maildroppa ei luo toista avainta. Käytä olemassa olevaa avainta tai vaihda se uuteen.

Peitetyn avaimen ymmärtäminen

Sivu ei tulosta täydellistä salaista arvoa tavallisena tekstinä. Se näyttää viisi ensimmäistä merkkiä ja niiden jälkeen viisi tähteä, esimerkiksi:

a1b2c*****

Tämä on vain visuaalinen peite. Tähdet eivät kuvaa avaimen todellista pituutta, eikä peitettyä arvoa voi käyttää API-pyynnössä.

Napsauta “Copy”, jos haluat kopioida nykyisen täydellisen avaimen leikepöydälle. Onnistuneen kopioinnin jälkeen painikkeen tekstiksi vaihtuu hetkeksi “Copied!”.

Avain pysyy peitettynä, kun palaat sivulle, mutta “Copy” kopioi edelleen nykyisen täydellisen arvon. Sinun ei siis tarvitse vaihtaa toimivaa avainta uuteen vain siksi, ettet tallentanut sitä luomisen yhteydessä.

Avaimen turvallinen tallentaminen

Siirrä kopioitu avain suoraan integraation käyttämään salaisuuksien tallennuspaikkaan.

Sopivia sijainteja ovat esimerkiksi:

• Hallinnoitu salaisuuksien hallintapalvelu.
• Suojattu palvelimen ympäristökonfiguraatio.
• Salattu käyttöönoton salaisuus.
• Operatiiviseen palautukseen käytetty salasananhallintaohjelma.

Älä tallenna avainta seuraaviin:

• Selainpuolen JavaScriptiin tai muuhun ladattavaan frontend-pakettiin.
• Julkiseen tai yksityiseen lähdekooditiedostoon, joka on commitoitu repositorioon.
• Verkko-osoitteeseen tai kyselyparametriin.
• Julkiseen dokumentaatioon, kuvakaappauksiin, tukiviesteihin tai issue-seurantaan.
• Jaettuihin sovelluslokeihin, analytiikkatapahtumiin tai virheraportteihin.
• Salaamattomaan taulukkolaskentatiedostoon tai tavalliseen tiimichattiin.

Älä lisää avainta curl-esimerkkiin, joka kopioidaan dokumentaatioon tai muiden kanssa jaettuun komentohistoriaan. Käytä mieluummin ympäristömuuttujaa, kuten MAILDROPPA_API_KEY.

API-avaimen käyttäminen

Lähetä täydellinen avain X-API-Key-HTTP-pyyntöotsakkeessa:

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

Älä lähetä sitä Bearer-tunnisteena. Maildroppa odottaa otsaketta X-API-Key, ei muotoa Authorization: Bearer ....

Tuotanto-API ja sen vuorovaikutteinen OpenAPI-dokumentaatio ovat saatavilla osoitteessa:

https://api.maildroppa.com

Avaa dokumentaatio uuteen selaimen välilehteen napsauttamalla API-avainsivulla “View OpenAPI docs”. Valitse sieltä päätepiste tarkastellaksesi sen metodia, polkua, parametreja, pyynnön runkoa, vastaustyyppiä ja mahdollisia tilakoodeja.

Esimerkkipyyntö

Seuraava esimerkki hakee tilaajien ensimmäisen sivun. Se lukee avaimen ympäristömuuttujasta sen sijaan, että salaisuus sijoitettaisiin suoraan komentoon:

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

Aseta muuttuja suojatussa ympäristössä, jossa integraatio suoritetaan. Täsmällinen metodi, polku, kyselyparametrit ja runko riippuvat päätepisteestä. Kopioi nämä tiedot OpenAPI-dokumentaatiosta sen sijaan, että päättelisit ne Maildroppa-sovelluksessa käytettävissä olevista toiminnoista.

JSON-rungon sisältävät pyynnöt

JSON-dataa lähettävään pyyntöön on lisättävä myös:

Content-Type: application/json

Perusrakenne on esimerkiksi:

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 ja sen runko ovat paikanhaltijoita. Korvaa ne dokumentoidulla päätepisteellä ja sen dokumentoidulla pyyntöskeemalla.

Mitä avaimella voi käyttää

Avain toimii vain päätepisteissä, jotka tukevat API-avain-todennusta. Maildroppa-sovelluksen sisäisesti käyttämä sivu tai pyyntö ei automaattisesti kuulu julkiseen asiakas-API:in.

OpenAPI-dokumentaatio näyttää tuetun asiakas-API:n. Jos polkua ei ole dokumentoitu API-avaimen käyttöä varten, älä oleta, että avaimella voi käyttää sitä.

API-avainsivulla ei ole käyttöoikeusalueita tai päätepistekohtaisia käyttöoikeusvalintoja. Nykyistä tilin API-avainta on siksi käsiteltävä korkean arvon tunnistetietona, vaikka yksi integraatio käyttäisi vain yhtä päätepistettä.

Pyyntörajoitukset

Nykyinen OpenAPI-sopimus dokumentoi seuraavat API-avaimen rajoitukset:

• Oletusarvoinen asiakas-API: 300 pyyntöä minuutissa ja 2 000 pyyntöä tunnissa.
• Events API osoitteessa /events: 100 pyyntöä sekunnissa ja purskekapasiteetti 500 pyyntöä.

Rajoitukset kohdistetaan Maildroppa-tiliin, ei erikseen jokaiseen samaa avainta käyttävään skriptiin. Useat integraatiot voivat siis käyttää samaa kiintiötä.

Kun Maildroppa palauttaa 429 Too Many Requests, lopeta uusien pyyntöjen lähettäminen ja noudata Retry-After-vastausotsaketta, jos se on mukana. Käytä jonoa ja hallittua backoffia sen sijaan, että aloittaisit useita rinnakkaisia uudelleenyrityksiä.

Pyyntörajoitukset voivat muuttua API:n ollessa betavaiheessa. Tarkista OpenAPI-dokumentaation yläosassa olevat tiedot ennen suuren volyymin integraatioiden suunnittelua.

Avaimen käyttäminen Automationin API-pyynnöissä

Automation voi käynnistyä, kun järjestelmäsi lähettää mukautetun tapahtuman Maildroppan Events API:in.

Kun määrität “API request” -käynnistimen, Maildroppa käyttää samaa tällä sivulla hallittavaa tilin API-avainta. Käynnistimen asetukset voivat luoda avaimen, jos sitä ei ole, ja kopioida valmistellun curl-pyynnön, joka sisältää täydellisen avaimen.

Tällä on kaksi tärkeää seurausta:

• Tilin avaimen vaihtaminen tai poistaminen vaikuttaa myös järjestelmiin, jotka lähettävät mukautettuja tapahtumia Automationeihin.
• Kopioitu Automation-pyyntöesimerkki sisältää salaisuuden leikepöydällä, vaikka avain on näytöllä peitetty.

Ennen avaimen vaihtamista tai poistamista lisää kaikki API-pyynnön käynnistimet ja ulkoiset tapahtumalähettäjät integraatioiden luetteloosi.

API-avaimen nollaaminen tai vaihtaminen

Käytä “Rotate API key” -toimintoa, kun sinun on nollattava tai vaihdettava nykyinen tunnistetieto. Maildroppa luo uuden avaimen ja mitätöi aiemman avaimen saman toiminnon yhteydessä.

Vaihda avain uuteen, kun:

• Avain on saattanut paljastua.
• Henkilö tai palveluntarjoaja, joka tiesi avaimen, ei enää tarvitse käyttöoikeutta.
• Tietoturvakäytäntösi edellyttää tunnistetietojen säännöllistä vaihtamista.
• Haluat korvata vanhaan tai suojaamattomaan sijaintiin tallennetun avaimen.

Napsauta “Rotate API key” peitetyn avaimen alapuolella. Maildroppa avaa varoitusikkunan, jossa kerrotaan, ettei nykyistä avainta voi enää käyttää.

Jatka napsauttamalla valintaikkunassa “Rotate API key” tai pidä nykyinen avain napsauttamalla “Cancel”.

Vaihtamisessa ei ole siirtymäaikaa

Kun vahvistat vaihdon, vanha avain lakkaa toimimasta välittömästi. Maildroppa ei pidä vanhaa ja uutta avainta samanaikaisesti voimassa.

Koska tilillä on vain yksi avain, vaihtaminen vaikuttaa kaikkiin sitä käyttäviin palvelimiin, ajastettuihin töihin, integraatioihin, skripteihin ja Automation-tapahtumien lähettäjiin.

Käytä suunnitellussa vaihdossa seuraavaa järjestystä:

1. Luettele kaikki nykyistä avainta käyttävät integraatiot.
2. Varmista pääsy kunkin integraation salaiseen konfiguraatioon ja käyttöönottoprosessiin.
3. Valitse lyhyt huoltoikkuna, jos keskeytymätön API-yhteys on tärkeää.
4. Napsauta “Rotate API key” ja vahvista sitten varoitus valitsemalla valintaikkunassa “Rotate API key”.
5. Kopioi uusi täydellinen avain napsauttamalla “Copy”.
6. Korvaa salaisuus välittömästi kaikissa integraatioissa.
7. Käynnistä uudelleen tai ota uudelleen käyttöön palvelut, jotka lataavat salaisuudet vain käynnistyksen yhteydessä.
8. Lähetä vaaraton, dokumentoitu pyyntö kunkin integraation toiminnan varmistamiseksi.
9. Tarkista, onko unohtunut palvelu, joka käyttää edelleen vanhaa avainta, palauttanut vastauksia 401 Unauthorized.

Jos nykyisen avaimen uskotaan vaarantuneen, vaihda se välittömästi ja hyväksy laillisten järjestelmien päivittämiseen tarvittava lyhyt keskeytys.

API-avaimen poistaminen

Poista avain, kun tilin ei enää pidä hyväksyä API-avaimella todennettuja pyyntöjä.

Napsauta “Delete API key” peitetyn avaimen alapuolella. Maildroppa avaa varoitusikkunan, jossa kerrotaan, että avain poistetaan tililtä pysyvästi.

Poista avain napsauttamalla valintaikkunassa “Delete API key” tai pidä se napsauttamalla “Cancel”.

Poistamisen jälkeen:

• Nykyinen avain lakkaa toimimasta välittömästi.
• Sivu palaa tilaan “No API key yet”.
• Poistettua avainta käyttävät palvelinintegraatiot eivät voi enää todentautua.
• Tätä avainta käyttävät Automationin API-pyyntöjen lähettäjät eivät voi enää toimittaa tapahtumia.

Avaimen poistaminen ei poista tilaajia, kampanjoita, tunnisteita, kenttiä, segmenttejä, Automations-automaatioita tai muita tilin tietoja. Se poistaa tunnistetiedon, jota käytetään tuettujen API-päätepisteiden käyttöön.

Voit myöhemmin luoda uuden tunnistetiedon napsauttamalla “Create API key”. Poistettua arvoa ei palauteta. Jokainen integraatio on päivitettävä ennen kuin se voi käyttää uutta avainta.

Nollaaminen vai poistaminen: kumman valitset?

Valitse “Rotate API key”, kun API-yhteyden tulee jatkua uudella tunnistetiedolla.

Valitse poistaminen, kun API-yhteyden tulee katketa kokonaan, ainakin toistaiseksi.

Molemmat toiminnot mitätöivät nykyisen avaimen välittömästi. Vaihtaminen luo korvaavan avaimen saman toiminnon yhteydessä; poistaminen jättää tilin ilman avainta.

Tietoturvasuositukset

Pidä API-kutsut palvelimellasi

Selain tai mobiilisovellus ei pysty pitämään upotettua salaisuutta luotettavasti suojattuna. Käyttäjä voi tutkia sovellusta, pyyntöotsakkeita, lähdekarttoja tai verkkoliikennettä ja poimia avaimen.

Jos verkkosivuston tai sovelluksen on käynnistettävä toiminto, lähetä pyyntö ensin omaan todennettuun backend-järjestelmääsi. Anna backendin validoida käyttäjä ja kutsua Maildroppaa palvelimelle tallennetulla avaimella.

Minimoi altistuminen

Anna avain vain järjestelmille, jotka tarvitsevat sitä. Älä jaa sitä jokaiselle kehittäjälle tai liitä sitä useisiin paikallisiin konfiguraatiotiedostoihin.

Koska sivu hallitsee tällä hetkellä yhtä koko tilin kattavaa avainta useiden nimettyjen tai rajattujen avainten sijaan, käytä sisäistä integraatiopalvelua tai välityspalvelinta, jos useat sovellukset tarvitsevat parempaa eristystä toisistaan.

Peitä pyyntöotsakkeet

Määritä HTTP-asiakkaat, käänteiset välityspalvelimet, havainnointityökalut ja virheraportointityökalut peittämään X-API-Key. Pyyntö voi toimia oikein ja silti vuotaa tunnistetiedon debug-lokien kautta.

Pidä ympäristöt erillään

Älä käytä tuotantoavainta uudelleen paikallisessa kehityksessä, esimerkkikoodissa, kuvakaappauksissa tai testilaitteistoissa. Tallenna ympäristökohtaiset salaisuudet ympäristökohtaisiin salaisuuksien tallennuspaikkoihin.

“View OpenAPI docs” -linkki ohjaa tuotantokäyttäjät automaattisesti tuotanto-API:n dokumentaatioon. Varmista aina isäntänimi ennen oikean avaimen lähettämistä.

Vaihda avain epäillyn paljastumisen jälkeen

Viestin, repositoriocommitin, lokirivin tai kuvakaappauksen poistaminen ei todista, ettei kukaan kopioinut avainta. Jos täydellinen arvo paljastui, vaihda avain.

API-virheiden käsittely

Päätä integraation toiminta HTTP-tilakoodin ja dokumentoidun vastausrungon perusteella.

Yleisiä tapauksia ovat:

• 400 Bad Request — Polku, parametri tai JSON-runko ei täytä päätepisteen sopimusta. Vertaa pyyntöä OpenAPI-skeemaan.
• 401 Unauthorized — X-API-Key-otsake puuttuu, on tyhjä, virheellinen tai poistettu, tai sisältää vanhan arvon avaimen vaihtamisen jälkeen.
• 403 Forbidden — Todennettua avainta ei sallita kyseiseen toimintoon.
• 404 Not Found — Polkua tai viitattua resurssia ei ole tällä tilillä.
• 429 Too Many Requests — Integraatio on saavuttanut API:n pyyntörajoituksen. Keskeytä pyynnöt ja noudata Retry-After-otsaketta, jos se on mukana.
• 5xx — Maildroppa ei pystynyt käsittelemään pyyntöä. Yritä turvallisia toimintoja uudelleen rajatulla eksponentiaalisella backoffilla ja varmista, etteivät lokit sisällä API-avainta.

Älä yritä kaikkia pyyntöjä uudelleen sokeasti. Korjaa 400-, 401-, 403- ja useimmat 404-vastaukset ennen saman pyynnön lähettämistä uudelleen.

Varmista muuttavia pyyntöjä varten päätepisteen uudelleenyritys- ja idempotenssikäyttäytyminen ennen automaattista toistoa. Yhteysvirhe ei aina todista, ettei Maildroppa tehnyt muutosta.

Vianmääritys

“Create API key” näkyy edelleen

Tilillä ei tällä hetkellä ole avainta. Napsauta painiketta kerran ja odota pyynnön valmistumista.

Jos luominen epäonnistuu, lataa sivu uudelleen ennen uutta yritystä. Toinen sivu tai Automation-asetus on saattanut jo luoda tilin API-avaimen.

Sivulla näkyvä avain näyttää liian lyhyeltä

Sivu näyttää tarkoituksella vain viisi ensimmäistä merkkiä ja *****. Kopioi täydellinen arvo napsauttamalla “Copy”. Älä lähetä peitettyä tekstiä pyyntöön.

“Copy” ei vaihdu muotoon “Copied!”

Selain on saattanut estää pääsyn leikepöydälle. Pidä sivu aktiivisessa välilehdessä, salli leikepöydän käyttö pyydettäessä ja napsauta “Copy” uudelleen.

Älä yritä muodostaa avainta uudelleen peitetyn tekstin perusteella.

Pyyntö palauttaa 401 Unauthorized

Tarkista seuraavat:

• Otsakkeen nimi on täsmälleen X-API-Key.
• Otsake sisältää täydellisen arvon ilman näkyviä tähtiä.
• Integraatio ei lähetä sen sijaan Authorization: Bearer -otsaketta.
• Salaisuuteen ei ole lisätty välilyöntejä, lainausmerkkejä tai rivinvaihtoa.
• Kukaan ei ole vaihtanut tai poistanut tilin avainta.
• Palvelu käynnistettiin uudelleen, jos se lukee ympäristömuuttujat vain käynnistyksen yhteydessä.
• Pyyntö lähetetään oikeaan Maildroppa API -ympäristöön.

Yksi integraatio toimii, mutta toinen lakkasi toimimasta vaihdon jälkeen

Toinen integraatio käyttää todennäköisesti edelleen vanhaa avainta. Päällekkäistä voimassaoloaikaa ei ole. Päivitä sen salaisuus ja käynnistä uudelleen kaikki konfiguraation välimuistiin tallentavat prosessit.

OpenAPI-sivu toimii, mutta päätepiste palauttaa 403

Kaikki sovelluksen päätepisteet eivät tue API-avaimella todennusta. Käytä asiakas-API:ssa dokumentoitua operaatiota ja varmista sen todennusvaatimukset OpenAPI-sivulta.

Pyynnöt palauttavat 429 Too Many Requests

Vähennä pyyntöpiikkejä, aseta työ jonoon ja yritä uudelleen API:n palauttaman viiveen jälkeen. Vältä rinnakkaisten uudelleenyritysten muodostamaa kuormituspiikkiä. Jos useat sovellukset jakavat yhden tilin API-avaimen, koordinoi niiden pyyntömäärää, koska ne jakavat tilin API-rajoitukset.

Suositeltu käyttöönoton tarkistuslista

Varmista ennen integraation säännöllistä käyttöä, että:

• Avain on tallennettu vain palvelinpuolen salaisuuksien konfiguraatioon.
• Pyynnöissä käytetään X-API-Key-otsaketta.
• Integraatio käyttää tuotannossa osoitetta https://api.maildroppa.com.
• Jokainen metodi, polku, parametri ja JSON-runko noudattaa OpenAPI-dokumentaatiota.
• Lokit ja virheraportit peittävät avaimen.
• Aikakatkaisut ja rajatut uudelleenyritykset on määritetty.
• 401-, 403-, 429- ja palvelinvirheitä seurataan.
• Integraation omistaja on kirjattu.
• Kaikki tilin API-avaimen jakavat järjestelmät sisältyvät vaihtosuunnitelmaan.
• Vaarantunut avain voidaan vaihtaa nopeasti.

API-avainsivu on tarkoituksella suppea, mutta sen toiminnot vaikuttavat jokaiseen tiliin yhdistettyyn API-integraatioon. Luo avain vain tarvittaessa, säilytä se luotetuilla palvelimilla ja suunnittele vaihtaminen koko tiliä koskevaksi tunnistetiedon muutokseksi.