Documentazione dell'API

API GPTMail

Usa l'API di GPTMail per generare caselle di posta temporanee, elencare e leggere i messaggi ed eliminare la posta tramite HTTPS con l'intestazione X-API-Key. È ideale per test automatizzati, pipeline CI/CD e flussi di lavoro QA.

Come ottenere una 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

Opzione 2: Aggiungi il tuo dominio

Dopo la verifica MX di un dominio pubblico: inviato senza accesso → chiave API (20000 richieste); inviato dopo l'accesso → 200 punti. Ogni dominio riceve una sola ricompensa. Importante: una volta collegato, quel suffisso di dominio diventa un suffisso pubblico per tutti gli utenti del sito, così altri possono generare indirizzi di casella sotto di esso. Dopo l’attivazione, non eliminare, sostituire o modificare il record MX che punta questo dominio al nostro servizio. Altrimenti controlli successivi potrebbero considerare il dominio mal configurato. Se un controllo successivo rileva il MX non valido, il dominio verrà disattivato. Se il MX resta non valido per 3 controlli consecutivi, anche la API Key associata verrà disattivata. Se il MX torna valido in seguito, il dominio verrà riattivato automaticamente.

Domini

Chiave pubblica di test

Per i test, invia la chiave pubblica condivisa mostrata qui sotto nell'intestazione X-API-Key. Cambia ogni giorno e ha un limite giornaliero di 200.000 richieste condiviso da tutti gli utenti.

Rimanente oggi

Si azzera tra

Caricamento quota in tempo reale della chiave pubblica…

Il riferimento API qui sotto può essere copiato come Markdown per strumenti IA, knowledge base o un README.

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

AI
llms.txt

·

llms-full.txt

(Markdown)

Avvio rapido

  • X-API-Key: YOUR_KEY è l'opzione più semplice. Per test rapidi, usa la chiave pubblica giornaliera mostrata sopra al posto di YOUR_KEY.

  • La maggior parte degli endpoint della casella richiede il parametro email, ad esempio ?email=demo@example.com.

  • Le risposte dell'API GPTMail usano JSON con i campi success, data ed error, più usage quando si usa una chiave API. Gli errori di Cloudflare, comprese le risposte per limite di frequenza superato, possono invece restituire HTML. Controlla lo stato HTTP e il Content-Type prima di analizzare il JSON.

  • Se conosci già un dominio attualmente supportato su questo sito, non devi prima chiamare l’endpoint di generazione email. Puoi comporre prefix@domain in locale e chiamare direttamente le API della casella, risparmiando una richiesta.

Limiti di frequenza e nuovi tentativi

  • GET e POST /api/generate-email condividono un limite di 30 richieste ogni 10 secondi per IP di origine. Vale sia per le chiavi API pubbliche sia per quelle personali. Chiavi e client diversi dietro lo stesso IP condividono questo limite.

  • Il superamento di questo limite restituisce HTTP 429 e blocca la generazione di indirizzi per 10 secondi. Attendi la durata indicata da Retry-After prima di riprovare. Se l'header manca, attendi almeno 10 secondi, poi riprova con attese crescenti. Evita nuovi tentativi simultanei da client che condividono lo stesso IP.

  • Questa regola non si applica all'elenco dei messaggi di una casella né alla lettura di singole email. Le quote giornaliere e totali delle chiavi API continuano ad applicarsi separatamente. Attendere 10 secondi non ripristina la quota esaurita di una chiave.

Endpoint principali

POST / GET
/api/generate-email

Genera una casella temporanea. Usa GET per il flusso casuale più semplice, oppure POST con prefix e domain quando vuoi un controllo esplicito.

GET
/api/emails?email=...

Recupera le email di una casella.

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

Recupera una singola email, inclusi testo, HTML, intestazioni grezze e metadati.

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

Elimina un’email per ID.

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

Elimina tutte le email in una casella.

GET
/api/stats

Legge le statistiche dell’intero sito.

Flusso di esempio

Due schemi comuni: lasciare che il servizio generi una casella o richiedere un prefisso fisso. Se conosci già un dominio attualmente supportato, puoi anche comporre la casella in locale e interrogarla direttamente.

1) Generare un indirizzo email temporaneo casuale

curl 'https://mail.chatgpt.org.uk/api/generate-email' \
  -H 'X-API-Key: PUBLIC_API_KEY'
Esempio di risposta
{
  "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) Generare con prefisso fisso (es. 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"}'
Esempio di risposta
{
  "success": true,
  "data": {
    "email": "demo@example.com"
  },
  "usage": {
    "daily_limit": 200000,
    "used_today": 2,
    "remaining_today": 199998
  }
}

3) Elencare le email in una casella

Se conosci già un dominio supportato, salta il passo 1 e interroga direttamente.

curl 'https://mail.chatgpt.org.uk/api/emails?email=demo@example.com' \
  -H 'X-API-Key: PUBLIC_API_KEY'
Esempio di risposta
{
  "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) Leggere una singola email — include testo normale, corpo HTML e metadati

Sostituisci EMAIL_ID con un id restituito al passo 3. Passa anche l'indirizzo della casella come email (anche per eliminazioni e download degli allegati): l'email viene così letta direttamente dalla sua casella invece di essere cercata per ID. Con una chiave API il parametro email è facoltativo, ma inviarlo rende la ricerca più veloce.

curl 'https://mail.chatgpt.org.uk/api/email/EMAIL_ID?email=demo@example.com' \
  -H 'X-API-Key: PUBLIC_API_KEY'
Esempio di risposta
{
  "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) Eliminare una singola email per ID

Con una chiave API il parametro email è facoltativo, ma inviarlo rende la ricerca più veloce.

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

6) Svuotare l’intera casella — elimina tutte le email per questo indirizzo

Ogni chiamata elimina un blocco. Finché la risposta contiene "has_more": true, richiamala finché non restituisce false.

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

Struttura della risposta

Le risposte di successo di solito hanno questa forma. Se ti autentichi con una API Key, controlla le informazioni sulla quota in 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
  }
}

Statistiche estese

  • /api/statistics/24h restituisce una finestra di distribuzione oraria di 24 ore; usa offset=1,2,... per le finestre precedenti.
  • /api/statistics/top-subjects restituisce gli oggetti email più frequenti.
  • /api/statistics/top-domains restituisce i domini più attivi.
  • /api/statistics/top-senders restituisce i mittenti più attivi.
GPTMail