Je API-sleutel maken en beheren

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

Op de pagina API-sleutel krijgt een extern systeem geauthenticeerde toegang tot de ondersteunde Maildroppa API-eindpunten in je account.

Je kunt één API-sleutel maken, de volledige geheime waarde kopiëren, deze veilig resetten door hem te roteren, of verwijderen wanneer je hem niet meer nodig hebt. Dezelfde accountsleutel kan worden gebruikt door server-side-integraties en door API-aanvraagtriggers in Maildroppa Automations.

Een API-sleutel vertegenwoordigt je Maildroppa-account. Behandel hem als een wachtwoord: iedereen die de sleutel verkrijgt, kan de voor die sleutel beschikbare API-eindpunten aanroepen totdat je de sleutel roteert of verwijdert.

Waarvoor de API-sleutel dient

Gebruik de API-sleutel wanneer software buiten Maildroppa met Maildroppa moet werken zonder interactieve gebruikersaanmelding.

Veelvoorkomende voorbeelden zijn:

• Abonnees synchroniseren met een CRM, webshop, ledensysteem of interne database.
• Abonnees maken of bijwerken vanuit een server-side-applicatie.
• Tags, velden, veldwaarden en segmenten lezen of beheren via ondersteunde eindpunten.
• Aangepaste gebeurtenissen naar een API-aanvraagtrigger in een Automation sturen.
• Transactionele e-mailberichten via de API verzenden.
• API-gebaseerde webhookabonnementen beheren.

De API-sleutel is bedoeld voor server-to-servercommunicatie. Hij is niet bedoeld voor code die in de browser van een bezoeker, op een openbare website, in een mobiele applicatie of in een ingesloten inschrijfformulier wordt uitgevoerd.

De pagina is momenteel gemarkeerd als “beta”. Gebruik de gekoppelde OpenAPI-documentatie als bron voor de eindpunten, request bodies, parameters en response-schema's die momenteel door de API worden ondersteund.

De pagina API-sleutel openen

Open “Settings”, vouw “Developers” uit en selecteer “API key”.

Je kunt de pagina ook rechtstreeks openen via:

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

De pagina bevat:

• Een API-sleutelpaneel met een beta-badge.
• Een link “View OpenAPI docs”.
• Een lege status en de knop “Create API key” wanneer er geen sleutel bestaat.
• Een gemaskeerde weergave van de huidige sleutel wanneer er wel een bestaat.
• Een knop “Copy” waarmee de volledige sleutel wordt gekopieerd.
• Acties “Rotate API key” en “Delete API key” om de huidige sleutel te vervangen of te verwijderen.

Maildroppa staat één API-sleutel per account toe. De pagina maakt geen afzonderlijke sleutels voor individuele applicaties, omgevingen of teamleden.

Een API-sleutel maken

Wanneer op de pagina “No API key yet” wordt weergegeven, klik je op “Create API key”.

Maildroppa maakt de sleutel onmiddellijk aan. Bij deze eerste aanmaak verschijnt geen bevestigingsvenster. Terwijl de aanvraag wordt uitgevoerd, verandert de knop in “Creating API key” en schakelt de pagina verdere sleutelacties tijdelijk uit.

Nadat de sleutel is aangemaakt:

• Verdwijnt de lege status.
• Verschijnt een gemaskeerde sleutel.
• Komen de acties “Copy”, “Rotate API key” en “Delete API key” beschikbaar.
• Toont Maildroppa een succesmelding “API key updated”.

Als er al een andere sleutel voor het account bestaat, maakt Maildroppa geen tweede sleutel aan. Gebruik de bestaande sleutel of roteer hem.

De gemaskeerde sleutel begrijpen

De pagina toont het volledige geheim niet als gewone tekst. Je ziet de eerste vijf tekens, gevolgd door vijf sterretjes, bijvoorbeeld:

a1b2c*****

Dit is alleen een visueel masker. De sterretjes geven niet de werkelijke lengte van de sleutel weer en de gemaskeerde waarde kan niet voor een API-aanvraag worden gebruikt.

Klik op “Copy” om de volledige huidige sleutel naar je klembord te kopiëren. Na een geslaagde kopieeractie verandert de knop kort in “Copied!”.

Wanneer je terugkeert naar de pagina, blijft de sleutel gemaskeerd, maar met “Copy” wordt nog steeds de volledige huidige waarde gekopieerd. Je hoeft een geldige sleutel dus niet te roteren alleen omdat je hem bij het aanmaken niet hebt opgeslagen.

De sleutel veilig opslaan

Verplaats de gekopieerde sleutel rechtstreeks naar de geheime opslag die door de integratie wordt gebruikt.

Geschikte locaties zijn onder andere:

• Een beheerde secretmanager.
• Beveiligde serveromgevingsconfiguratie.
• Een versleuteld deploymentgeheim.
• Een wachtwoordmanager die wordt gebruikt voor operationeel herstel.

Sla de sleutel niet op in:

• JavaScript aan de browserzijde of een andere downloadbare frontendbundel.
• Een openbaar of privébroncodebestand dat naar een repository is gecommit.
• Een URL of queryparameter.
• Openbare documentatie, schermafbeeldingen, supportberichten of issue trackers.
• Gedeelde applicatielogboeken, analytics-events of foutrapporten.
• Een niet-versleuteld spreadsheet of gewone teamchat.

Voeg de sleutel niet toe aan een curl-voorbeeld dat in documentatie of gedeelde shellgeschiedenis wordt gekopieerd. Gebruik bij voorkeur een omgevingsvariabele zoals MAILDROPPA_API_KEY.

De API-sleutel gebruiken

Stuur de volledige sleutel mee in de HTTP-requestheader X-API-Key:

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

Stuur hem niet als Bearer-token. Maildroppa verwacht X-API-Key, niet Authorization: Bearer ....

De productie-API en de interactieve OpenAPI-documentatie zijn beschikbaar via:

https://api.maildroppa.com

Klik op “View OpenAPI docs” op de pagina API-sleutel om de documentatie in een nieuw browsertabblad te openen. Selecteer daar een eindpunt om de methode, het pad, de parameters, de request body, het responstype en mogelijke statuscodes te bekijken.

Voorbeeldrequest

In het volgende voorbeeld wordt de eerste pagina met abonnees opgehaald. De sleutel wordt uit een omgevingsvariabele gelezen in plaats van rechtstreeks in de opdracht te worden geplaatst:

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

Stel de variabele in de beveiligde omgeving in waarin de integratie wordt uitgevoerd. De exacte methode, het pad, de queryparameters en de body zijn afhankelijk van het eindpunt. Kopieer deze gegevens uit de OpenAPI-documentatie in plaats van ze af te leiden uit acties die in de Maildroppa-applicatie beschikbaar zijn.

Requests met JSON-bodies

Voeg bij een request dat JSON verstuurt ook het volgende toe:

Content-Type: application/json

De basisstructuur is bijvoorbeeld:

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 en de body zijn placeholders. Vervang ze door een gedocumenteerd eindpunt en het bijbehorende gedocumenteerde request-schema.

Waartoe de sleutel toegang geeft

De sleutel werkt alleen met eindpunten die API-sleutelauthenticatie ondersteunen. Een pagina of request dat intern door de Maildroppa-applicatie wordt gebruikt, maakt niet automatisch deel uit van de openbare customer API.

De OpenAPI-documentatie toont de ondersteunde customer API. Als een pad niet is gedocumenteerd voor gebruik met een API-sleutel, ga er dan niet van uit dat de sleutel er toegang toe heeft.

De pagina API-sleutel biedt geen scopes of selectievakjes voor machtigingen per eindpunt. De huidige accountsleutel moet daarom als een waardevol geheim worden behandeld, ook als één integratie slechts één eindpunt gebruikt.

Rate limits

Het huidige OpenAPI-contract documenteert de volgende limieten voor API-sleutels:

• Standaard customer API: 300 requests per minuut en 2.000 requests per uur.
• Events API op /events: 100 requests per seconde met een burstcapaciteit van 500 requests.

Deze limieten worden toegepast op het Maildroppa-account, niet afzonderlijk op elk script dat de sleutel deelt. Meerdere integraties kunnen dezelfde toegestane hoeveelheid dus verbruiken.

Wanneer Maildroppa 429 Too Many Requests retourneert, stop je met het versturen van nieuwe requests en volg je de responseheader Retry-After wanneer die aanwezig is. Gebruik een wachtrij en gecontroleerde backoff in plaats van veel parallelle nieuwe pogingen te starten.

Rate-limitbeleid kan veranderen terwijl de API zich in de beta bevindt. Controleer de informatie bovenaan de OpenAPI-documentatie voordat je integraties met grote volumes ontwerpt.

De sleutel gebruiken voor Automation API-aanvragen

Een Automation kan starten wanneer je systeem een aangepaste gebeurtenis naar de Events API van Maildroppa stuurt.

Wanneer je een trigger van het type “API request” configureert, gebruikt Maildroppa dezelfde accountsleutel die op deze pagina wordt beheerd. De triggerconfiguratie kan de sleutel aanmaken wanneer er nog geen bestaat en een voorbereid curl-request met de volledige sleutel kopiëren.

Dit heeft twee belangrijke gevolgen:

• Het roteren of verwijderen van de accountsleutel heeft ook gevolgen voor systemen die aangepaste gebeurtenissen naar Automations sturen.
• Een gekopieerd voorbeeldrequest voor een Automation bevat het geheim op het klembord, ook al is de sleutel op het scherm gemaskeerd.

Neem vóór het roteren of verwijderen van de sleutel elke API-aanvraagtrigger en elke externe verzender van gebeurtenissen op in je integratie-inventaris.

De API-sleutel resetten of vervangen

Gebruik “Rotate API key” wanneer je de huidige inloggegevens wilt resetten of vervangen. Maildroppa maakt een nieuwe sleutel aan en maakt de vorige sleutel ongeldig als onderdeel van dezelfde actie.

Gebruik rotatie wanneer:

• De sleutel mogelijk is blootgesteld.
• Een persoon of provider die de sleutel kende geen toegang meer nodig heeft.
• Je beveiligingsbeleid periodieke vervanging van inloggegevens vereist.
• Je een sleutel wilt vervangen die op een oude of onveilige locatie is opgeslagen.

Klik onder de gemaskeerde sleutel op “Rotate API key”. Maildroppa opent een waarschuwingsvenster waarin wordt uitgelegd dat de bestaande sleutel niet langer bruikbaar zal zijn.

Klik in het venster op “Rotate API key” om door te gaan, of klik op “Cancel” om de huidige sleutel te behouden.

Rotatie heeft geen overgangsperiode

Nadat je de rotatie hebt bevestigd, werkt de oude sleutel onmiddellijk niet meer. Maildroppa houdt de oude en nieuwe sleutel niet tegelijkertijd geldig.

Omdat het account slechts één sleutel heeft, heeft rotatie gevolgen voor elke server, geplande taak, integratie, script en verzender van Automation-gebeurtenissen die de sleutel gebruikt.

Gebruik voor een geplande rotatie deze volgorde:

1. Noteer elke integratie die de huidige sleutel gebruikt.
2. Zorg dat je toegang hebt tot de geheime configuratie en het deploymentproces van elke integratie.
3. Kies een kort onderhoudsvenster als ononderbroken API-toegang belangrijk is.
4. Klik op “Rotate API key” en bevestig de waarschuwing vervolgens met “Rotate API key” in het venster.
5. Klik op “Copy” om de volledige nieuwe sleutel te kopiëren.
6. Vervang het geheim onmiddellijk in elke integratie.
7. Start services die geheimen alleen bij het opstarten laden opnieuw of deploy ze opnieuw.
8. Verstuur een onschadelijk, gedocumenteerd request om elke integratie te controleren.
9. Controleer op 401 Unauthorized-responses van een vergeten service die nog steeds de oude sleutel gebruikt.

Als je denkt dat de huidige sleutel is gecompromitteerd, roteer hem dan onmiddellijk en accepteer de korte onderbreking die nodig is om legitieme systemen bij te werken.

De API-sleutel verwijderen

Verwijder de sleutel wanneer het account geen API-key-geauthenticeerde requests meer moet accepteren.

Klik onder de gemaskeerde sleutel op “Delete API key”. Maildroppa opent een waarschuwingsvenster waarin wordt uitgelegd dat de sleutel permanent uit het account wordt verwijderd.

Klik in het venster op “Delete API key” om de sleutel te verwijderen, of klik op “Cancel” om hem te behouden.

Na verwijdering:

• Werkt de huidige sleutel onmiddellijk niet meer.
• Keert de pagina terug naar de status “No API key yet”.
• Kunnen serverintegraties die de verwijderde sleutel gebruiken niet langer authenticeren.
• Kunnen API-aanvraagverzenders van Automations die deze sleutel gebruiken geen gebeurtenissen meer afleveren.

Het verwijderen van een sleutel verwijdert geen abonnees, campagnes, tags, velden, segmenten, Automations of andere accountgegevens. Alleen de inloggegevens voor toegang tot ondersteunde API-eindpunten worden verwijderd.

Je kunt later op “Create API key” klikken om nieuwe inloggegevens aan te maken. De verwijderde waarde wordt niet hersteld. Elke integratie moet worden bijgewerkt voordat deze de nieuwe sleutel kan gebruiken.

Resetten of verwijderen: wat moet je kiezen?

Kies “Rotate API key” wanneer de API-toegang met nieuwe inloggegevens moet blijven werken.

Kies verwijderen wanneer de API-toegang volledig moet stoppen, in ieder geval voorlopig.

Beide acties maken de huidige sleutel onmiddellijk ongeldig. Rotatie maakt de vervangende sleutel aan als onderdeel van dezelfde actie; verwijdering laat het account zonder sleutel achter.

Beveiligingsaanbevelingen

Houd API-aanroepen op je server

Een browser of mobiele app kan een ingebed geheim niet betrouwbaar geheimhouden. Een gebruiker kan de applicatie, requestheaders, sourcemaps of netwerkverkeer inspecteren en de sleutel achterhalen.

Als een website of app een actie moet activeren, stuur je het request eerst naar je eigen geauthenticeerde backend. Laat die backend de gebruiker valideren en Maildroppa aanroepen met de sleutel die op de server is opgeslagen.

Beperk blootstelling zoveel mogelijk

Geef de sleutel alleen aan systemen die hem nodig hebben. Verspreid hem niet onder elke ontwikkelaar en plak hem niet in meerdere lokale configuratiebestanden.

Omdat de pagina momenteel één accountbrede sleutel beheert in plaats van meerdere benoemde of afgebakende sleutels, kun je een interne integratieservice of proxy gebruiken als meerdere applicaties sterker van elkaar moeten worden geïsoleerd.

Redigeer requestheaders

Configureer HTTP-clients, reverse proxies, observabilitytools en foutrapportagetools om X-API-Key te redigeren. Een request kan correct werken en toch het geheim lekken via debuglogging.

Houd omgevingen gescheiden

Gebruik een productiesleutel niet opnieuw in lokale ontwikkeling, voorbeeldcode, schermafbeeldingen of testfixtures. Bewaar omgevingsspecifieke geheimen in omgevingsspecifieke secret stores.

De link “View OpenAPI docs” verwijst productiegebruikers automatisch naar de documentatie van de productie-API. Controleer altijd de hostnaam voordat je een echte sleutel verstuurt.

Roteer na elke vermoedelijke blootstelling

Het verwijderen van een bericht, repository-commit, logregel of schermafbeelding bewijst niet dat niemand de sleutel heeft gekopieerd. Als de volledige waarde is blootgesteld, roteer je de sleutel.

API-fouten afhandelen

Gebruik de HTTP-status en de gedocumenteerde response body om te bepalen wat de integratie moet doen.

Veelvoorkomende gevallen zijn:

• 400 Bad Request — Het pad, de parameter of de JSON-body voldoet niet aan het contract van het eindpunt. Vergelijk het request met het OpenAPI-schema.
• 401 Unauthorized — De header X-API-Key ontbreekt, is leeg of ongeldig, is verwijderd of bevat na rotatie een oude waarde.
• 403 Forbidden — De geauthenticeerde sleutel mag die bewerking niet uitvoeren.
• 404 Not Found — Het pad of de verwezen resource bestaat niet in dit account.
• 429 Too Many Requests — De integratie heeft een API-rate limit bereikt. Pauzeer requests en volg de header Retry-After wanneer die aanwezig is.
• 5xx — Maildroppa kon het request niet voltooien. Herhaal veilige bewerkingen met begrensde exponentiële backoff en logging waarin de API-sleutel niet voorkomt.

Herhaal niet blind elke fout. Los 400, 401, 403 en de meeste 404-responses op voordat je hetzelfde request opnieuw verstuurt.

Controleer bij muterende requests het retry- en idempotentiegedrag van het eindpunt voordat je een request automatisch opnieuw verstuurt. Een verbindingsfout bewijst niet altijd dat Maildroppa geen wijziging heeft doorgevoerd.

Probleemoplossing

“Create API key” blijft zichtbaar

Er bestaat momenteel geen sleutel in het account. Klik eenmaal op de knop en wacht totdat het request is voltooid.

Als het aanmaken mislukt, laad je de pagina opnieuw voordat je het opnieuw probeert. Een andere pagina of Automationconfiguratie kan de accountsleutel al hebben aangemaakt.

De sleutel op de pagina lijkt te kort

De pagina toont bewust alleen de eerste vijf tekens en *****. Klik op “Copy” om de volledige waarde te kopiëren. Verstuur de gemaskeerde tekst niet in een request.

“Copy” verandert niet in “Copied!”

De browser kan de toegang tot het klembord hebben geblokkeerd. Houd de pagina in het actieve tabblad, geef toegang tot het klembord als daarom wordt gevraagd en klik opnieuw op “Copy”.

Probeer de sleutel niet uit de gemaskeerde tekst te reconstrueren.

Een request retourneert 401 Unauthorized

Controleer of:

• De headernaam exact X-API-Key is.
• De header de volledige waarde bevat, zonder de zichtbare sterretjes.
• De integratie niet in plaats daarvan Authorization: Bearer verstuurt.
• Er geen spaties, aanhalingstekens of regeleinden aan het geheim zijn toegevoegd.
• Niemand de accountsleutel heeft geroteerd of verwijderd.
• Een service opnieuw is gestart als deze omgevingsvariabelen alleen bij het opstarten leest.
• Het request naar de juiste Maildroppa-API-omgeving wordt verstuurd.

Eén integratie werkt, maar een andere stopte na rotatie

De tweede integratie gebruikt waarschijnlijk nog de oude sleutel. Er is geen overlapperiode. Werk het geheim bij en start elk proces dat de configuratie in de cache houdt opnieuw.

De OpenAPI-pagina werkt, maar een eindpunt retourneert 403

Niet elk applicatie-eindpunt ondersteunt authenticatie met een API-sleutel. Gebruik een bewerking die in de customer API is gedocumenteerd en controleer de authenticatievereisten op de OpenAPI-pagina.

Requests retourneren 429 Too Many Requests

Verminder requestpieken, plaats werk in een wachtrij en probeer het opnieuw na de vertraging die door de API wordt geretourneerd. Vermijd parallelle retry-stormen. Als meerdere applicaties dezelfde accountsleutel delen, stem dan hun requestvolume op elkaar af omdat ze dezelfde accountlimieten delen.

Aanbevolen checklist voor configuratie

Controleer voordat je een integratie regelmatig gaat gebruiken of:

• De sleutel alleen in server-side secretconfiguratie is opgeslagen.
• Requests de header X-API-Key gebruiken.
• De integratie in productie https://api.maildroppa.com gebruikt.
• Elke methode, elk pad, elke parameter en elke JSON-body de OpenAPI-documentatie volgt.
• Logboeken en foutrapporten de sleutel redigeren.
• Time-outs en begrensde retries zijn geconfigureerd.
• 401, 403, 429 en serverfouten worden gemonitord.
• De eigenaar van de integratie is vastgelegd.
• Elk systeem dat de accountsleutel deelt in het rotatieplan is opgenomen.
• Een gecompromitteerde sleutel snel kan worden geroteerd.

De pagina API-sleutel is bewust klein, maar de acties ervan hebben gevolgen voor elke API-integratie die met het account is verbonden. Maak de sleutel alleen aan wanneer dat nodig is, bewaar hem op vertrouwde servers en plan rotatie als een accountbrede wijziging van inloggegevens.