API E-mail

API E-mail

Avec l’API E-mail, vous créez, modifiez, désactivez et supprimez automatiquement les boîtes e-mail de votre hébergement. Vous gérez aussi les alias et les redirections. Elle fonctionne sur tous nos serveurs d’hébergement (Linux et Windows) et elle est gratuite.

Étape 1 : activer l’accès API

Connectez-vous à admin.firestorm.ch avec votre identifiant FireStorm et activez Accès API sous Compte => Profil client.

Étape 2 : créer une clé avec le domaine d’accès « E-mail »

Dans le même formulaire, cliquez sur Gérer les clés API. Saisissez une désignation, choisissez le domaine d’accès E-mail (boîtes e-mail) et les hébergements dont la clé peut gérer les boîtes e-mail. Vous pouvez limiter la clé à certains domaines de l’hébergement. Nous recommandons aussi d’indiquer les adresses IP de votre serveur : la clé ne fonctionne alors que depuis celui-ci.

La clé n’est affichée qu’une seule fois. Conservez-la en lieu sûr. Pour chaque nouvelle clé avec accès e-mail, nous vous envoyons une confirmation par e-mail. Si vous n’avez pas créé la clé vous-même, révoquez-la immédiatement dans la même fenêtre.

La clé API principale de l’API DNS n’est volontairement pas valable pour l’API E-mail. Ainsi, une clé DNS perdue n’ouvre jamais vos boîtes e-mail.

Étape 3 : utiliser l’API

Envoyez la clé dans l’en-tête X-API-Key. Les données s’envoient en JSON.

curl -H "X-API-Key: VOTRE_CLE_API" https://api.firestorm.ch/mail/v1/domains

Points de terminaison de l’API

URL de base : https://api.firestorm.ch/mail/v1

Description technique complète sous forme de fichier OpenAPI : firestorm-mail-api.yaml

Exemples

Créer une boîte e-mail

curl -X POST -H "X-API-Key: VOTRE_CLE_API" -H "Content-Type: application/json" \
  -d '{"address":"anna@exemple.ch","password":"Sur-Mdp-2026!","quota_mb":2048,"aliases":["anna.martin"]}' \
  https://api.firestorm.ch/mail/v1/mailboxes

Modifier le mot de passe et l’espace

curl -X PATCH -H "X-API-Key: VOTRE_CLE_API" -H "Content-Type: application/json" \
  -d '{"password":"Nouveau-Mdp-2026!","quota_mb":4096}' \
  https://api.firestorm.ch/mail/v1/mailboxes/anna@exemple.ch

Définir ou désactiver une redirection

La liste remplace toutes les destinations précédentes. Avec "enabled":false et une liste vide, vous désactivez la redirection.

curl -X PATCH -H "X-API-Key: VOTRE_CLE_API" -H "Content-Type: application/json" \
  -d '{"forwarding":{"enabled":true,"addresses":["anna.privee@example.org"]}}' \
  https://api.firestorm.ch/mail/v1/mailboxes/anna@exemple.ch

Ajouter et supprimer un alias

curl -X POST -H "X-API-Key: VOTRE_CLE_API" -H "Content-Type: application/json" \
  -d '{"alias":"ventes"}' https://api.firestorm.ch/mail/v1/mailboxes/anna@exemple.ch/aliases

curl -X DELETE -H "X-API-Key: VOTRE_CLE_API" \
  https://api.firestorm.ch/mail/v1/mailboxes/anna@exemple.ch/aliases/ventes

Désactiver et réactiver

curl -X POST -H "X-API-Key: VOTRE_CLE_API" \
  https://api.firestorm.ch/mail/v1/mailboxes/anna@exemple.ch/disable

curl -X POST -H "X-API-Key: VOTRE_CLE_API" -H "Content-Type: application/json" \
  -d '{"password":"Encore-Mdp-2026!"}' \
  https://api.firestorm.ch/mail/v1/mailboxes/anna@exemple.ch/enable

Supprimer

curl -X DELETE -H "X-API-Key: VOTRE_CLE_API" \
  "https://api.firestorm.ch/mail/v1/mailboxes/anna@exemple.ch?confirm=anna@exemple.ch"

Bon à savoir

• Mots de passe : 10 à 30 caractères, au moins trois parmi minuscules, majuscules, chiffres et caractères spéciaux, sans le nom de la boîte e-mail. L’API ne renvoie jamais de mot de passe.
• Désactiver bloque la connexion (IMAP, POP3, SMTP, webmail). Le contenu est conservé, les nouveaux e-mails continuent d’arriver, les alias et redirections restent actifs. Pour réactiver, vous indiquez un nouveau mot de passe.
• Supprimer efface définitivement la boîte et tous ses e-mails. C’est pourquoi vous devez confirmer l’adresse avec confirm.
• Les limites de votre hébergement (nombre de boîtes, espace) s’appliquent aussi à l’API. Si une limite est atteinte, vous recevez l’erreur limit_reached.
• Service e-mail : si /domains indique "mail_service": false pour un domaine, le service e-mail de ce domaine est désactivé dans la gestion de l’hébergement. Les boîtes e-mail ne fonctionnent alors pas.
• Hébergement Windows : les changements de mot de passe prennent effet en 2 minutes au plus.
• Limites : 120 requêtes par minute et par clé, 100 nouvelles boîtes et 500 modifications par jour et par compte. Après 25 connexions échouées, l’adresse IP est bloquée pendant 6 heures.
• Les erreurs sont renvoyées en JSON : {"status":"error","error":"weak_password","message":"…"}. Dans votre programme, évaluez le code du champ error ; le texte message est destiné aux humains (en allemand).