Opprett og administrer API-nøkkelen din

Published: 16. juli 2026 · Last updated: 21. juli 2026 · By Marcus Biel

API-nøkkelsiden gir et eksternt system autentisert tilgang til de støttede Maildroppa-API-endepunktene i kontoen din.

Du kan opprette én API-nøkkel, kopiere hele den hemmelige verdien, tilbakestille den på en sikker måte ved å rotere den, eller slette den når den ikke lenger trengs. Den samme kontonøkkelen kan brukes av integrasjoner på serversiden og av utløsere for API-forespørsler i Maildroppa Automations.

En API-nøkkel representerer Maildroppa-kontoen din. Behandle den som et passord: Alle som får tak i nøkkelen, kan kalle API-endepunktene som er tilgjengelige for nøkkelen, frem til du roterer eller sletter den.

Hva API-nøkkelen brukes til

Bruk API-nøkkelen når programvare utenfor Maildroppa må arbeide med Maildroppa uten en interaktiv brukerpålogging.

Vanlige eksempler inkluderer:

• Synkronisering av abonnenter med et CRM-system, en nettbutikk, et medlemssystem eller en intern database.
• Oppretting eller oppdatering av abonnenter fra en serverapplikasjon.
• Lesing eller administrering av tagger, felt, feltverdier og segmenter gjennom støttede endepunkter.
• Sending av egendefinerte hendelser til en utløser for API-forespørsler i en Automation.
• Sending av transaksjonelle e-postmeldinger gjennom API-et.
• Administrering av API-baserte webhook-abonnementer.

API-nøkkelen er beregnet for kommunikasjon mellom servere. Den er ikke beregnet for kode som kjører i nettleseren til en besøkende, på et offentlig nettsted, i en mobilapplikasjon eller i et innebygd påmeldingsskjema.

Siden er for øyeblikket merket «beta». Bruk den lenkede OpenAPI-dokumentasjonen som kilde for endepunktene, forespørselskroppene, parameterne og responsskjemaene som API-et støtter for øyeblikket.

Åpne API-nøkkelsiden

Åpne «Settings», utvid «Developers», og velg «API key».

Du kan også åpne siden direkte på:

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

Siden inneholder:

• Et API-nøkkelpanel med et beta-merke.
• En «View OpenAPI docs»-lenke.
• En tom tilstand og «Create API key»-knappen når ingen nøkkel finnes.
• En maskert visning av den gjeldende nøkkelen når en nøkkel finnes.
• En «Copy»-knapp som kopierer hele nøkkelen.
• Handlingene «Rotate API key» og «Delete API key» for å erstatte eller fjerne den gjeldende nøkkelen.

Maildroppa tillater én API-nøkkel per konto. Siden oppretter ikke separate nøkler for individuelle applikasjoner, miljøer eller teammedlemmer.

Opprett en API-nøkkel

Når siden viser «No API key yet», klikker du på «Create API key».

Maildroppa oppretter nøkkelen umiddelbart. Det vises ingen bekreftelsesdialog ved denne første opprettelsen. Mens forespørselen behandles, endres knappen til «Creating API key», og siden deaktiverer midlertidig andre nøkkelhandlinger.

Etter at nøkkelen er opprettet:

• Forsvinner den tomme tilstanden.
• Vises en maskert nøkkel.
• Blir handlingene «Copy», «Rotate API key» og «Delete API key» tilgjengelige.
• Viser Maildroppa en suksessmelding med teksten «API key updated».

Hvis det allerede finnes en annen nøkkel for kontoen, oppretter ikke Maildroppa en ny. Bruk den eksisterende nøkkelen eller roter den.

Forstå den maskerte nøkkelen

Siden viser ikke hele hemmeligheten som vanlig tekst. Den viser de fem første tegnene etterfulgt av fem stjerner, for eksempel:

a1b2c*****

Dette er bare en visuell maskering. Stjernene representerer ikke nøkkelens faktiske lengde, og den maskerte verdien kan ikke brukes i en API-forespørsel.

Klikk på «Copy» for å skrive hele den gjeldende nøkkelen til utklippstavlen. Etter en vellykket kopiering endres knappen kortvarig til «Copied!».

Nøkkelen forblir maskert når du kommer tilbake til siden, men «Copy» kopierer fortsatt hele den gjeldende verdien. Du trenger derfor ikke rotere en gyldig nøkkel bare fordi du ikke lagret den da den ble opprettet.

Oppbevar nøkkelen sikkert

Flytt den kopierte nøkkelen direkte til den hemmelige lagringen som integrasjonen bruker.

Egnede plasseringer inkluderer:

• En administrert hemmelighetsbehandler.
• Beskyttet serverkonfigurasjon i miljøet.
• En kryptert distribusjonshemmelighet.
• En passordbehandler som brukes til operativ gjenoppretting.

Ikke lagre nøkkelen i:

• JavaScript på klientsiden eller en annen nedlastbar frontend-pakke.
• En offentlig eller privat kildekodefil som er lagret i et repository.
• En URL eller spørringsparameter.
• Offentlig dokumentasjon, skjermbilder, supportmeldinger eller sakssystemer.
• Delte applikasjonslogger, analysehendelser eller feilrapporter.
• Et ukryptert regneark eller vanlig teamchat.

Ikke legg nøkkelen i et curl-eksempel som skal kopieres inn i dokumentasjon eller en skallhistorikk som deles med andre. Foretrekk en miljøvariabel som MAILDROPPA_API_KEY.

Bruk API-nøkkelen

Send hele nøkkelen i HTTP-forespørselshodet X-API-Key:

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

Ikke send den som et Bearer-token. Maildroppa forventer X-API-Key, ikke Authorization: Bearer ....

Produksjons-API-et og den interaktive OpenAPI-dokumentasjonen er tilgjengelige på:

https://api.maildroppa.com

Klikk på «View OpenAPI docs» på API-nøkkelsiden for å åpne dokumentasjonen i en ny nettleserfane. Velg et endepunkt der for å se gjennom metoden, banen, parameterne, forespørselskroppen, responstypen og mulige statuskoder.

Eksempelforespørsel

Følgende eksempel henter den første siden med abonnenter. Det leser nøkkelen fra en miljøvariabel i stedet for å plassere hemmeligheten direkte i kommandoen:

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

Angi variabelen i det sikre miljøet der integrasjonen kjører. Den nøyaktige metoden, banen, spørringsparameterne og kroppen avhenger av endepunktet. Kopier disse detaljene fra OpenAPI-dokumentasjonen i stedet for å gjette dem ut fra handlinger som er tilgjengelige i Maildroppa-applikasjonen.

Forespørsler med JSON-kropper

For en forespørsel som sender JSON, må du også inkludere:

Content-Type: application/json

Den grunnleggende strukturen er for eksempel:

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 og kroppen er plassholdere. Erstatt dem med et dokumentert endepunkt og det dokumenterte forespørselsskjemaet.

Hva nøkkelen har tilgang til

Nøkkelen fungerer bare med endepunkter som støtter API-nøkkelautentisering. En side eller forespørsel som brukes internt av Maildroppa-applikasjonen, er ikke automatisk en del av det offentlige kunde-API-et.

OpenAPI-dokumentasjonen viser det støttede kunde-API-et. Hvis en bane ikke er dokumentert for bruk med API-nøkkel, må du ikke anta at nøkkelen kan få tilgang til den.

API-nøkkelsiden tilbyr ikke scopes eller avkrysningsbokser for tillatelser per endepunkt. Den gjeldende kontonøkkelen må derfor behandles som en verdifull legitimasjon, selv om én integrasjon bare bruker ett enkelt endepunkt.

Hastighetsbegrensninger

Den gjeldende OpenAPI-kontrakten dokumenterer disse grensene for API-nøkler:

• Standard kunde-API: 300 forespørsler per minutt og 2 000 forespørsler per time.
• Events API på /events: 100 forespørsler per sekund med en burst-kapasitet på 500 forespørsler.

Disse grensene gjelder Maildroppa-kontoen, ikke uavhengig for hvert skript som deler nøkkelen. Flere integrasjoner kan derfor bruke av den samme kvoten.

Når Maildroppa returnerer 429 Too Many Requests, må du stoppe å sende nye forespørsler og følge Retry-After-responsheaderen når den finnes. Bruk en kø og kontrollert backoff i stedet for å starte mange parallelle nye forsøk.

Retningslinjer for hastighetsbegrensninger kan endres mens API-et er i beta. Sjekk informasjonen øverst i OpenAPI-dokumentasjonen før du utformer integrasjoner med høyt volum.

Bruk nøkkelen til API-forespørsler i Automations

En Automation kan starte når systemet ditt sender en egendefinert hendelse til Maildroppas Events API.

Når du konfigurerer en «API request»-utløser, bruker Maildroppa den samme konto-API-nøkkelen som administreres på denne siden. Utløseroppsettet kan opprette nøkkelen når ingen finnes, og kan kopiere en klargjort curl-forespørsel som inneholder hele nøkkelen.

Dette har to viktige konsekvenser:

• Rotering eller sletting av kontonøkkelen påvirker også systemer som sender egendefinerte hendelser til Automations.
• Et kopiert eksempel på en Automation-forespørsel inneholder hemmeligheten på utklippstavlen, selv om nøkkelen er maskert på skjermen.

Før du roterer eller sletter nøkkelen, må du inkludere alle utløsere for API-forespørsler og alle eksterne avsendere av hendelser i integrasjonsoversikten din.

Tilbakestille eller erstatte API-nøkkelen

Bruk «Rotate API key» når du må tilbakestille eller erstatte den gjeldende legitimasjonen. Maildroppa oppretter en ny nøkkel og ugyldiggjør den forrige nøkkelen som del av samme handling.

Bruk rotering når:

• Nøkkelen kan ha blitt eksponert.
• En person eller leverandør som kjente nøkkelen, ikke lenger trenger tilgang.
• Sikkerhetspolicyen din krever periodisk utskifting av legitimasjon.
• Du vil erstatte en nøkkel som er lagret på en gammel eller usikker plassering.

Klikk på «Rotate API key» under den maskerte nøkkelen. Maildroppa åpner en advarselsdialog som forklarer at den eksisterende nøkkelen ikke lenger vil kunne brukes.

Klikk på «Rotate API key» i dialogen for å fortsette, eller klikk på «Cancel» for å beholde den gjeldende nøkkelen.

Rotering har ingen friperiode

Etter at du har bekreftet roteringen, slutter den gamle nøkkelen å fungere umiddelbart. Maildroppa holder ikke den gamle og den nye nøkkelen gyldige samtidig.

Fordi kontoen bare har én nøkkel, påvirker rotering alle servere, planlagte jobber, integrasjoner, skript og avsendere av Automation-hendelser som bruker den.

Bruk denne sekvensen for en planlagt rotering:

1. List opp alle integrasjoner som bruker den gjeldende nøkkelen.
2. Sørg for tilgang til den hemmelige konfigurasjonen og distribusjonsprosessen for hver integrasjon.
3. Velg et kort vedlikeholdsvindu hvis uavbrutt API-tilgang er viktig.
4. Klikk på «Rotate API key», og bekreft deretter advarselen med «Rotate API key» i dialogen.
5. Klikk på «Copy» for å kopiere hele den nye nøkkelen.
6. Erstatt hemmeligheten i alle integrasjoner umiddelbart.
7. Start tjenester som bare laster inn hemmeligheter ved oppstart, på nytt, eller distribuer dem på nytt.
8. Send en ufarlig, dokumentert forespørsel for å bekrefte hver integrasjon.
9. Se etter 401 Unauthorized-svar fra en glemt tjeneste som fortsatt bruker den gamle nøkkelen.

Hvis du tror at den gjeldende nøkkelen er kompromittert, må du rotere den umiddelbart og akseptere det korte avbruddet som kreves for å oppdatere legitime systemer.

Slette API-nøkkelen

Slett nøkkelen når kontoen ikke lenger skal godta API-nøkkelautentiserte forespørsler.

Klikk på «Delete API key» under den maskerte nøkkelen. Maildroppa åpner en advarselsdialog som forklarer at nøkkelen fjernes permanent fra kontoen.

Klikk på «Delete API key» i dialogen for å slette den, eller klikk på «Cancel» for å beholde den.

Etter sletting:

• Slutter den gjeldende nøkkelen å fungere umiddelbart.
• Går siden tilbake til tilstanden «No API key yet».
• Kan serverintegrasjoner som bruker den slettede nøkkelen, ikke lenger autentisere.
• Kan avsendere av Automation-API-forespørsler som bruker nøkkelen, ikke lenger levere hendelser.

Sletting av en nøkkel sletter ikke abonnenter, kampanjer, tagger, felt, segmenter, Automations eller andre kontodata. Den fjerner legitimasjonen som brukes for å få tilgang til støttede API-endepunkter.

Du kan klikke på «Create API key» senere for å opprette en ny legitimasjon. Den slettede verdien gjenopprettes ikke. Alle integrasjoner må oppdateres før de kan bruke den nye nøkkelen.

Tilbakestille eller slette: Hva bør du velge?

Velg «Rotate API key» når API-tilgangen skal fortsette med en ny legitimasjon.

Velg sletting når API-tilgangen skal stoppes helt, i alle fall foreløpig.

Begge handlingene ugyldiggjør den gjeldende nøkkelen umiddelbart. Rotering oppretter erstatningen som del av samme handling, mens sletting etterlater kontoen uten en nøkkel.

Sikkerhetsanbefalinger

Hold API-kall på serveren din

En nettleser eller mobilapp kan ikke pålitelig holde på en innebygd hemmelighet. En bruker kan inspisere applikasjonen, forespørselshoder, kildekart eller nettverkstrafikk og hente ut nøkkelen.

Hvis et nettsted eller en app trenger å utløse en handling, sender du først forespørselen til din egen autentiserte backend. La backend-løsningen validere brukeren og kalle Maildroppa med nøkkelen som er lagret på serveren.

Begrens eksponeringen mest mulig

Gi nøkkelen bare til systemer som trenger den. Ikke distribuer den til alle utviklere eller lim den inn i flere lokale konfigurasjonsfiler.

Fordi siden for øyeblikket administrerer én kontoomfattende nøkkel i stedet for flere navngitte eller avgrensede nøkler, bør du bruke en intern integrasjonstjeneste eller proxy hvis flere applikasjoner trenger sterkere isolasjon fra hverandre.

Masker forespørselshoder

Konfigurer HTTP-klienter, reverse proxyer, verktøy for overvåking og feilrapporteringsverktøy til å maskere X-API-Key. En forespørsel kan fungere korrekt samtidig som legitimasjonen lekker gjennom feilsøkingslogger.

Hold separate miljøer atskilt

Ikke bruk en produksjonsnøkkel på nytt i lokal utvikling, eksempelkode, skjermbilder eller testdata. Lagre miljøspesifikke hemmeligheter i miljøspesifikke hemmelighetslagre.

Lenken «View OpenAPI docs» peker automatisk produksjonsbrukere til produksjonsdokumentasjonen for API-et. Kontroller alltid vertsnavnet før du sender en ekte nøkkel.

Roter etter enhver mistenkt eksponering

Sletting av en melding, en commit i et repository, en logglinje eller et skjermbilde beviser ikke at ingen kopierte nøkkelen. Hvis hele verdien ble eksponert, må du rotere den.

Håndtere API-feil

Bruk HTTP-statusen og den dokumenterte responskroppen for å avgjøre hva integrasjonen skal gjøre.

Vanlige tilfeller inkluderer:

• 400 Bad Request — Banen, parameteren eller JSON-kroppen oppfyller ikke kontrakten for endepunktet. Sammenlign forespørselen med OpenAPI-skjemaet.
• 401 Unauthorized — X-API-Key-headeren mangler, er tom, ugyldig, slettet eller inneholder en gammel verdi etter rotering.
• 403 Forbidden — Den autentiserte nøkkelen har ikke tillatelse til å bruke operasjonen.
• 404 Not Found — Banen eller den refererte ressursen finnes ikke i denne kontoen.
• 429 Too Many Requests — Integrasjonen har nådd en API-hastighetsgrense. Sett forespørsler på pause og følg Retry-After-headeren når den finnes.
• 5xx — Maildroppa kunne ikke fullføre forespørselen. Prøv trygge operasjoner på nytt med begrenset eksponentiell backoff og logging som utelater API-nøkkelen.

Ikke prøv blindt på nytt ved enhver feil. Korriger 400, 401, 403 og de fleste 404-svar før du sender den samme forespørselen på nytt.

For endrende forespørsler må du bekrefte endepunktets oppførsel for nye forsøk og idempotens før du gjentar en forespørsel automatisk. En tilkoblingsfeil beviser ikke alltid at Maildroppa ikke gjorde noen endring.

Feilsøking

«Create API key» vises fortsatt

Det finnes for øyeblikket ingen nøkkel i kontoen. Klikk på knappen én gang og vent til forespørselen er fullført.

Hvis opprettelsen mislykkes, laster du siden på nytt før du prøver igjen. En annen side eller et Automation-oppsett kan allerede ha opprettet kontonøkkelen.

Nøkkelen på siden ser for kort ut

Siden viser med hensikt bare de fem første tegnene og *****. Klikk på «Copy» for å kopiere hele verdien. Ikke send den maskerte teksten i en forespørsel.

«Copy» endres ikke til «Copied!»

Nettleseren kan ha blokkert tilgang til utklippstavlen. La siden være i den aktive fanen, tillat tilgang til utklippstavlen hvis du blir spurt, og klikk på «Copy» igjen.

Ikke prøv å rekonstruere nøkkelen fra den maskerte teksten.

En forespørsel returnerer 401 Unauthorized

Kontroller at:

• Headernavnet er nøyaktig X-API-Key.
• Headeren inneholder hele verdien, uten de synlige stjernene.
• Integrasjonen ikke sender Authorization: Bearer i stedet.
• Det ikke er lagt til mellomrom, anførselstegn eller et linjeskift i hemmeligheten.
• Ingen har rotert eller slettet kontonøkkelen.
• En tjeneste ble startet på nytt hvis den bare leser miljøvariabler ved oppstart.
• Forespørselen sendes til riktig Maildroppa-API-miljø.

Én integrasjon fungerer, men en annen sluttet å fungere etter rotering

Den andre integrasjonen bruker sannsynligvis fortsatt den gamle nøkkelen. Det finnes ingen overlappingsperiode. Oppdater hemmeligheten og start prosesser som mellomlagrer konfigurasjon, på nytt.

OpenAPI-siden fungerer, men et endepunkt returnerer 403

Ikke alle applikasjonsendepunkter støtter API-nøkkelautentisering. Bruk en operasjon som er dokumentert for kunde-API-et, og bekreft autentiseringskravene på OpenAPI-siden.

Forespørsler returnerer 429 Too Many Requests

Reduser forespørselsutbrudd, legg arbeidet i kø, og prøv på nytt etter forsinkelsen som API-et returnerer. Unngå parallelle stormer av nye forsøk. Hvis flere applikasjoner deler den ene kontonøkkelen, må du koordinere forespørselsvolumet fordi de deler kontoens API-grenser.

Sjekkliste for anbefalt oppsett

Før du tar en integrasjon i vanlig bruk, må du bekrefte at:

• Nøkkelen bare lagres i hemmelig konfigurasjon på serversiden.
• Forespørsler bruker X-API-Key-headeren.
• Integrasjonen bruker https://api.maildroppa.com i produksjon.
• Alle metoder, baner, parametere og JSON-kropper følger OpenAPI-dokumentasjonen.
• Logger og feilrapporter maskerer nøkkelen.
• Tidsavbrudd og begrensede nye forsøk er konfigurert.
• 401, 403, 429 og serverfeil overvåkes.
• Integrasjonens eier er registrert.
• Alle systemer som deler kontonøkkelen, er inkludert i planen for rotering.
• En kompromittert nøkkel kan roteres raskt.

API-nøkkelsiden er med hensikt liten, men handlingene påvirker alle API-integrasjoner som er koblet til kontoen. Opprett nøkkelen bare når den trengs, oppbevar den på pålitelige servere, og planlegg rotering som en kontoomfattende endring av legitimasjonen.