Documentation API

API GPTMail

Utilisez l'API GPTMail pour générer des boîtes de réception temporaires, lister et lire les messages et supprimer des emails via HTTPS avec un en-tête X-API-Key. Elle convient aux tests automatisés, aux pipelines CI/CD et aux workflows QA.

Comment obtenir une API Key

Buy API requests

Purchase API requests with GPTMail points. Earn points through daily check-ins and public domains, or buy points with LDC at a 1:1 rate.

Buy with points / add requests

Option 2 : ajouter votre propre domaine

Après validation MX d'un domaine public : soumis sans connexion → clé API (20000 requêtes) ; soumis en étant connecté → 200 points. Chaque domaine reçoit une seule récompense. Important : une fois connecté, ce suffixe de domaine devient un suffixe public pour tous les utilisateurs du site, qui peuvent aussi créer des adresses sous celui-ci. Après activation, ne supprimez, ne remplacez ni ne modifiez l’enregistrement MX qui pointe ce domaine vers notre service. Sinon, des vérifications ultérieures pourront considérer le domaine comme mal configuré. Si une vérification ultérieure juge le MX invalide, le domaine sera désactivé. Si le MX reste invalide pendant 3 vérifications consécutives, l’API Key associée sera aussi désactivée. Si le MX redevient valide plus tard, le domaine sera réactivé automatiquement.

Domaines

Clé de test publique

Pour vos tests, envoyez la clé publique partagée affichée ci-dessous dans l'en-tête X-API-Key. Elle change chaque jour et dispose d'une limite quotidienne de 200 000 requêtes partagée entre tous les utilisateurs.

Restant aujourd’hui

Réinitialisation dans

Chargement du quota en direct de la clé publique…

La référence API ci-dessous peut être copiée en Markdown pour des outils d’IA, des bases de connaissances ou un README.

URL de base: https://mail.chatgpt.org.uk

AI
llms.txt

·

llms-full.txt

(Markdown)

Démarrage rapide

  • X-API-Key: YOUR_KEY est l'option la plus simple. Pour des tests rapides, utilisez la clé publique quotidienne affichée ci-dessus à la place de YOUR_KEY.

  • La plupart des points d’accès boîte mail exigent un paramètre email, par exemple ?email=demo@example.com.

  • Les réponses de l'API GPTMail utilisent le format JSON avec les champs success, data et error, ainsi que usage lorsqu'une clé API est utilisée. Les erreurs de Cloudflare, y compris les réponses de limitation de débit, peuvent renvoyer du HTML. Vérifiez le code d'état HTTP et le Content-Type avant d'analyser le JSON.

  • Si vous connaissez déjà un domaine actuellement pris en charge sur ce site, inutile d’appeler d’abord le point de génération d’email. Composez prefix@domain localement et appelez directement les API de boîte mail, ce qui évite une requête.

Limites de débit et nouvelles tentatives

  • GET et POST /api/generate-email partagent une limite de 30 requêtes toutes les 10 secondes par adresse IP source. Elle s'applique aux clés API publiques comme personnelles. Les différentes clés et différents clients situés derrière la même IP partagent cette limite.

  • Le dépassement de cette limite renvoie une erreur HTTP 429 et bloque la génération d'adresses pendant 10 secondes. Attendez la durée indiquée par Retry-After avant de réessayer. Si cet en-tête est absent, attendez au moins 10 secondes, puis réessayez avec des délais croissants. Évitez les nouvelles tentatives simultanées depuis des clients qui partagent une même IP.

  • Cette règle ne s'applique ni à l'affichage de la liste des messages d'une boîte ni à la lecture d'un email. Les quotas quotidiens et totaux des clés API continuent de s'appliquer séparément. Attendre 10 secondes ne rétablit pas le quota épuisé d'une clé.

Points d’accès principaux

POST / GET
/api/generate-email

Génère une boîte de réception temporaire. Utilisez GET pour le flux aléatoire le plus simple, ou POST avec prefix et domain pour un contrôle explicite.

GET
/api/emails?email=...

Récupère les messages d’une boîte mail.

GET
/api/email/{id}?email=...

Récupère un seul message, avec texte, HTML, en-têtes bruts et métadonnées.

DELETE
/api/email/{id}?email=...

Supprime un message par son ID.

DELETE
/api/emails/clear?email=...

Supprime tous les messages d’une boîte mail.

GET
/api/stats

Lit les statistiques à l’échelle du site.

Exemple de flux

Deux schémas courants : laisser le service générer une boîte de réception, ou demander un préfixe fixe. Si vous connaissez déjà un domaine actuellement pris en charge, vous pouvez aussi composer l’adresse localement et l’interroger directement.

1) Générer une adresse e-mail temporaire aléatoire

curl 'https://mail.chatgpt.org.uk/api/generate-email' \
  -H 'X-API-Key: PUBLIC_API_KEY'
Exemple de réponse
{
  "success": true,
  "data": {
    "email": "a3f9c2b1@example.com"
  },
  "usage": {
    "daily_limit": 200000,
    "used_today": 1,
    "remaining_today": 199999,
    "total_limit": 200000,
    "total_usage": 1,
    "remaining_total": 199999
  }
}

2) Générer avec un préfixe fixe (ex. demo@example.com)

curl -X POST 'https://mail.chatgpt.org.uk/api/generate-email' \
  -H 'Content-Type: application/json' \
  -H 'X-API-Key: PUBLIC_API_KEY' \
  -d '{"prefix":"demo"}'
Exemple de réponse
{
  "success": true,
  "data": {
    "email": "demo@example.com"
  },
  "usage": {
    "daily_limit": 200000,
    "used_today": 2,
    "remaining_today": 199998
  }
}

3) Lister les messages d’une boîte de réception

Si vous connaissez déjà un domaine pris en charge, sautez l’étape 1 et interrogez directement.

curl 'https://mail.chatgpt.org.uk/api/emails?email=demo@example.com' \
  -H 'X-API-Key: PUBLIC_API_KEY'
Exemple de réponse
{
  "success": true,
  "data": {
    "emails": [
      {
        "id": "e5a7f3...",
        "email_address": "demo@example.com",
        "from_address": "noreply@github.com",
        "subject": "Your code: 654321",
        "content": "Your verification code is 654321",
        "html_content": "...",
        "has_html": true,
        "timestamp": 1709654321,
        "created_at": "2024-03-05T12:18:41Z"
      }
    ],
    "count": 1
  }
}

4) Lire un seul message — texte brut, corps HTML et métadonnées

Remplacez EMAIL_ID par un id renvoyé à l'étape 3. Transmettez aussi l'adresse de la boîte comme email (y compris pour les suppressions et les téléchargements de pièces jointes) : l'email est alors lu directement dans sa boîte au lieu d'être recherché par ID. Avec une clé API, le paramètre email est facultatif, mais l'envoyer accélère la recherche.

curl 'https://mail.chatgpt.org.uk/api/email/EMAIL_ID?email=demo@example.com' \
  -H 'X-API-Key: PUBLIC_API_KEY'
Exemple de réponse
{
  "success": true,
  "data": {
    "id": "e5a7f3...",
    "email_address": "demo@example.com",
    "from_address": "noreply@github.com",
    "subject": "Your code: 654321",
    "content": "Your verification code is 654321",
    "html_content": "<p>Your code is 654321</p>",
    "has_html": true,
    "timestamp": 1709654321,
    "raw_size": 2048,
    "created_at": "2024-03-05T12:18:41Z"
  }
}

5) Supprimer un message par ID

Avec une clé API, le paramètre email est facultatif, mais l'envoyer accélère la recherche.

curl -X DELETE 'https://mail.chatgpt.org.uk/api/email/EMAIL_ID?email=demo@example.com' \
  -H 'X-API-Key: PUBLIC_API_KEY'
Exemple de réponse
{
  "success": true,
  "data": {
    "message": "Email deleted"
  }
}

6) Vider toute la boîte — supprime tous les messages pour cette adresse

Chaque appel supprime un lot. Tant que la réponse contient "has_more": true, rappelez-le jusqu'à ce qu'il renvoie false.

curl -X DELETE 'https://mail.chatgpt.org.uk/api/emails/clear?email=demo@example.com' \
  -H 'X-API-Key: PUBLIC_API_KEY'
Exemple de réponse
{
  "success": true,
  "data": {
    "message": "Deleted 3 emails",
    "count": 3,
    "has_more": false
  }
}

Forme de la réponse

Les réponses réussies ressemblent en général à ceci. Avec une API Key, regardez les infos de quota dans usage.

{
  "success": true,
  "data": {
    "email": "demo@example.com"
  },
  "usage": {
    "daily_limit": 200000,
    "used_today": 1,
    "remaining_today": 199999,
    "total_limit": 200000,
    "total_usage": 1,
    "remaining_total": 199999
  }
}

Statistiques étendues

  • /api/statistics/24h renvoie une fenêtre de répartition horaire de 24 heures ; utilisez offset=1,2,... pour les fenêtres plus anciennes.
  • /api/statistics/top-subjects renvoie les objets d'email les plus fréquents.
  • /api/statistics/top-domains renvoie les domaines les plus actifs.
  • /api/statistics/top-senders renvoie les expéditeurs les plus actifs.
GPTMail