{"openapi":"3.1.0","info":{"title":"ShazaMail API","version":"2.2.0","description":"L'API REST ShazaMail vous permet de créer et gérer des boîtes email temporaires\npar programmation. Intégrez la messagerie jetable dans vos applications en quelques lignes de code.\n\n**Base URL (production):** `https://api.shazamail.tech`\n**Base URL (sandbox):** `https://sandbox.shazamail.tech`\n\nLes données sandbox sont supprimées toutes les heures.\n","contact":{"name":"Support ShazaMail","email":"support@shazamail.tech","url":"https://shazamail.tech/support"},"license":{"name":"MIT","url":"https://opensource.org/licenses/MIT"}},"servers":[{"url":"https://api.shazamail.tech","description":"Production"},{"url":"https://sandbox.shazamail.tech","description":"Sandbox (données supprimées toutes les heures)"}],"security":[{"ApiKeyAuth":[]}],"tags":[{"name":"inboxes","description":"Créer et gérer les boîtes email temporaires"},{"name":"messages","description":"Lire les messages reçus"},{"name":"webhooks","description":"Configurer des notifications en temps réel"},{"name":"usage","description":"Consulter les quotas et statistiques d'utilisation"},{"name":"domains","description":"Gérer les domaines de messagerie personnalisés"}],"paths":{"/api/v1/inboxes":{"post":{"tags":["inboxes"],"summary":"Créer une boîte temporaire","description":"Crée une nouvelle boîte email jetable. L'adresse générée est aléatoire\net expire après 1 heure par défaut (modifiable via le paramètre `ttl`).\n","operationId":"createInbox","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"ttl":{"type":"integer","description":"Durée de vie en secondes (défaut 3600, max 86400)","default":3600,"minimum":300,"maximum":86400},"domain":{"type":"string","description":"Domaine à utiliser (si vous possédez un domaine personnalisé)","example":"mycompany.com"}}},"example":{"ttl":3600}}}},"responses":{"200":{"description":"Boîte créée avec succès","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Inbox"},"example":{"address":"tmp_x7k2p1@shazamail.tech","domain":"shazamail.tech","created_at":"2026-06-09T14:30:00Z","expires_at":"2026-06-09T15:30:00Z","message_count":0}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/api/v1/inboxes/{address}/messages":{"get":{"tags":["messages"],"summary":"Lister les messages d'une boîte","description":"Retourne la liste des messages reçus dans une boîte temporaire.\nLes messages sont triés par date de réception décroissante.\n","operationId":"listMessages","parameters":[{"name":"address","in":"path","required":true,"description":"Adresse email de la boîte","schema":{"type":"string"},"example":"tmp_x7k2p1@shazamail.tech"},{"name":"limit","in":"query","required":false,"description":"Nombre maximum de messages à retourner (défaut 20, max 100)","schema":{"type":"integer","default":20,"minimum":1,"maximum":100}},{"name":"offset","in":"query","required":false,"description":"Offset pour la pagination","schema":{"type":"integer","default":0}}],"responses":{"200":{"description":"Liste des messages","content":{"application/json":{"schema":{"type":"object","properties":{"messages":{"type":"array","items":{"$ref":"#/components/schemas/Message"}},"total":{"type":"integer"},"has_more":{"type":"boolean"}}},"example":{"messages":[{"id":"msg_abc123","from":"no-reply@paypal.com","from_name":"PayPal","subject":"Reçu de paiement","body_text":"Vous avez envoyé 45,00 EUR à Example Shop.","body_html":"...","received_at":"2026-06-09T14:35:22Z","is_phishing":false,"size_bytes":4821}],"total":1,"has_more":false}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/api/v1/inboxes/{address}":{"delete":{"tags":["inboxes"],"summary":"Supprimer une boîte","description":"Supprime définitivement une boîte temporaire et tous ses messages.","operationId":"deleteInbox","parameters":[{"name":"address","in":"path","required":true,"description":"Adresse email de la boîte à supprimer","schema":{"type":"string"},"example":"tmp_x7k2p1@shazamail.tech"}],"responses":{"200":{"description":"Boîte supprimée avec succès","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"deleted_at":{"type":"string","format":"date-time"}}},"example":{"success":true,"deleted_at":"2026-06-09T14:45:00Z"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/api/v1/webhooks":{"post":{"tags":["webhooks"],"summary":"Créer un webhook","description":"Configure un endpoint pour recevoir des notifications en temps réel\nlorsque des événements se produisent sur vos boîtes email.\n\nLa signature HMAC-SHA256 est envoyée dans le header `X-Shazamail-Signature`.\n","operationId":"createWebhook","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["url","events"],"properties":{"url":{"type":"string","format":"uri","description":"URL HTTPS de votre endpoint webhook","example":"https://api.yourapp.com/webhooks/shazamail"},"events":{"type":"array","description":"Événements à écouter","items":{"type":"string","enum":["inbox.created","message.received","inbox.expired","inbox.deleted","message.phishing_detected"]}},"secret":{"type":"string","description":"Secret HMAC (généré automatiquement si non fourni)"}}},"example":{"url":"https://api.yourapp.com/webhooks/shazamail","events":["message.received","inbox.expired"]}}}},"responses":{"200":{"description":"Webhook créé","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Webhook"},"example":{"id":"wh_7f3k9x","url":"https://api.yourapp.com/webhooks/shazamail","events":["message.received","inbox.expired"],"secret":"whsec_4b3c2a1...","active":true,"created_at":"2026-06-09T14:30:00Z"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/api/v1/usage":{"get":{"tags":["usage"],"summary":"Consulter les quotas d'utilisation","description":"Retourne les statistiques d'utilisation API pour le mois en cours,\nincluant les requêtes consommées et les limites du plan actif.\n","operationId":"getUsage","responses":{"200":{"description":"Statistiques d'utilisation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Usage"},"example":{"plan":"pro","period":"2026-06","requests_used":4823,"requests_limit":10000,"inboxes_active":3,"inboxes_limit":50,"messages_stored":142,"messages_limit":10000,"webhooks_count":2,"webhooks_limit":10,"reset_at":"2026-07-01T00:00:00Z"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/api/v1/domains":{"get":{"tags":["domains"],"summary":"Lister les domaines","description":"Liste tous les domaines de messagerie disponibles pour votre compte.","operationId":"listDomains","responses":{"200":{"description":"Liste des domaines","content":{"application/json":{"schema":{"type":"object","properties":{"domains":{"type":"array","items":{"$ref":"#/components/schemas/Domain"}}}},"example":{"domains":[{"domain":"shazamail.tech","type":"principal","status":"ok","users":4821,"rep":98},{"domain":"mycompany.com","type":"custom","status":"ok","users":3,"rep":100}]}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"500":{"$ref":"#/components/responses/ServerError"}}},"post":{"tags":["domains"],"summary":"Ajouter un domaine personnalisé","description":"Ajoute un domaine personnalisé à votre compte.\nVous devez configurer les enregistrements DNS MX, SPF et DKIM avant validation.\n","operationId":"addDomain","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["domain"],"properties":{"domain":{"type":"string","description":"Nom de domaine à ajouter","example":"mycompany.com"}}},"example":{"domain":"mycompany.com"}}}},"responses":{"200":{"description":"Domaine ajouté, en attente de vérification DNS","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Domain"},"example":{"domain":"mycompany.com","type":"custom","status":"pending","users":0,"rep":100,"dns_records":{"mx":"10 mx.shazamail.tech.","spf":"v=spf1 include:_spf.shazamail.tech ~all","dkim":"v=DKIM1; k=rsa; p=MIGfMA... (généré)"}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"500":{"$ref":"#/components/responses/ServerError"}}}}},"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-Api-Key","description":"Clé API obtenue depuis votre Dashboard → Clés API → Créer.\nFormat : `sk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxx`\n"}},"schemas":{"Inbox":{"type":"object","required":["address","domain","created_at","expires_at","message_count"],"properties":{"address":{"type":"string","description":"Adresse email complète de la boîte","example":"tmp_x7k2p1@shazamail.tech"},"domain":{"type":"string","description":"Domaine de l'adresse","example":"shazamail.tech"},"created_at":{"type":"string","format":"date-time","description":"Date de création ISO 8601"},"expires_at":{"type":"string","format":"date-time","description":"Date d'expiration ISO 8601"},"message_count":{"type":"integer","description":"Nombre de messages reçus","default":0}}},"Message":{"type":"object","required":["id","from","subject","received_at"],"properties":{"id":{"type":"string","description":"Identifiant unique du message","example":"msg_abc123"},"from":{"type":"string","description":"Adresse email de l'expéditeur","example":"no-reply@paypal.com"},"from_name":{"type":"string","description":"Nom de l'expéditeur","example":"PayPal"},"subject":{"type":"string","description":"Objet du message","example":"Reçu de paiement"},"body_text":{"type":"string","description":"Corps du message en texte brut"},"body_html":{"type":"string","description":"Corps du message en HTML"},"received_at":{"type":"string","format":"date-time","description":"Date et heure de réception"},"is_phishing":{"type":"boolean","description":"Indique si un risque de phishing a été détecté","default":false},"size_bytes":{"type":"integer","description":"Taille du message en octets"}}},"Webhook":{"type":"object","required":["id","url","events","active","created_at"],"properties":{"id":{"type":"string","description":"Identifiant unique du webhook","example":"wh_7f3k9x"},"url":{"type":"string","format":"uri","description":"URL de l'endpoint webhook"},"events":{"type":"array","items":{"type":"string"},"description":"Événements surveillés"},"secret":{"type":"string","description":"Secret pour vérification HMAC-SHA256 (affiché une seule fois)"},"active":{"type":"boolean","description":"Statut du webhook"},"created_at":{"type":"string","format":"date-time"}}},"Usage":{"type":"object","properties":{"plan":{"type":"string","enum":["free","pro","enterprise"],"description":"Plan actif"},"period":{"type":"string","description":"Période de facturation (YYYY-MM)","example":"2026-06"},"requests_used":{"type":"integer","description":"Requêtes API consommées ce mois"},"requests_limit":{"type":"integer","description":"Limite de requêtes du plan (-1 = illimité)"},"inboxes_active":{"type":"integer","description":"Boîtes actives actuellement"},"inboxes_limit":{"type":"integer","description":"Limite de boîtes actives (-1 = illimité)"},"messages_stored":{"type":"integer","description":"Messages stockés actuellement"},"messages_limit":{"type":"integer","description":"Limite de messages stockés (-1 = illimité)"},"webhooks_count":{"type":"integer"},"webhooks_limit":{"type":"integer"},"reset_at":{"type":"string","format":"date-time","description":"Date de remise à zéro des compteurs"}}},"Domain":{"type":"object","required":["domain","type","status"],"properties":{"domain":{"type":"string","example":"shazamail.tech"},"type":{"type":"string","enum":["principal","custom"]},"status":{"type":"string","enum":["ok","pending","warning"]},"users":{"type":"integer","description":"Nombre d'utilisateurs sur ce domaine"},"rep":{"type":"integer","description":"Score de réputation (0-100)"},"dns_records":{"type":"object","description":"Enregistrements DNS requis (uniquement lors de l'ajout)"}}},"Error":{"type":"object","required":["error","code","message"],"properties":{"error":{"type":"boolean","default":true},"code":{"type":"string","description":"Code d'erreur machine","example":"UNAUTHORIZED"},"message":{"type":"string","description":"Message d'erreur lisible","example":"Clé API manquante ou invalide."}}}},"responses":{"BadRequest":{"description":"Paramètre manquant ou invalide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":true,"code":"BAD_REQUEST","message":"Le champ 'url' est requis."}}}},"Unauthorized":{"description":"Clé API absente ou invalide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":true,"code":"UNAUTHORIZED","message":"Clé API manquante. Ajoutez le header X-Api-Key."}}}},"Forbidden":{"description":"Quota dépassé ou plan insuffisant","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":true,"code":"FORBIDDEN","message":"Quota mensuel dépassé. Passez au plan Pro."}}}},"NotFound":{"description":"Ressource introuvable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":true,"code":"NOT_FOUND","message":"La boîte email spécifiée n'existe pas ou a expiré."}}}},"RateLimited":{"description":"Limite de requêtes atteinte","headers":{"Retry-After":{"description":"Nombre de secondes avant de pouvoir réessayer","schema":{"type":"integer"}},"X-RateLimit-Limit":{"schema":{"type":"integer"}},"X-RateLimit-Remaining":{"schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Timestamp Unix de remise à zéro","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":true,"code":"RATE_LIMITED","message":"Limite atteinte. Réessayez dans 60 secondes."}}}},"ServerError":{"description":"Erreur interne du serveur","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":true,"code":"SERVER_ERROR","message":"Une erreur interne s'est produite. Contactez support@shazamail.tech."}}}}}}}