Créer et gérer votre clé API

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

La page Clé API permet à un système externe d’accéder de manière authentifiée aux points de terminaison de l’API Maildroppa pris en charge dans votre compte.

Vous pouvez créer une clé API, copier la totalité de sa valeur secrète, la réinitialiser en toute sécurité en la faisant tourner, ou la supprimer lorsqu’elle n’est plus nécessaire. La même clé de compte peut être utilisée par les intégrations côté serveur et par les déclencheurs de requêtes API dans les automatisations Maildroppa.

Une clé API représente votre compte Maildroppa. Traitez-la comme un mot de passe : toute personne qui obtient la clé peut appeler les points de terminaison API auxquels elle donne accès jusqu’à ce que vous la fassiez tourner ou la supprimiez.

À quoi sert la clé API

Utilisez la clé API lorsqu’un logiciel externe à Maildroppa doit interagir avec Maildroppa sans connexion utilisateur interactive.

Voici quelques exemples courants :

• Synchroniser les abonnés avec un CRM, une boutique, un système d’adhésion ou une base de données interne.
• Créer ou mettre à jour des abonnés depuis une application côté serveur.
• Lire ou gérer les tags, les champs, les valeurs de champs et les segments via les points de terminaison pris en charge.
• Envoyer des événements personnalisés à un déclencheur de requête API dans une automatisation.
• Envoyer des messages e-mail transactionnels via l’API.
• Gérer les abonnements aux webhooks basés sur l’API.

La clé API est destinée aux communications de serveur à serveur. Elle n’est pas destinée au code exécuté dans le navigateur d’un visiteur, sur un site public, dans une application mobile ou dans un formulaire d’inscription intégré.

La page est actuellement marquée « beta ». Utilisez la documentation OpenAPI liée comme source pour connaître les points de terminaison, les corps de requête, les paramètres et les schémas de réponse actuellement pris en charge par l’API.

Ouvrir la page Clé API

Ouvrez « Settings », développez « Developers », puis sélectionnez « API key ».

Vous pouvez également ouvrir directement la page à l’adresse suivante :

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

La page contient :

• Un panneau de clé API avec un badge beta.
• Un lien « View OpenAPI docs ».
• Un état vide et un bouton « Create API key » lorsqu’aucune clé n’existe.
• Une représentation masquée de la clé actuelle lorsqu’une clé existe.
• Un bouton « Copy » qui copie la clé complète.
• Les actions « Rotate API key » et « Delete API key » pour remplacer ou supprimer la clé actuelle.

Maildroppa autorise une seule clé API par compte. La page ne crée pas de clés distinctes pour les applications, les environnements ou les membres de l’équipe.

Créer une clé API

Lorsque la page affiche « No API key yet », cliquez sur « Create API key ».

Maildroppa crée immédiatement la clé. Aucune boîte de dialogue de confirmation n’est affichée lors de cette première création. Pendant le traitement de la requête, le bouton devient « Creating API key » et la page désactive temporairement les autres actions liées à la clé.

Une fois la clé créée :

• L’état vide disparaît.
• Une clé masquée apparaît.
• Les actions « Copy », « Rotate API key » et « Delete API key » deviennent disponibles.
• Maildroppa affiche un message de réussite « API key updated ».

Si une autre clé existe déjà pour le compte, Maildroppa n’en crée pas une seconde. Utilisez la clé existante ou faites-la tourner.

Comprendre la clé masquée

La page n’affiche pas le secret complet sous forme de texte ordinaire. Elle montre les cinq premiers caractères suivis de cinq astérisques, par exemple :

a1b2c*****

Il s’agit uniquement d’un masque visuel. Les astérisques ne représentent pas la longueur réelle de la clé, et la valeur masquée ne peut pas être utilisée pour une requête API.

Cliquez sur « Copy » pour copier la clé actuelle complète dans votre presse-papiers. Une fois la copie réussie, le bouton devient brièvement « Copied! ».

La clé reste masquée lorsque vous revenez sur la page, mais « Copy » continue de copier la valeur actuelle complète. Vous n’avez donc pas besoin de faire tourner une clé valide simplement parce que vous ne l’avez pas enregistrée lors de sa création.

Stocker la clé en toute sécurité

Transférez directement la clé copiée dans le stockage de secrets utilisé par l’intégration.

Les emplacements appropriés comprennent :

• Un gestionnaire de secrets administré.
• Une configuration d’environnement protégée du serveur.
• Un secret de déploiement chiffré.
• Un gestionnaire de mots de passe utilisé pour la récupération opérationnelle.

Ne stockez pas la clé dans :

• Du JavaScript côté navigateur ou un autre bundle frontend téléchargeable.
• Un fichier de code source public ou privé enregistré dans un dépôt.
• Une URL ou un paramètre de requête.
• De la documentation publique, des captures d’écran, des messages au support ou des systèmes de suivi des problèmes.
• Des journaux d’application partagés, des événements analytiques ou des rapports d’erreur.
• Une feuille de calcul non chiffrée ou une conversation d’équipe ordinaire.

N’ajoutez pas la clé à un exemple curl qui sera copié dans de la documentation ou dans un historique de shell partagé avec d’autres personnes. Préférez une variable d’environnement telle que MAILDROPPA_API_KEY.

Utiliser la clé API

Envoyez la clé complète dans l’en-tête de requête HTTP X-API-Key :

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

Ne l’envoyez pas comme jeton Bearer. Maildroppa attend X-API-Key, et non Authorization: Bearer ....

L’API de production et sa documentation OpenAPI interactive sont disponibles à l’adresse suivante :

https://api.maildroppa.com

Cliquez sur « View OpenAPI docs » sur la page Clé API pour ouvrir la documentation dans un nouvel onglet du navigateur. Sélectionnez-y un point de terminaison afin d’examiner sa méthode, son chemin, ses paramètres, son corps de requête, son type de réponse et ses codes d’état possibles.

Exemple de requête

L’exemple suivant récupère la première page d’abonnés. Il lit la clé depuis une variable d’environnement au lieu de placer directement le secret dans la commande :

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

Définissez la variable dans l’environnement sécurisé où l’intégration s’exécute. La méthode, le chemin, les paramètres de requête et le corps exacts dépendent du point de terminaison. Copiez ces informations depuis la documentation OpenAPI au lieu de les déduire des actions disponibles dans l’application Maildroppa.

Requêtes avec des corps JSON

Pour une requête qui envoie du JSON, incluez également :

Content-Type: application/json

Par exemple, la structure de base est la suivante :

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 et son corps sont des espaces réservés. Remplacez-les par un point de terminaison documenté et le schéma de requête correspondant.

Ce à quoi la clé peut accéder

La clé ne fonctionne qu’avec les points de terminaison prenant en charge l’authentification par clé API. Une page ou une requête utilisée en interne par l’application Maildroppa ne fait pas automatiquement partie de l’API publique destinée aux clients.

La documentation OpenAPI présente l’API client prise en charge. Si un chemin n’est pas documenté pour une utilisation avec une clé API, ne supposez pas que la clé peut y accéder.

La page Clé API ne propose pas de portées ni de cases à cocher d’autorisation par point de terminaison. La clé actuelle du compte doit donc être traitée comme un identifiant hautement sensible, même si une intégration n’utilise qu’un seul point de terminaison.

Limites de débit

Le contrat OpenAPI actuel documente les limites suivantes pour les clés API :

• API client par défaut : 300 requêtes par minute et 2 000 requêtes par heure.
• API Events à /events : 100 requêtes par seconde, avec une capacité en rafale de 500 requêtes.

Ces limites s’appliquent au compte Maildroppa, et non séparément à chaque script qui partage sa clé. Plusieurs intégrations peuvent donc consommer la même capacité autorisée.

Lorsque Maildroppa renvoie 429 Too Many Requests, cessez d’envoyer de nouvelles requêtes et respectez l’en-tête de réponse Retry-After lorsqu’il est présent. Utilisez une file d’attente et un ralentissement contrôlé au lieu de lancer de nombreuses nouvelles tentatives en parallèle.

Les politiques de limitation de débit peuvent évoluer pendant que l’API est en version beta. Consultez les informations en haut de la documentation OpenAPI avant de concevoir des intégrations à fort volume.

Utiliser la clé pour les requêtes API d’une automatisation

Une automatisation peut démarrer lorsque votre système envoie un événement personnalisé à l’API Events de Maildroppa.

Lorsque vous configurez un déclencheur « API request », Maildroppa utilise la même clé API de compte gérée sur cette page. La configuration du déclencheur peut créer la clé lorsqu’il n’en existe aucune et copier une requête curl préparée contenant la clé complète.

Cela entraîne deux conséquences importantes :

• Faire tourner ou supprimer la clé du compte affecte également les systèmes qui envoient des événements personnalisés aux automatisations.
• Un exemple de requête d’automatisation copié contient le secret dans le presse-papiers, même si la clé est masquée à l’écran.

Avant de faire tourner ou de supprimer la clé, incluez chaque déclencheur de requête API et chaque émetteur d’événements externe dans l’inventaire de vos intégrations.

Réinitialiser ou remplacer la clé API

Utilisez « Rotate API key » lorsque vous devez réinitialiser ou remplacer l’identifiant actuel. Maildroppa crée une nouvelle clé et invalide l’ancienne dans le cadre de la même action.

Utilisez la rotation lorsque :

• La clé a peut-être été exposée.
• Une personne ou un fournisseur qui connaissait la clé n’a plus besoin d’y accéder.
• Votre politique de sécurité exige un remplacement périodique des identifiants.
• Vous souhaitez remplacer une clé stockée dans un emplacement ancien ou non sécurisé.

Cliquez sur « Rotate API key » sous la clé masquée. Maildroppa ouvre une boîte de dialogue d’avertissement expliquant que la clé existante ne sera plus utilisable.

Cliquez sur « Rotate API key » dans la boîte de dialogue pour continuer, ou cliquez sur « Cancel » pour conserver la clé actuelle.

La rotation ne prévoit aucun délai de grâce

Après confirmation de la rotation, l’ancienne clé cesse immédiatement de fonctionner. Maildroppa ne maintient pas simultanément l’ancienne et la nouvelle clé en état de validité.

Comme le compte ne possède qu’une seule clé, la rotation affecte tous les serveurs, tâches planifiées, intégrations, scripts et émetteurs d’événements d’automatisation qui l’utilisent.

Suivez cette séquence pour une rotation planifiée :

1. Listez toutes les intégrations qui utilisent la clé actuelle.
2. Préparez l’accès à la configuration des secrets et au processus de déploiement de chaque intégration.
3. Choisissez une courte fenêtre de maintenance si un accès API ininterrompu est important.
4. Cliquez sur « Rotate API key », puis confirmez l’avertissement avec « Rotate API key » dans la boîte de dialogue.
5. Cliquez sur « Copy » pour copier la nouvelle clé complète.
6. Remplacez immédiatement le secret dans chaque intégration.
7. Redémarrez ou redéployez les services qui ne chargent les secrets qu’au démarrage.
8. Envoyez une requête documentée sans effet afin de vérifier chaque intégration.
9. Recherchez les réponses 401 Unauthorized provenant d’un service oublié qui utilise encore l’ancienne clé.

Si vous pensez que la clé actuelle a été compromise, faites-la tourner immédiatement et acceptez la courte interruption nécessaire à la mise à jour des systèmes légitimes.

Supprimer la clé API

Supprimez la clé lorsque le compte ne doit plus accepter de requêtes authentifiées par clé API.

Cliquez sur « Delete API key » sous la clé masquée. Maildroppa ouvre une boîte de dialogue d’avertissement expliquant que la clé sera définitivement supprimée du compte.

Cliquez sur « Delete API key » dans la boîte de dialogue pour la supprimer, ou cliquez sur « Cancel » pour la conserver.

Après la suppression :

• La clé actuelle cesse immédiatement de fonctionner.
• La page revient à l’état « No API key yet ».
• Les intégrations serveur utilisant la clé supprimée ne peuvent plus s’authentifier.
• Les émetteurs de requêtes API d’automatisation utilisant cette clé ne peuvent plus transmettre d’événements.

La suppression d’une clé ne supprime pas les abonnés, les campagnes, les tags, les champs, les segments, les automatisations ni les autres données du compte. Elle supprime l’identifiant utilisé pour accéder aux points de terminaison API pris en charge.

Vous pouvez cliquer ultérieurement sur « Create API key » pour créer un nouvel identifiant. La valeur supprimée n’est pas restaurée. Chaque intégration doit être mise à jour avant de pouvoir utiliser la nouvelle clé.

Réinitialiser ou supprimer : que choisir ?

Choisissez « Rotate API key » lorsque l’accès à l’API doit continuer avec un nouvel identifiant.

Choisissez la suppression lorsque l’accès à l’API doit être complètement interrompu, au moins pour le moment.

Les deux actions invalident immédiatement la clé actuelle. La rotation crée le remplacement dans le cadre de la même action ; la suppression laisse le compte sans clé.

Recommandations de sécurité

Garder les appels API sur votre serveur

Un navigateur ou une application mobile ne peut pas conserver de manière fiable un secret intégré. Un utilisateur peut inspecter l’application, les en-têtes de requête, les cartes source ou le trafic réseau et extraire la clé.

Si un site ou une application doit déclencher une action, envoyez d’abord la requête à votre propre backend authentifié. Laissez ce backend valider l’utilisateur et appeler Maildroppa avec la clé stockée sur le serveur.

Réduire l’exposition au minimum

Ne fournissez la clé qu’aux systèmes qui en ont besoin. Ne la distribuez pas à tous les développeurs et ne la collez pas dans plusieurs fichiers de configuration locaux.

Comme la page gère actuellement une seule clé à l’échelle du compte plutôt que plusieurs clés nommées ou limitées par portée, utilisez un service d’intégration interne ou un proxy si plusieurs applications ont besoin d’une isolation renforcée les unes par rapport aux autres.

Masquer les en-têtes de requête

Configurez les clients HTTP, les proxys inverses, les outils d’observabilité et les rapports d’erreur pour masquer X-API-Key. Une requête peut fonctionner correctement tout en divulguant son identifiant dans les journaux de débogage.

Séparer les environnements

Ne réutilisez pas une clé de production dans le développement local, les exemples de code, les captures d’écran ou les jeux de tests. Stockez les secrets propres à chaque environnement dans des gestionnaires de secrets propres à cet environnement.

Le lien « View OpenAPI docs » dirige automatiquement les utilisateurs de production vers la documentation de l’API de production. Vérifiez toujours le nom d’hôte avant d’envoyer une véritable clé.

Faire tourner la clé après toute exposition suspectée

Supprimer un message, un commit de dépôt, une ligne de journal ou une capture d’écran ne prouve pas que personne n’a copié la clé. Si la valeur complète a été exposée, faites-la tourner.

Gérer les erreurs API

Utilisez le statut HTTP et le corps de réponse documenté pour déterminer le comportement de l’intégration.

Les cas courants comprennent :

• 400 Bad Request — Le chemin, le paramètre ou le corps JSON ne respecte pas le contrat du point de terminaison. Comparez la requête au schéma OpenAPI.
• 401 Unauthorized — L’en-tête X-API-Key est absent, vide, invalide, supprimé ou contient une ancienne valeur après une rotation.
• 403 Forbidden — La clé authentifiée n’est pas autorisée à utiliser cette opération.
• 404 Not Found — Le chemin ou la ressource référencée n’existe pas dans ce compte.
• 429 Too Many Requests — L’intégration a atteint une limite de débit API. Mettez les requêtes en pause et respectez l’en-tête Retry-After lorsqu’il est présent.
• 5xx — Maildroppa n’a pas pu traiter la requête. Réessayez les opérations sûres avec un ralentissement exponentiel borné et des journaux qui excluent la clé API.

Ne réessayez pas aveuglément après chaque échec. Corrigez les réponses 400, 401, 403 et la plupart des réponses 404 avant de renvoyer la même requête.

Pour les requêtes qui modifient des données, vérifiez le comportement de l’opération en matière de nouvelle tentative et d’idempotence avant de répéter automatiquement une requête. Une défaillance de connexion ne prouve pas toujours que Maildroppa n’a effectué aucune modification.

Dépannage

« Create API key » est toujours visible

Aucune clé n’existe actuellement dans le compte. Cliquez une fois sur le bouton et attendez la fin de la requête.

Si la création échoue, rechargez la page avant de réessayer. Une autre page ou configuration d’automatisation a peut-être déjà créé la clé du compte.

La clé affichée sur la page semble trop courte

La page affiche volontairement uniquement les cinq premiers caractères et *****. Cliquez sur « Copy » pour copier la valeur complète. N’envoyez pas le texte masqué dans une requête.

« Copy » ne devient pas « Copied! »

Le navigateur a peut-être bloqué l’accès au presse-papiers. Gardez la page dans l’onglet actif, autorisez l’accès au presse-papiers si vous y êtes invité, puis cliquez de nouveau sur « Copy ».

N’essayez pas de reconstituer la clé à partir du texte masqué.

Une requête renvoie 401 Unauthorized

Vérifiez que :

• Le nom de l’en-tête est exactement X-API-Key.
• L’en-tête contient la valeur complète, sans les astérisques visibles.
• L’intégration n’envoie pas à la place Authorization: Bearer.
• Aucun espace, guillemet ou retour à la ligne n’a été ajouté au secret.
• Personne n’a fait tourner ou supprimé la clé du compte.
• Un service a été redémarré s’il ne lit les variables d’environnement qu’au démarrage.
• La requête est envoyée vers le bon environnement API Maildroppa.

Une intégration fonctionne, mais une autre s’est arrêtée après la rotation

La seconde intégration utilise probablement encore l’ancienne clé. Il n’y a aucune période de chevauchement. Mettez à jour son secret et redémarrez tout processus qui conserve la configuration en cache.

La page OpenAPI fonctionne, mais un point de terminaison renvoie 403

Tous les points de terminaison de l’application ne prennent pas en charge l’authentification par clé API. Utilisez une opération documentée pour l’API client et vérifiez ses exigences d’authentification sur la page OpenAPI.

Les requêtes renvoient 429 Too Many Requests

Réduisez les rafales de requêtes, placez le travail en file d’attente et réessayez après le délai renvoyé par l’API. Évitez les vagues de nouvelles tentatives parallèles. Si plusieurs applications partagent l’unique clé du compte, coordonnez leur volume de requêtes, car elles partagent les limites API du compte.

Liste de contrôle de configuration recommandée

Avant de mettre une intégration en utilisation régulière, vérifiez que :

• La clé est stockée uniquement dans une configuration de secrets côté serveur.
• Les requêtes utilisent l’en-tête X-API-Key.
• L’intégration utilise https://api.maildroppa.com en production.
• Chaque méthode, chemin, paramètre et corps JSON respecte la documentation OpenAPI.
• Les journaux et les rapports d’erreur masquent la clé.
• Des délais d’expiration et des nouvelles tentatives bornées sont configurés.
• Les erreurs 401, 403, 429 et les erreurs serveur sont surveillées.
• Le responsable de l’intégration est identifié.
• Chaque système qui partage la clé du compte est inclus dans le plan de rotation.
• Une clé compromise peut être remplacée rapidement.

La page Clé API est volontairement simple, mais ses actions affectent toutes les intégrations API connectées au compte. Créez la clé uniquement lorsque cela est nécessaire, conservez-la sur des serveurs de confiance et planifiez la rotation comme une modification d’un identifiant à l’échelle du compte.