Checklist di setup rapido
- Apri la pagina API Management del tuo dashboard e crea la tua chiave API personale.
- Copia l'URL di base dell'API utente esatto mostrato lì, ad esempio https://v1.tempmailg.com/api.
- Invia ogni richiesta a quell'host API con Authorization: Bearer YOUR_USER_API_KEY e Accept: application/json.
- Monitora la tua quota mensile di richieste dalla stessa pagina del cruscotto e dalle intestazioni della quota quando disponibili nelle risposte API dell'utente. Solo le richieste 2xx riuscite contano ai fini della quota.
Flusso di autenticazione
- Generare la chiave API personale dalla pagina di gestione dell'API del cruscotto.
- Inviare la chiave come token Bearer in ogni richiesta.
- Utilizzare l'URL di base dell'API dell'utente dedicato mostrato nella pagina di gestione dell'API.
- Rigenerare la chiave ogni volta che si desidera annullare la vecchia e iniziare a utilizzare una nuova chiave immediatamente.
Header obbligatori
Authorization: Bearer YOUR_USER_API_KEY
Accept: application/json
Intestazioni di Limite di Velocità e Quota
Le intestazioni di limitazione della velocità descrivono il budget di richieste indicato. Le intestazioni di quota sono incluse quando le informazioni sulla quota sono disponibili; i rifiuti per limite al minuto non calcolano la tua quota mensile completa.
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 45
X-RateLimit-Reset: 1729520000
X-Quota-Limit: 50000
X-Quota-Remaining: 48210
X-Quota-Used: 1790
X-Quota-Reset: 2026-11-01T00:00:00+00:00
X-RateLimit-Scope: account
Retry-After: 42 (when a timed retry is available)
X-RateLimit-Limit— Richieste massime consentite al minuto (RPM) per il tuo piano.X-RateLimit-Remaining— Richieste RPM rimanenti nella finestra corrente di un minuto.X-RateLimit-Reset— Timestamp Unix quando la finestra di limitazione del tasso per il minuto corrente si resetta.X-Quota-Limit— Capacità totale mensile e di credito acquistato per il tuo account.X-Quota-Remaining— Richieste API disponibili rimanenti nel mese corrente.X-Quota-Used— Totale richieste API consumate durante il periodo di fatturazione corrente.X-Quota-Reset— Timestamp ISO-8601 quando la tua quota mensile si resetta.X-RateLimit-Scope— Il budget descritto dalle intestazioni: account, ip, status_endpoint o mailbox.X-Mailbox-RateLimit-*— Budget separato per la creazione/aggiornamento della casella di posta. Le risposte di casella di posta riuscite mantengono l'RPM dell'account in X-RateLimit-*; un rifiuto solo per la casella di posta utilizza l'ambito della casella e la sua finestra di ritentativo.Retry-After— Secondi prima che un nuovo tentativo temporizzato sia appropriato. Un piano disabilitato o una quota esaurita potrebbero richiedere invece un cambio di account, quindi questa intestazione non è sempre presente.503 protection_unavailable— L'archiviazione o il coordinamento della protezione API non è temporaneamente disponibile. Riprova più tardi; questo non è un fallimento di pagamento o un addebito di credito.
Gestione della casella di posta
Recupera i domini consentiti, crea o cambia cassette postali, scegli le durate consentite e elimina gli indirizzi posseduti.
Elenco dei domini consentiti
Elenca i domini disponibili per creare email temporanee. Filtra per tipo per vedere solo i domini gratuiti, premium o personalizzati supportati dal tuo piano di abbonamento.
| Parametro | Posizione | Tipo | Stato | Descrizione |
|---|---|---|---|---|
type
|
query | string | opzionale |
Filtro livello dominio. L'omissione utilizza tutti quando l'accesso premium-domain è abilitato, altrimenti gratuito. Valori riconosciuti: free, basic, pro, premium, custom, ultimate, all
Predefinito:
Dipendente dall'account
|
const response = await fetch('https://v1.tempmailg.com/api/domains?type=free', {
method: 'GET',
headers: {
'Authorization': 'Bearer YOUR_USER_API_KEY',
'Accept': 'application/json',
},
});
if (!response.ok) {
throw new Error(`Request failed with status ${response.status}`);
}
const data = await response.json();
console.log(data);
import requests
headers = {
'Authorization': 'Bearer YOUR_USER_API_KEY',
'Accept': 'application/json',
}
response = requests.get('https://v1.tempmailg.com/api/domains?type=free', headers=headers, timeout=30)
response.raise_for_status()
print(response.json())
<?php
$ch = curl_init('https://v1.tempmailg.com/api/domains?type=free');
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'GET',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'Authorization: Bearer YOUR_USER_API_KEY',
'Accept: application/json',
],
]);
$response = curl_exec($ch);
if ($response === false) {
throw new RuntimeException(curl_error($ch));
}
$statusCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);
var_dump($statusCode, json_decode($response, true));
curl --request GET \
--url 'https://v1.tempmailg.com/api/domains?type=free' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer YOUR_USER_API_KEY'
Risposta illustrativa usando dati sintetici. ID, indirizzi, token, timestamp, limiti e conteggi del piano variano. Le durate di esempio non sovrascrivono il valore predefinito del tuo piano. Le descrizioni dei campi di risposta identificano i campi nullable e specifici del provider.
Esempio di risposta
200 OK • JSON{
"status": true,
"data": {
"requested_type": "free",
"plan": "pro",
"plan_name": "Pro Plan",
"allowed_types": [
"free",
"basic",
"pro",
"premium",
"custom",
"ultimate",
"all"
],
"domains": [
{
"domain": "example.com",
"type": "Free",
"custom": false
}
]
}
}
| Campo | Tipo | Descrizione |
|---|---|---|
status |
boolean | Se l'operazione è riuscita. |
data.requested_type |
string | Filtro di dominio applicato. |
data.plan |
string | Tag del piano corrente. |
data.plan_name |
string | Nome leggibile del piano corrente. |
data.allowed_types |
array<string> | Filtri di dominio disponibili per questo account. Un filtro riconosciuto può comunque essere vietato per il tuo piano. |
data.domains |
array | Domini selezionabili dopo il filtraggio; un array vuoto è valido. |
data.domains[].domain |
string | Nome di dominio selezionabile. |
data.domains[].type |
string | Etichetta del livello di dominio leggibile. |
data.domains[].custom |
boolean | Se questo è un dominio personalizzato. |
Crea casella di posta temporanea
Crea una casella di posta temporanea di proprietà. Ometti nome utente e dominio per generazione casuale, oppure fornisci un nome utente personalizzato consentito e un dominio consentito. Il parametro provider può selezionare la generazione di alias Gmail o Outlook.
| Parametro | Posizione | Tipo | Stato | Descrizione |
|---|---|---|---|---|
username
|
body | string | opzionale |
Nome utente personalizzato opzionale: da 2 a 64 caratteri ASCII, lettere, cifre, punti, underscore o trattini. Richiede l'autorizzazione del piano; è accettato anche custom_username.
Predefinito:
Generato casualmente
|
domain
|
body | string | opzionale |
Uno dei domini consentiti restituiti da GET /domains. L'omissione sceglie un dominio consentito casuale.
Predefinito:
Dominio consentito casuale
|
lifetime
|
body | string | opzionale |
valori consentiti:
10m — 10 minuti
1h — 1 Ora
2h — 2 ore
1d — 1 giorno
1w — 1 Settimana
1m — 30 Giorni
3m — 90 giorni
6m — 180 giorni
1y — 365 giorni
unlimited — Illimitato
Predefinito:
Durata predefinita del piano
|
provider
|
body | string | opzionale |
Provider della casella di posta: standard, gmail_alias, o outlook_alias.
Predefinito:
standard
|
pin_enabled
|
body | boolean | opzionale |
Protezione PIN opzionale per la nuova casella di posta, quando consentita dal tuo piano. Non modifica il PIN di una casella di posta esistente.
Predefinito:
false
|
pin
|
body | string | opzionale |
Obbligatorio quando pin_enabled è true: un PIN di 6 a 8 cifre, inviato come stringa per preservare gli zero iniziali.
|
pin_confirmation
|
body | string | opzionale |
Obbligatorio quando pin_enabled è true. Deve corrispondere esattamente al pin.
|
Idempotency-Key
|
header | string | opzionale |
Richiesto per la creazione o eliminazione protetta da PIN: una chiave stabile da 16 a 128 caratteri. Riprova la stessa richiesta con la stessa chiave per evitare lavoro duplicato.
|
username (nome utente personalizzato se consentito dal piano), domain (dominio consentito, es. example.com), lifetime (valori consentiti: 10m, 1h, 2h, 1d, 1w, 1m, 3m, 6m, 1y, unlimited), provider (standard, gmail_alias, outlook_alias). Ometti la durata, o lasciala vuota, per utilizzare la Durata Email Predefinita configurata per il tuo attuale piano mensile/annuale. Invia una durata consentita, ad esempio 1h, per sovrascrivere tale impostazione predefinita. Illimitato è usato solo quando configurato come impostazione predefinita del piano o richiesto esplicitamente e consentito. Anche i parametri del corpo mailbox_lifetime e email_lifetime sono accettati; il primo valore non vuoto vince in questo ordine: lifetime, mailbox_lifetime, email_lifetime. I valori non validi o non consentiti restituiscono HTTP 422 invece di selezionare silenziosamente un valore predefinito.const response = await fetch('https://v1.tempmailg.com/api/emails', {
method: 'POST',
headers: {
'Authorization': 'Bearer YOUR_USER_API_KEY',
'Accept': 'application/json',
},
});
if (!response.ok) {
throw new Error(`Request failed with status ${response.status}`);
}
const data = await response.json();
console.log(data);
import requests
headers = {
'Authorization': 'Bearer YOUR_USER_API_KEY',
'Accept': 'application/json',
}
response = requests.post('https://v1.tempmailg.com/api/emails', headers=headers, timeout=30)
response.raise_for_status()
print(response.json())
<?php
$ch = curl_init('https://v1.tempmailg.com/api/emails');
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'POST',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'Authorization: Bearer YOUR_USER_API_KEY',
'Accept: application/json',
],
]);
$response = curl_exec($ch);
if ($response === false) {
throw new RuntimeException(curl_error($ch));
}
$statusCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);
var_dump($statusCode, json_decode($response, true));
curl --request POST \
--url 'https://v1.tempmailg.com/api/emails' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer YOUR_USER_API_KEY'
Risposta illustrativa usando dati sintetici. ID, indirizzi, token, timestamp, limiti e conteggi del piano variano. Le durate di esempio non sovrascrivono il valore predefinito del tuo piano. Le descrizioni dei campi di risposta identificano i campi nullable e specifici del provider.
Esempio di risposta
200 OK • JSON{
"status": true,
"data": {
"id": 2301,
"pin_protected": false,
"email": "demo123@example.com",
"domain": "example.com",
"provider": "standard",
"expire_at": "2026-11-20T02:17:48+00:00",
"expires_in_seconds": 86399.75,
"mailbox_state": "active",
"receiving_enabled": true,
"message_count": 0,
"unread_message_count": 0,
"last_message_received_at": null,
"message_count_synced_at": null,
"created_at": "2026-11-19T02:17:48+00:00",
"email_token": "encrypted-email-token"
}
}
| Campo | Tipo | Descrizione |
|---|---|---|
status |
boolean | Se l'operazione è riuscita. |
data.id |
integer | ID della casella di posta. Gli ID, gli indirizzi e i token generati differiscono per ogni casella. |
data.pin_protected |
boolean | Indica se questa casella di posta ha protezione PIN. Nessun PIN o hash PIN viene restituito. |
data.email |
string | Generato indirizzo completo della casella di posta. |
data.domain |
string | Dominio della casella di posta generata. |
data.provider |
string | Provider della casella di posta: standard, gmail_alias, o outlook_alias. |
data.expire_at |
string|null | Scadenza effettiva come timestamp ISO-8601, o null per una casella di posta illimitata. |
data.expires_in_seconds |
number|null | Secondi rimanenti non negativi al calcolo; i secondi frazionari sono possibili. Null significa illimitato, non zero. |
data.mailbox_state |
string | Stato attuale della casella di posta: attiva, in pausa, scaduta o inattiva. |
data.receiving_enabled |
boolean | Indica se questa casella di posta accetta attualmente messaggi in arrivo. |
data.message_count |
integer | Conteggio totale dei messaggi noto; può riflettere l'ultima sincronizzazione della casella di posta. |
data.unread_message_count |
integer | Conteggio dei messaggi non letti conosciuti; può riflettere l'ultima sincronizzazione della casella di posta. |
data.last_message_received_at |
string|null | Ultimo orario noto del messaggio ricevuto in formato ISO-8601, o null se non disponibile. |
data.message_count_synced_at |
string|null | Ultimo orario di sincronizzazione del conteggio dei messaggi in formato ISO-8601, o null prima della sincronizzazione. |
data.created_at |
string|null | Ora di creazione della casella di posta in formato ISO-8601. |
data.email_token |
string | Riferimento di casella di posta crittografata opaco. Non sostituisce l'autenticazione Bearer, i controlli di proprietà o l'autorizzazione PIN. |
data.pin_grant |
object | Condizionale: la creazione di caselle di posta protette da PIN attivo restituisce questo permesso di lettura; la creazione ordinaria non protetta lo omette. |
data.pin_grant.mailbox_id |
integer | ID della casella di posta a cui è associata l'autorizzazione di lettura condizionale. |
data.pin_grant.unlock_token |
string | Token di lettura opaco per X-Mailbox-Unlock con le stesse credenziali del proprietario. Mantenerlo privato e in memoria; un permesso di lettura non autorizza l'eliminazione. |
data.pin_grant.scope |
string | L'ambito letto per la concessione di creazione condizionale. |
data.pin_grant.idle_timeout_seconds |
integer | Tempo di inattività consentito per il permesso di lettura, normalmente 3600 secondi. |
data.pin_grant.absolute_timeout_seconds |
integer | Durata massima del permesso di lettura, normalmente 86400 secondi. |
data.pin_grant.expires_at |
string | Scadenza attuale del permesso di lettura in formato ISO-8601. |
data.pin_grant.absolute_expires_at |
string | Scadenza assoluta del permesso di lettura in formato ISO-8601. Le modifiche di sicurezza possono revocare il permesso in anticipo. |
Aggiorna / Cambia casella di posta
Crea o seleziona una casella di posta con il nuovo nome utente e dominio dopo aver verificato la proprietà della casella di posta attuale. Questo non rinomina la vecchia casella di posta né ne modifica la durata. Quando la destinazione è diversa, la vecella casella di posta rimane nella cronologia e può essere sospesa dai limiti di caselle attive. Riutilizzare la tua stessa destinazione attiva riapplica la durata richiesta o il valore predefinito del piano.
| Parametro | Posizione | Tipo | Stato | Descrizione |
|---|---|---|---|---|
email
|
path | string | obbligatorio |
Indirizzo email completo attuale della casella di posta posseduta da cambiare. Codifica URL di ogni segmento del percorso; codifica un segno più come %2B.
|
username
|
path | string | obbligatorio |
Nuovo nome utente desiderato: da 2 a 64 caratteri alfanumerici; soggetto a permesso di nome utente personalizzato.
|
domain
|
path | string | obbligatorio |
Nuovo nome di dominio consentito.
|
lifetime
|
body | string | opzionale |
valori consentiti:
10m — 10 minuti
1h — 1 Ora
2h — 2 ore
1d — 1 giorno
1w — 1 Settimana
1m — 30 Giorni
3m — 90 giorni
6m — 180 giorni
1y — 365 giorni
unlimited — Illimitato
Predefinito:
Durata predefinita del piano
|
pin_enabled
|
body | boolean | opzionale |
Protezione PIN opzionale per la nuova casella di posta, quando consentita dal tuo piano. Non modifica il PIN di una casella di posta esistente.
Predefinito:
false
|
pin
|
body | string | opzionale |
Obbligatorio quando pin_enabled è true: un PIN di 6 a 8 cifre, inviato come stringa per preservare gli zero iniziali.
|
pin_confirmation
|
body | string | opzionale |
Obbligatorio quando pin_enabled è true. Deve corrispondere esattamente al pin.
|
Idempotency-Key
|
header | string | opzionale |
Richiesto per la creazione o eliminazione protetta da PIN: una chiave stabile da 16 a 128 caratteri. Riprova la stessa richiesta con la stessa chiave per evitare lavoro duplicato.
|
X-Mailbox-Unlock
|
header | string | opzionale |
Intestazione, solo caselle di posta protette: usa un unlock_token di lettura. Prima invia un POST con pin e scope=read all'URL di sblocco PIN. Mantieni la tua normale autenticazione Bearer. <code>https://v1.tempmailg.com/api/mailboxes/{mailbox}/pin/unlock</code>
|
lifetime (valori consentiti: 10m, 1h, 2h, 1d, 1w, 1m, 3m, 6m, 1y, unlimited). Ometti la durata, o lasciala vuota, per utilizzare la Durata Email Predefinita configurata per il tuo attuale piano mensile/annuale. Invia una durata consentita, ad esempio 1h, per sovrascrivere tale impostazione predefinita. Illimitato è usato solo quando configurato come impostazione predefinita del piano o richiesto esplicitamente e consentito. Anche i parametri del corpo mailbox_lifetime e email_lifetime sono accettati; il primo valore non vuoto vince in questo ordine: lifetime, mailbox_lifetime, email_lifetime. I valori non validi o non consentiti restituiscono HTTP 422 invece di selezionare silenziosamente un valore predefinito.const response = await fetch('https://v1.tempmailg.com/api/emails/current@example.com/demo123/example.com', {
method: 'POST',
headers: {
'Authorization': 'Bearer YOUR_USER_API_KEY',
'Accept': 'application/json',
},
});
if (!response.ok) {
throw new Error(`Request failed with status ${response.status}`);
}
const data = await response.json();
console.log(data);
import requests
headers = {
'Authorization': 'Bearer YOUR_USER_API_KEY',
'Accept': 'application/json',
}
response = requests.post('https://v1.tempmailg.com/api/emails/current@example.com/demo123/example.com', headers=headers, timeout=30)
response.raise_for_status()
print(response.json())
<?php
$ch = curl_init('https://v1.tempmailg.com/api/emails/current@example.com/demo123/example.com');
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'POST',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'Authorization: Bearer YOUR_USER_API_KEY',
'Accept: application/json',
],
]);
$response = curl_exec($ch);
if ($response === false) {
throw new RuntimeException(curl_error($ch));
}
$statusCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);
var_dump($statusCode, json_decode($response, true));
curl --request POST \
--url 'https://v1.tempmailg.com/api/emails/current@example.com/demo123/example.com' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer YOUR_USER_API_KEY'
Risposta illustrativa usando dati sintetici. ID, indirizzi, token, timestamp, limiti e conteggi del piano variano. Le durate di esempio non sovrascrivono il valore predefinito del tuo piano. Le descrizioni dei campi di risposta identificano i campi nullable e specifici del provider.
Esempio di risposta
200 OK • JSON{
"status": true,
"data": {
"id": 2302,
"pin_protected": false,
"email": "demo123@example.com",
"domain": "example.com",
"provider": "standard",
"expire_at": "2026-11-19T02:27:48+00:00",
"expires_in_seconds": 599.75,
"mailbox_state": "active",
"receiving_enabled": true,
"message_count": 0,
"unread_message_count": 0,
"last_message_received_at": null,
"message_count_synced_at": null,
"created_at": "2026-11-19T02:17:48+00:00",
"email_token": "encrypted-email-token"
}
}
| Campo | Tipo | Descrizione |
|---|---|---|
status |
boolean | Se l'operazione è riuscita. |
data.id |
integer | ID della casella di posta. Gli ID, gli indirizzi e i token generati differiscono per ogni casella. |
data.pin_protected |
boolean | Indica se questa casella di posta ha protezione PIN. Nessun PIN o hash PIN viene restituito. |
data.email |
string | Generato indirizzo completo della casella di posta. |
data.domain |
string | Dominio della casella di posta generata. |
data.provider |
string | Provider della casella di posta: standard, gmail_alias, o outlook_alias. |
data.expire_at |
string|null | Scadenza effettiva come timestamp ISO-8601, o null per una casella di posta illimitata. |
data.expires_in_seconds |
number|null | Secondi rimanenti non negativi al calcolo; i secondi frazionari sono possibili. Null significa illimitato, non zero. |
data.mailbox_state |
string | Stato attuale della casella di posta: attiva, in pausa, scaduta o inattiva. |
data.receiving_enabled |
boolean | Indica se questa casella di posta accetta attualmente messaggi in arrivo. |
data.message_count |
integer | Conteggio totale dei messaggi noto; può riflettere l'ultima sincronizzazione della casella di posta. |
data.unread_message_count |
integer | Conteggio dei messaggi non letti conosciuti; può riflettere l'ultima sincronizzazione della casella di posta. |
data.last_message_received_at |
string|null | Ultimo orario noto del messaggio ricevuto in formato ISO-8601, o null se non disponibile. |
data.message_count_synced_at |
string|null | Ultimo orario di sincronizzazione del conteggio dei messaggi in formato ISO-8601, o null prima della sincronizzazione. |
data.created_at |
string|null | Ora di creazione della casella di posta in formato ISO-8601. |
data.email_token |
string | Riferimento di casella di posta crittografata opaco. Non sostituisce l'autenticazione Bearer, i controlli di proprietà o l'autorizzazione PIN. |
data.pin_grant |
object | Condizionale: la creazione di caselle di posta protette da PIN attivo restituisce questo permesso di lettura; la creazione ordinaria non protetta lo omette. |
data.pin_grant.mailbox_id |
integer | ID della casella di posta a cui è associata l'autorizzazione di lettura condizionale. |
data.pin_grant.unlock_token |
string | Token di lettura opaco per X-Mailbox-Unlock con le stesse credenziali del proprietario. Mantenerlo privato e in memoria; un permesso di lettura non autorizza l'eliminazione. |
data.pin_grant.scope |
string | L'ambito letto per la concessione di creazione condizionale. |
data.pin_grant.idle_timeout_seconds |
integer | Tempo di inattività consentito per il permesso di lettura, normalmente 3600 secondi. |
data.pin_grant.absolute_timeout_seconds |
integer | Durata massima del permesso di lettura, normalmente 86400 secondi. |
data.pin_grant.expires_at |
string | Scadenza attuale del permesso di lettura in formato ISO-8601. |
data.pin_grant.absolute_expires_at |
string | Scadenza assoluta del permesso di lettura in formato ISO-8601. Le modifiche di sicurezza possono revocare il permesso in anticipo. |
Elimina casella di posta
Elimina una casella di posta posseduta e avvia la pulizia dei messaggi e dei file. I record della casella di posta conservati possono essere eliminati in modo soft internamente; l'indirizzo non è più utilizzabile tramite l'API.
| Parametro | Posizione | Tipo | Stato | Descrizione |
|---|---|---|---|---|
email
|
path | string | obbligatorio |
Indirizzo email completo della casella di posta posseduta da eliminare. Codifica l'indirizzo in URL; codifica il segno più come %2B.
|
X-Mailbox-Unlock
|
header | string | opzionale |
Intestazione, solo cassette postali protette: usa il token di sblocco per eliminazione monouso. Prima invia un POST pin, scope=delete e l'action/target_id restituiti dalla risposta 423 all'URL di sblocco PIN. Un token di lettura non può eliminare. <code>https://v1.tempmailg.com/api/mailboxes/{mailbox}/pin/unlock</code>
|
Idempotency-Key
|
header | string | opzionale |
Richiesto per la creazione o eliminazione protetta da PIN: una chiave stabile da 16 a 128 caratteri. Riprova la stessa richiesta con la stessa chiave per evitare lavoro duplicato.
|
const response = await fetch('https://v1.tempmailg.com/api/emails/demo123@example.com', {
method: 'DELETE',
headers: {
'Authorization': 'Bearer YOUR_USER_API_KEY',
'Accept': 'application/json',
},
});
if (!response.ok) {
throw new Error(`Request failed with status ${response.status}`);
}
const data = await response.json();
console.log(data);
import requests
headers = {
'Authorization': 'Bearer YOUR_USER_API_KEY',
'Accept': 'application/json',
}
response = requests.delete('https://v1.tempmailg.com/api/emails/demo123@example.com', headers=headers, timeout=30)
response.raise_for_status()
print(response.json())
<?php
$ch = curl_init('https://v1.tempmailg.com/api/emails/demo123@example.com');
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'DELETE',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'Authorization: Bearer YOUR_USER_API_KEY',
'Accept: application/json',
],
]);
$response = curl_exec($ch);
if ($response === false) {
throw new RuntimeException(curl_error($ch));
}
$statusCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);
var_dump($statusCode, json_decode($response, true));
curl --request DELETE \
--url 'https://v1.tempmailg.com/api/emails/demo123@example.com' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer YOUR_USER_API_KEY'
Risposta illustrativa usando dati sintetici. ID, indirizzi, token, timestamp, limiti e conteggi del piano variano. Le durate di esempio non sovrascrivono il valore predefinito del tuo piano. Le descrizioni dei campi di risposta identificano i campi nullable e specifici del provider.
Esempio di risposta
200 OK • JSON{
"status": true,
"message": "Email has been successfully deleted."
}
| Campo | Tipo | Descrizione |
|---|---|---|
status |
boolean | Se l'operazione è riuscita. |
message |
string | Risultato dell'eliminazione. Una risorsa mancante restituisce HTTP 404. |
Alias Gmail e Outlook
Genera caselle di posta alias Gmail e Outlook/Hotmail ad alta reputazione.
Crea alias Gmail
Crea una nuova casella di posta temporanea alias Gmail di proprietà dell'utente autenticato.
| Parametro | Posizione | Tipo | Stato | Descrizione |
|---|---|---|---|---|
mode
|
body | string | opzionale |
Modalità di generazione: auto, dot, plus o plus_dot. Accetta anche gmail_alias_mode. Se la selezione dello stile non è consentita, viene utilizzata auto.
Predefinito:
auto
|
username
|
body | string | opzionale |
Suffisso alias personalizzato opzionale: da 2 a 32 caratteri ASCII (lettere o cifre), normalizzato in minuscolo; soggetto a permesso della funzionalità. Accetta anche custom_username o alias_username.
Predefinito:
Generato automaticamente
|
domain
|
body | string | opzionale |
Usa random, gmail.com o googlemail.com; alias_domain è anche accettato. L'omissione o l'assenza di permesso di selezione del dominio utilizza random.
Predefinito:
random
|
lifetime
|
body | string | opzionale |
valori consentiti:
10m — 10 minuti
1h — 1 Ora
2h — 2 ore
1d — 1 giorno
1w — 1 Settimana
1m — 30 Giorni
3m — 90 giorni
6m — 180 giorni
1y — 365 giorni
unlimited — Illimitato
Predefinito:
Durata predefinita del piano
|
pin_enabled
|
body | boolean | opzionale |
Protezione PIN opzionale per la nuova casella di posta, quando consentita dal tuo piano. Non modifica il PIN di una casella di posta esistente.
Predefinito:
false
|
pin
|
body | string | opzionale |
Obbligatorio quando pin_enabled è true: un PIN di 6 a 8 cifre, inviato come stringa per preservare gli zero iniziali.
|
pin_confirmation
|
body | string | opzionale |
Obbligatorio quando pin_enabled è true. Deve corrispondere esattamente al pin.
|
Idempotency-Key
|
header | string | opzionale |
Richiesto per la creazione o eliminazione protetta da PIN: una chiave stabile da 16 a 128 caratteri. Riprova la stessa richiesta con la stessa chiave per evitare lavoro duplicato.
|
mode (auto, dot, plus, plus_dot), username (nome utente alias personalizzato), domain (es. gmail.com, googlemail.com), lifetime (valori consentiti: 10m, 1h, 2h, 1d, 1w, 1m, 3m, 6m, 1y, unlimited). Ometti la durata, o lasciala vuota, per utilizzare la Durata Email Predefinita configurata per il tuo attuale piano mensile/annuale. Invia una durata consentita, ad esempio 1h, per sovrascrivere tale impostazione predefinita. Illimitato è usato solo quando configurato come impostazione predefinita del piano o richiesto esplicitamente e consentito. Anche i parametri del corpo mailbox_lifetime e email_lifetime sono accettati; il primo valore non vuoto vince in questo ordine: lifetime, mailbox_lifetime, email_lifetime. I valori non validi o non consentiti restituiscono HTTP 422 invece di selezionare silenziosamente un valore predefinito.const response = await fetch('https://v1.tempmailg.com/api/gmail-alias/emails', {
method: 'POST',
headers: {
'Authorization': 'Bearer YOUR_USER_API_KEY',
'Accept': 'application/json',
},
});
if (!response.ok) {
throw new Error(`Request failed with status ${response.status}`);
}
const data = await response.json();
console.log(data);
import requests
headers = {
'Authorization': 'Bearer YOUR_USER_API_KEY',
'Accept': 'application/json',
}
response = requests.post('https://v1.tempmailg.com/api/gmail-alias/emails', headers=headers, timeout=30)
response.raise_for_status()
print(response.json())
<?php
$ch = curl_init('https://v1.tempmailg.com/api/gmail-alias/emails');
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'POST',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'Authorization: Bearer YOUR_USER_API_KEY',
'Accept: application/json',
],
]);
$response = curl_exec($ch);
if ($response === false) {
throw new RuntimeException(curl_error($ch));
}
$statusCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);
var_dump($statusCode, json_decode($response, true));
curl --request POST \
--url 'https://v1.tempmailg.com/api/gmail-alias/emails' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer YOUR_USER_API_KEY'
Risposta illustrativa usando dati sintetici. ID, indirizzi, token, timestamp, limiti e conteggi del piano variano. Le durate di esempio non sovrascrivono il valore predefinito del tuo piano. Le descrizioni dei campi di risposta identificano i campi nullable e specifici del provider.
Esempio di risposta
200 OK • JSON{
"status": true,
"data": {
"id": 2305,
"pin_protected": false,
"email": "example+alias123@gmail.com",
"domain": "gmail.com",
"provider": "gmail_alias",
"expire_at": "2026-11-19T03:17:48+00:00",
"expires_in_seconds": 3599.75,
"mailbox_state": "active",
"receiving_enabled": true,
"message_count": 0,
"unread_message_count": 0,
"last_message_received_at": null,
"message_count_synced_at": null,
"created_at": "2026-11-19T02:17:48+00:00",
"email_token": "encrypted-email-token"
}
}
| Campo | Tipo | Descrizione |
|---|---|---|
status |
boolean | Se l'operazione è riuscita. |
data.id |
integer | ID della casella di posta. Gli ID, gli indirizzi e i token generati differiscono per ogni casella. |
data.pin_protected |
boolean | Indica se questa casella di posta ha protezione PIN. Nessun PIN o hash PIN viene restituito. |
data.email |
string | Generato indirizzo completo della casella di posta. |
data.domain |
string | Dominio della casella di posta generata. |
data.provider |
string | Provider della casella di posta: standard, gmail_alias, o outlook_alias. |
data.expire_at |
string|null | Scadenza effettiva come timestamp ISO-8601, o null per una casella di posta illimitata. |
data.expires_in_seconds |
number|null | Secondi rimanenti non negativi al calcolo; i secondi frazionari sono possibili. Null significa illimitato, non zero. |
data.mailbox_state |
string | Stato attuale della casella di posta: attiva, in pausa, scaduta o inattiva. |
data.receiving_enabled |
boolean | Indica se questa casella di posta accetta attualmente messaggi in arrivo. |
data.message_count |
integer | Conteggio totale dei messaggi noto; può riflettere l'ultima sincronizzazione della casella di posta. |
data.unread_message_count |
integer | Conteggio dei messaggi non letti conosciuti; può riflettere l'ultima sincronizzazione della casella di posta. |
data.last_message_received_at |
string|null | Ultimo orario noto del messaggio ricevuto in formato ISO-8601, o null se non disponibile. |
data.message_count_synced_at |
string|null | Ultimo orario di sincronizzazione del conteggio dei messaggi in formato ISO-8601, o null prima della sincronizzazione. |
data.created_at |
string|null | Ora di creazione della casella di posta in formato ISO-8601. |
data.email_token |
string | Riferimento di casella di posta crittografata opaco. Non sostituisce l'autenticazione Bearer, i controlli di proprietà o l'autorizzazione PIN. |
data.pin_grant |
object | Condizionale: la creazione di caselle di posta protette da PIN attivo restituisce questo permesso di lettura; la creazione ordinaria non protetta lo omette. |
data.pin_grant.mailbox_id |
integer | ID della casella di posta a cui è associata l'autorizzazione di lettura condizionale. |
data.pin_grant.unlock_token |
string | Token di lettura opaco per X-Mailbox-Unlock con le stesse credenziali del proprietario. Mantenerlo privato e in memoria; un permesso di lettura non autorizza l'eliminazione. |
data.pin_grant.scope |
string | L'ambito letto per la concessione di creazione condizionale. |
data.pin_grant.idle_timeout_seconds |
integer | Tempo di inattività consentito per il permesso di lettura, normalmente 3600 secondi. |
data.pin_grant.absolute_timeout_seconds |
integer | Durata massima del permesso di lettura, normalmente 86400 secondi. |
data.pin_grant.expires_at |
string | Scadenza attuale del permesso di lettura in formato ISO-8601. |
data.pin_grant.absolute_expires_at |
string | Scadenza assoluta del permesso di lettura in formato ISO-8601. Le modifiche di sicurezza possono revocare il permesso in anticipo. |
Domini alias Outlook
Recupera i domini alias attivi di Outlook / Hotmail disponibili per la generazione della casella di posta.
const response = await fetch('https://v1.tempmailg.com/api/outlook-alias/domains', {
method: 'GET',
headers: {
'Authorization': 'Bearer YOUR_USER_API_KEY',
'Accept': 'application/json',
},
});
if (!response.ok) {
throw new Error(`Request failed with status ${response.status}`);
}
const data = await response.json();
console.log(data);
import requests
headers = {
'Authorization': 'Bearer YOUR_USER_API_KEY',
'Accept': 'application/json',
}
response = requests.get('https://v1.tempmailg.com/api/outlook-alias/domains', headers=headers, timeout=30)
response.raise_for_status()
print(response.json())
<?php
$ch = curl_init('https://v1.tempmailg.com/api/outlook-alias/domains');
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'GET',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'Authorization: Bearer YOUR_USER_API_KEY',
'Accept: application/json',
],
]);
$response = curl_exec($ch);
if ($response === false) {
throw new RuntimeException(curl_error($ch));
}
$statusCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);
var_dump($statusCode, json_decode($response, true));
curl --request GET \
--url 'https://v1.tempmailg.com/api/outlook-alias/domains' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer YOUR_USER_API_KEY'
Risposta illustrativa usando dati sintetici. ID, indirizzi, token, timestamp, limiti e conteggi del piano variano. Le durate di esempio non sovrascrivono il valore predefinito del tuo piano. Le descrizioni dei campi di risposta identificano i campi nullable e specifici del provider.
Esempio di risposta
200 OK • JSON{
"status": true,
"data": {
"domains": [
{
"domain": "outlook.com",
"type": "Outlook/Hotmail",
"selectable": true,
"locked": false,
"disabled_reason": null
},
{
"domain": "hotmail.com",
"type": "Outlook/Hotmail",
"selectable": true,
"locked": false,
"disabled_reason": null
}
]
}
}
| Campo | Tipo | Descrizione |
|---|---|---|
status |
boolean | Se l'operazione è riuscita. |
data.domains |
array | Domini Outlook/Hotmail attivi; un array vuoto è valido. |
data.domains[].domain |
string | Nome di dominio disponibile. |
data.domains[].type |
string | Etichetta leggibile del provider. |
data.domains[].selectable |
boolean | Se il tuo account può scegliere esplicitamente questo dominio. |
data.domains[].locked |
boolean | Se la selezione esplicita del dominio è bloccata per il tuo account. |
data.domains[].disabled_reason |
string|null | Motivo per cui la selezione del dominio è bloccata, o null quando selezionabile. |
Crea alias Outlook
Crea una nuova casella di posta temporanea alias Outlook / Hotmail di proprietà dell'utente autenticato.
| Parametro | Posizione | Tipo | Stato | Descrizione |
|---|---|---|---|---|
domain
|
body | string | opzionale |
Usa un dominio casuale o un dominio da GET /outlook-alias/domains; outlook_alias_domain è anche accettato. Senza permesso di selezione, viene usato quello casuale.
Predefinito:
Dominio disponibile casuale
|
username
|
body | string | opzionale |
Suffisso alias personalizzato opzionale: da 2 a 32 caratteri ASCII (lettere o cifre), normalizzato in minuscolo; soggetto a permesso della funzionalità. Accetta anche custom_username o alias_username.
Predefinito:
Generato automaticamente
|
lifetime
|
body | string | opzionale |
valori consentiti:
10m — 10 minuti
1h — 1 Ora
2h — 2 ore
1d — 1 giorno
1w — 1 Settimana
1m — 30 Giorni
3m — 90 giorni
6m — 180 giorni
1y — 365 giorni
unlimited — Illimitato
Predefinito:
Durata predefinita del piano
|
pin_enabled
|
body | boolean | opzionale |
Protezione PIN opzionale per la nuova casella di posta, quando consentita dal tuo piano. Non modifica il PIN di una casella di posta esistente.
Predefinito:
false
|
pin
|
body | string | opzionale |
Obbligatorio quando pin_enabled è true: un PIN di 6 a 8 cifre, inviato come stringa per preservare gli zero iniziali.
|
pin_confirmation
|
body | string | opzionale |
Obbligatorio quando pin_enabled è true. Deve corrispondere esattamente al pin.
|
Idempotency-Key
|
header | string | opzionale |
Richiesto per la creazione o eliminazione protetta da PIN: una chiave stabile da 16 a 128 caratteri. Riprova la stessa richiesta con la stessa chiave per evitare lavoro duplicato.
|
domain (es. outlook.com, hotmail.com), username (nome utente alias personalizzato), lifetime (valori consentiti: 10m, 1h, 2h, 1d, 1w, 1m, 3m, 6m, 1y, unlimited). Ometti la durata, o lasciala vuota, per utilizzare la Durata Email Predefinita configurata per il tuo attuale piano mensile/annuale. Invia una durata consentita, ad esempio 1h, per sovrascrivere tale impostazione predefinita. Illimitato è usato solo quando configurato come impostazione predefinita del piano o richiesto esplicitamente e consentito. Anche i parametri del corpo mailbox_lifetime e email_lifetime sono accettati; il primo valore non vuoto vince in questo ordine: lifetime, mailbox_lifetime, email_lifetime. I valori non validi o non consentiti restituiscono HTTP 422 invece di selezionare silenziosamente un valore predefinito.const response = await fetch('https://v1.tempmailg.com/api/outlook-alias/emails', {
method: 'POST',
headers: {
'Authorization': 'Bearer YOUR_USER_API_KEY',
'Accept': 'application/json',
},
});
if (!response.ok) {
throw new Error(`Request failed with status ${response.status}`);
}
const data = await response.json();
console.log(data);
import requests
headers = {
'Authorization': 'Bearer YOUR_USER_API_KEY',
'Accept': 'application/json',
}
response = requests.post('https://v1.tempmailg.com/api/outlook-alias/emails', headers=headers, timeout=30)
response.raise_for_status()
print(response.json())
<?php
$ch = curl_init('https://v1.tempmailg.com/api/outlook-alias/emails');
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'POST',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'Authorization: Bearer YOUR_USER_API_KEY',
'Accept: application/json',
],
]);
$response = curl_exec($ch);
if ($response === false) {
throw new RuntimeException(curl_error($ch));
}
$statusCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);
var_dump($statusCode, json_decode($response, true));
curl --request POST \
--url 'https://v1.tempmailg.com/api/outlook-alias/emails' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer YOUR_USER_API_KEY'
Risposta illustrativa usando dati sintetici. ID, indirizzi, token, timestamp, limiti e conteggi del piano variano. Le durate di esempio non sovrascrivono il valore predefinito del tuo piano. Le descrizioni dei campi di risposta identificano i campi nullable e specifici del provider.
Esempio di risposta
200 OK • JSON{
"status": true,
"data": {
"id": 2306,
"pin_protected": false,
"email": "example+alias45@outlook.com",
"domain": "outlook.com",
"provider": "outlook_alias",
"expire_at": "2026-11-19T03:17:48+00:00",
"expires_in_seconds": 3599.75,
"mailbox_state": "active",
"receiving_enabled": true,
"message_count": 0,
"unread_message_count": 0,
"last_message_received_at": null,
"message_count_synced_at": null,
"created_at": "2026-11-19T02:17:48+00:00",
"email_token": "encrypted-email-token"
}
}
| Campo | Tipo | Descrizione |
|---|---|---|
status |
boolean | Se l'operazione è riuscita. |
data.id |
integer | ID della casella di posta. Gli ID, gli indirizzi e i token generati differiscono per ogni casella. |
data.pin_protected |
boolean | Indica se questa casella di posta ha protezione PIN. Nessun PIN o hash PIN viene restituito. |
data.email |
string | Generato indirizzo completo della casella di posta. |
data.domain |
string | Dominio della casella di posta generata. |
data.provider |
string | Provider della casella di posta: standard, gmail_alias, o outlook_alias. |
data.expire_at |
string|null | Scadenza effettiva come timestamp ISO-8601, o null per una casella di posta illimitata. |
data.expires_in_seconds |
number|null | Secondi rimanenti non negativi al calcolo; i secondi frazionari sono possibili. Null significa illimitato, non zero. |
data.mailbox_state |
string | Stato attuale della casella di posta: attiva, in pausa, scaduta o inattiva. |
data.receiving_enabled |
boolean | Indica se questa casella di posta accetta attualmente messaggi in arrivo. |
data.message_count |
integer | Conteggio totale dei messaggi noto; può riflettere l'ultima sincronizzazione della casella di posta. |
data.unread_message_count |
integer | Conteggio dei messaggi non letti conosciuti; può riflettere l'ultima sincronizzazione della casella di posta. |
data.last_message_received_at |
string|null | Ultimo orario noto del messaggio ricevuto in formato ISO-8601, o null se non disponibile. |
data.message_count_synced_at |
string|null | Ultimo orario di sincronizzazione del conteggio dei messaggi in formato ISO-8601, o null prima della sincronizzazione. |
data.created_at |
string|null | Ora di creazione della casella di posta in formato ISO-8601. |
data.email_token |
string | Riferimento di casella di posta crittografata opaco. Non sostituisce l'autenticazione Bearer, i controlli di proprietà o l'autorizzazione PIN. |
data.pin_grant |
object | Condizionale: la creazione di caselle di posta protette da PIN attivo restituisce questo permesso di lettura; la creazione ordinaria non protetta lo omette. |
data.pin_grant.mailbox_id |
integer | ID della casella di posta a cui è associata l'autorizzazione di lettura condizionale. |
data.pin_grant.unlock_token |
string | Token di lettura opaco per X-Mailbox-Unlock con le stesse credenziali del proprietario. Mantenerlo privato e in memoria; un permesso di lettura non autorizza l'eliminazione. |
data.pin_grant.scope |
string | L'ambito letto per la concessione di creazione condizionale. |
data.pin_grant.idle_timeout_seconds |
integer | Tempo di inattività consentito per il permesso di lettura, normalmente 3600 secondi. |
data.pin_grant.absolute_timeout_seconds |
integer | Durata massima del permesso di lettura, normalmente 86400 secondi. |
data.pin_grant.expires_at |
string | Scadenza attuale del permesso di lettura in formato ISO-8601. |
data.pin_grant.absolute_expires_at |
string | Scadenza assoluta del permesso di lettura in formato ISO-8601. Le modifiche di sicurezza possono revocare il permesso in anticipo. |
Messaggi e Allegati
Recupera le caselle in arrivo, leggi i messaggi HTML/testo completi e trasmetti gli allegati.
Elenca i messaggi della casella di posta
Recupera i riepiloghi dei messaggi disponibili e i metadati della casella di posta. Le scansioni standard della posta in arrivo restituiscono un lotto recente di fino a 25 messaggi; questo non è un endpoint paginato con cronologia completa. Usa GET /messages/{messageId} per i corpi completi e gli allegati.
| Parametro | Posizione | Tipo | Stato | Descrizione |
|---|---|---|---|---|
email
|
query | string | obbligatorio |
Indirizzo email completo della casella di posta posseduta da cui leggere i messaggi. Codifica URL del valore della query; codifica un segno più come %2B.
|
X-Mailbox-Unlock
|
header | string | opzionale |
Intestazione, solo caselle di posta protette: usa un unlock_token di lettura. Prima invia un POST con pin e scope=read all'URL di sblocco PIN. Mantieni la tua normale autenticazione Bearer. <code>https://v1.tempmailg.com/api/mailboxes/{mailbox}/pin/unlock</code>
|
const response = await fetch('https://v1.tempmailg.com/api/messages?email=demo123@example.com', {
method: 'GET',
headers: {
'Authorization': 'Bearer YOUR_USER_API_KEY',
'Accept': 'application/json',
},
});
if (!response.ok) {
throw new Error(`Request failed with status ${response.status}`);
}
const data = await response.json();
console.log(data);
import requests
headers = {
'Authorization': 'Bearer YOUR_USER_API_KEY',
'Accept': 'application/json',
}
response = requests.get('https://v1.tempmailg.com/api/messages?email=demo123@example.com', headers=headers, timeout=30)
response.raise_for_status()
print(response.json())
<?php
$ch = curl_init('https://v1.tempmailg.com/api/messages?email=demo123@example.com');
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'GET',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'Authorization: Bearer YOUR_USER_API_KEY',
'Accept: application/json',
],
]);
$response = curl_exec($ch);
if ($response === false) {
throw new RuntimeException(curl_error($ch));
}
$statusCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);
var_dump($statusCode, json_decode($response, true));
curl --request GET \
--url 'https://v1.tempmailg.com/api/messages?email=demo123@example.com' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer YOUR_USER_API_KEY'
Risposta illustrativa usando dati sintetici. ID, indirizzi, token, timestamp, limiti e conteggi del piano variano. Le durate di esempio non sovrascrivono il valore predefinito del tuo piano. Le descrizioni dei campi di risposta identificano i campi nullable e specifici del provider.
Esempio di risposta
200 OK • JSON{
"status": true,
"mailbox": "demo123@example.com",
"email_token": "encrypted-email-token",
"messages": [
{
"is_seen": false,
"subject": "Welcome to Temp Mail",
"from": "Example Sender",
"from_email": "hello@example.org",
"receivedAt": "2026-11-19 02:17:48",
"id": "ap94AWDg123ELQz07vrVB9dLXlbqZM5NGwYxOJKko8n6m1",
"otp": null,
"otp_locked": false,
"verification_link": null,
"verification_link_locked": false
}
],
"mailbox_provider": "standard",
"mailbox_state": "active",
"expire_at": "2026-11-20T02:17:48+00:00",
"expires_in_seconds": 86399.75,
"receiving_enabled": true,
"mailbox_limit": {
"limit": 50,
"limit_label": "50",
"active_count": 1,
"paused_count": 0,
"paused_mailboxes": [],
"remaining": 49,
"remaining_label": "49",
"reached": false,
"blocked": false,
"provider": "standard"
},
"message_count": 1,
"unread_message_count": 1,
"last_message_received_at": "2026-11-19T02:17:48+00:00",
"message_count_synced_at": "2026-11-19T02:17:48+00:00"
}
| Campo | Tipo | Descrizione |
|---|---|---|
status |
boolean | Se l'operazione è riuscita. |
mailbox |
string | Indirizzo della casella di posta i cui messaggi sono stati richiesti. |
email_token |
string | Riferimento di casella di posta crittografata opaco; è comunque necessaria l'autenticazione normale. |
mailbox_provider |
string | Provider della casella di posta: standard, gmail_alias, o outlook_alias. |
messages |
array | Riepiloghi dei messaggi. Una casella di posta vuota restituisce un array vuoto; recupera un singolo messaggio per il suo corpo e gli allegati. |
expire_at |
string|null | Scadenza effettiva come timestamp ISO-8601, o null per una casella di posta illimitata. |
expires_in_seconds |
number|null | Secondi rimanenti non negativi al calcolo; i secondi frazionari sono possibili. Null significa illimitato, non zero. |
mailbox_state |
string | Stato attuale della casella di posta: attiva, in pausa, scaduta o inattiva. |
receiving_enabled |
boolean | Indica se questa casella di posta accetta attualmente messaggi in arrivo. |
message_count |
integer | Conteggio totale dei messaggi noto; può riflettere l'ultima sincronizzazione della casella di posta. |
unread_message_count |
integer | Conteggio dei messaggi non letti conosciuti; può riflettere l'ultima sincronizzazione della casella di posta. |
last_message_received_at |
string|null | Ultimo orario noto del messaggio ricevuto in formato ISO-8601, o null se non disponibile. |
message_count_synced_at |
string|null | Ultimo orario di sincronizzazione del conteggio dei messaggi in formato ISO-8601, o null prima della sincronizzazione. |
mailbox_limit.limit |
integer | Limite attivo della casella di posta per questo provider; -1 significa illimitato. |
mailbox_limit.limit_label |
string | Etichetta visualizzata per il limite della casella di posta. |
mailbox_limit.active_count |
integer | Numero di cassette postali attive per questo provider. |
mailbox_limit.paused_count |
integer | Numero di cassette postali messe in pausa per questo provider. |
mailbox_limit.paused_mailboxes |
array<string> | Indirizzi sospesi a causa del limite della casella di posta. |
mailbox_limit.remaining |
integer | Slot di caselle di posta attive rimanenti; -1 significa illimitato. Questo non è il limite di richieste API. |
mailbox_limit.remaining_label |
string | Etichetta di visualizzazione per le caselle di posta rimanenti. |
mailbox_limit.reached |
boolean | Indica se è stato raggiunto il limite di caselle di posta attive. |
mailbox_limit.blocked |
boolean | Se il limite della casella di posta attiva è zero. |
mailbox_limit.provider |
string|null | Provider a cui si applica il limite della casella di posta. |
messages[].id |
string | ID messaggio opaco utilizzato dagli endpoint singolo messaggio, cancellazione e allegato. |
messages[].is_seen |
boolean | Se il messaggio è contrassegnato come letto. |
messages[].subject |
string | Oggetto del messaggio. |
messages[].from |
string | Nome visualizzato o indirizzo del mittente. |
messages[].from_email |
string | Indirizzo email del mittente. |
messages[].receivedAt |
string | Ora di ricezione nel fuso orario dell'applicazione, formattata come YYYY-MM-DD HH:mm:ss. |
messages[].otp |
string|null | Rilevato codice monouso quando disponibile e consentito; altrimenti null. |
messages[].otp_locked |
boolean | Se un codice monouso rilevato è nascosto dalle autorizzazioni della funzionalità. |
messages[].verification_link |
string|null | URL di verifica rilevato quando disponibile e consentito; altrimenti null. |
messages[].verification_link_locked |
boolean | Se un link di verifica rilevato è nascosto dalle autorizzazioni delle funzionalità. |
messages[].from_name |
string|null | Campo riepilogo di Outlook: nome del mittente originale. Assente nei riepiloghi Standard e Gmail. |
messages[].snippet |
string|null | Campo riepilogo di Outlook: anteprima breve del messaggio. |
messages[].received_at |
string|null | Campo riepilogo di Outlook: ora di ricezione ISO-8601, quando nota. |
messages[].has_attachments |
boolean | Campo riepilogo di Outlook: se esistono i metadati degli allegati. La disponibilità del download è verificata separatamente. |
Recupera singolo messaggio
Recupera un messaggio di proprietà tramite il suo ID messaggio opaco. Restituisce i formati del corpo e i metadati degli allegati. I campi del corpo dipendono dal formato del messaggio; Outlook aggiunge i campi specifici del provider elencati di seguito.
| Parametro | Posizione | Tipo | Stato | Descrizione |
|---|---|---|---|---|
messageId
|
path | string | obbligatorio |
ID messaggio unico restituito nell'elenco dei messaggi.
|
X-Mailbox-Unlock
|
header | string | opzionale |
Intestazione, solo caselle di posta protette: usa un unlock_token di lettura. Prima invia un POST con pin e scope=read all'URL di sblocco PIN. Mantieni la tua normale autenticazione Bearer. <code>https://v1.tempmailg.com/api/mailboxes/{mailbox}/pin/unlock</code>
|
const response = await fetch('https://v1.tempmailg.com/api/messages/ap94AWDg123ELQz07vrVB9dLXlbqZM5NGwYxOJKko8n6m1', {
method: 'GET',
headers: {
'Authorization': 'Bearer YOUR_USER_API_KEY',
'Accept': 'application/json',
},
});
if (!response.ok) {
throw new Error(`Request failed with status ${response.status}`);
}
const data = await response.json();
console.log(data);
import requests
headers = {
'Authorization': 'Bearer YOUR_USER_API_KEY',
'Accept': 'application/json',
}
response = requests.get('https://v1.tempmailg.com/api/messages/ap94AWDg123ELQz07vrVB9dLXlbqZM5NGwYxOJKko8n6m1', headers=headers, timeout=30)
response.raise_for_status()
print(response.json())
<?php
$ch = curl_init('https://v1.tempmailg.com/api/messages/ap94AWDg123ELQz07vrVB9dLXlbqZM5NGwYxOJKko8n6m1');
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'GET',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'Authorization: Bearer YOUR_USER_API_KEY',
'Accept: application/json',
],
]);
$response = curl_exec($ch);
if ($response === false) {
throw new RuntimeException(curl_error($ch));
}
$statusCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);
var_dump($statusCode, json_decode($response, true));
curl --request GET \
--url 'https://v1.tempmailg.com/api/messages/ap94AWDg123ELQz07vrVB9dLXlbqZM5NGwYxOJKko8n6m1' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer YOUR_USER_API_KEY'
Risposta illustrativa usando dati sintetici. ID, indirizzi, token, timestamp, limiti e conteggi del piano variano. Le durate di esempio non sovrascrivono il valore predefinito del tuo piano. Le descrizioni dei campi di risposta identificano i campi nullable e specifici del provider.
Esempio di risposta
200 OK • JSON{
"status": true,
"data": {
"is_seen": true,
"subject": "Welcome to Temp Mail",
"from": "Example Sender",
"from_email": "hello@example.org",
"to": "demo123@example.com",
"mailbox_provider": "standard",
"receivedAt": "2026-11-19 02:17:48",
"id": "ap94AWDg123ELQz07vrVB9dLXlbqZM5NGwYxOJKko8n6m1",
"html": true,
"html_content": "<p>Hello from the inbox.</p>",
"text_content": "<pre>Hello from the inbox.</pre>",
"content": "<p>Hello from the inbox.</p>",
"attachments": [
{
"name": "file.txt",
"extension": "txt",
"size": 91,
"url": "https://v1.tempmailg.com/api/messages/ap94AWDg123ELQz07vrVB9dLXlbqZM5NGwYxOJKko8n6m1/attachments/file.txt"
}
]
}
}
| Campo | Tipo | Descrizione |
|---|---|---|
status |
boolean | Se l'operazione è riuscita. |
data.id |
string | ID messaggio opaco. |
data.is_seen |
boolean | Stato di lettura del messaggio. La lettura può contrassegnarlo come visto; i dati memorizzati nella cache possono riflettere uno stato precedente. |
data.subject |
string | Oggetto del messaggio. |
data.from |
string | Nome visualizzato o indirizzo del mittente. |
data.from_email |
string | Indirizzo email del mittente. |
data.to |
string | Indirizzo della casella di posta del destinatario. |
data.mailbox_provider |
string | Provider della casella di posta: standard, gmail_alias, o outlook_alias. |
data.receivedAt |
string | Ora di ricezione nel fuso orario dell'applicazione, formattata come YYYY-MM-DD HH:mm:ss. |
data.html |
boolean | Indica se il messaggio ha un corpo HTML. |
data.html_content |
string | Corpo HTML quando presente. I messaggi standard senza HTML possono omettere questo campo. Considera il contenuto del messaggio come non attendibile. |
data.text_content |
string | Corpo del testo quando presente; I messaggi standard possono contenere testo escapato in un elemento pre o omettere questo campo. |
data.content |
string | Corpo preferito per la visualizzazione, normalmente HTML quando disponibile. |
data.attachments |
array | Metadati dell'allegato, o un array vuoto. I download richiedono l'autenticazione normale e l'autorizzazione PIN applicabile. |
data.attachments[].name |
string | Nome file da codificare in URL come singolo segmento di percorso durante il download. |
data.attachments[].size |
integer | Dimensione dell'allegato in byte. |
data.attachments[].url |
string | URL di download dell'API per l'utente autenticato aggiunto agli allegati con un nome file. Un URL non garantisce che il file locale sia disponibile. |
data.attachments[].extension |
string | Campo di metadati Standard/Gmail: estensione del file quando fornita. |
data.attachments[].id |
string | Campo metadati Outlook: ID allegato del provider. |
data.attachments[].content_type |
string | Campo metadati Outlook: tipo di contenuto MIME. |
data.from_name |
string|null | Campo di dettaglio Outlook: nome del mittente originale. |
data.to_email |
string|null | Campo dettagli Outlook: indirizzo del destinatario originale. |
data.received_at |
string|null | Campo di dettaglio Outlook: ora di ricezione ISO-8601. |
data.has_html |
boolean | Campo di dettaglio Outlook: se esiste un corpo HTML. |
Elimina messaggio
Eliminare un singolo messaggio posseduto.
| Parametro | Posizione | Tipo | Stato | Descrizione |
|---|---|---|---|---|
messageId
|
path | string | obbligatorio |
Stringa ID messaggio unico da eliminare definitivamente.
|
X-Mailbox-Unlock
|
header | string | opzionale |
Intestazione, solo cassette postali protette: usa il token di sblocco per eliminazione monouso. Prima invia un POST pin, scope=delete e l'action/target_id restituiti dalla risposta 423 all'URL di sblocco PIN. Un token di lettura non può eliminare. <code>https://v1.tempmailg.com/api/mailboxes/{mailbox}/pin/unlock</code>
|
Idempotency-Key
|
header | string | opzionale |
Richiesto per la creazione o eliminazione protetta da PIN: una chiave stabile da 16 a 128 caratteri. Riprova la stessa richiesta con la stessa chiave per evitare lavoro duplicato.
|
const response = await fetch('https://v1.tempmailg.com/api/messages/ap94AWDg123ELQz07vrVB9dLXlbqZM5NGwYxOJKko8n6m1', {
method: 'DELETE',
headers: {
'Authorization': 'Bearer YOUR_USER_API_KEY',
'Accept': 'application/json',
},
});
if (!response.ok) {
throw new Error(`Request failed with status ${response.status}`);
}
const data = await response.json();
console.log(data);
import requests
headers = {
'Authorization': 'Bearer YOUR_USER_API_KEY',
'Accept': 'application/json',
}
response = requests.delete('https://v1.tempmailg.com/api/messages/ap94AWDg123ELQz07vrVB9dLXlbqZM5NGwYxOJKko8n6m1', headers=headers, timeout=30)
response.raise_for_status()
print(response.json())
<?php
$ch = curl_init('https://v1.tempmailg.com/api/messages/ap94AWDg123ELQz07vrVB9dLXlbqZM5NGwYxOJKko8n6m1');
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'DELETE',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'Authorization: Bearer YOUR_USER_API_KEY',
'Accept: application/json',
],
]);
$response = curl_exec($ch);
if ($response === false) {
throw new RuntimeException(curl_error($ch));
}
$statusCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);
var_dump($statusCode, json_decode($response, true));
curl --request DELETE \
--url 'https://v1.tempmailg.com/api/messages/ap94AWDg123ELQz07vrVB9dLXlbqZM5NGwYxOJKko8n6m1' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer YOUR_USER_API_KEY'
Risposta illustrativa usando dati sintetici. ID, indirizzi, token, timestamp, limiti e conteggi del piano variano. Le durate di esempio non sovrascrivono il valore predefinito del tuo piano. Le descrizioni dei campi di risposta identificano i campi nullable e specifici del provider.
Esempio di risposta
200 OK • JSON{
"status": true,
"message": "Message was deleted successfully."
}
| Campo | Tipo | Descrizione |
|---|---|---|
status |
boolean | Se l'operazione è riuscita. |
message |
string | Risultato dell'eliminazione. Una risorsa mancante restituisce HTTP 404. |
Scarica allegato
Scarica un allegato da un messaggio di proprietà.
| Parametro | Posizione | Tipo | Stato | Descrizione |
|---|---|---|---|---|
messageId
|
path | string | obbligatorio |
ID del messaggio contenente il file.
|
filename
|
path | string | obbligatorio |
Nome file e estensione dell'allegato da scaricare.
|
X-Mailbox-Unlock
|
header | string | opzionale |
Intestazione, solo caselle di posta protette: usa un unlock_token di lettura. Prima invia un POST con pin e scope=read all'URL di sblocco PIN. Mantieni la tua normale autenticazione Bearer. <code>https://v1.tempmailg.com/api/mailboxes/{mailbox}/pin/unlock</code>
|
const response = await fetch('https://v1.tempmailg.com/api/messages/ap94AWDg123ELQz07vrVB9dLXlbqZM5NGwYxOJKko8n6m1/attachments/file.txt', {
method: 'GET',
headers: {
'Authorization': 'Bearer YOUR_USER_API_KEY',
'Accept': 'application/json',
},
});
if (!response.ok) {
throw new Error(`Request failed with status ${response.status}`);
}
const blob = await response.blob();
const downloadUrl = window.URL.createObjectURL(blob);
const link = document.createElement('a');
link.href = downloadUrl;
link.download = 'file.txt';
document.body.appendChild(link);
link.click();
link.remove();
window.URL.revokeObjectURL(downloadUrl);
import requests
headers = {
'Authorization': 'Bearer YOUR_USER_API_KEY',
'Accept': 'application/json',
}
response = requests.get('https://v1.tempmailg.com/api/messages/ap94AWDg123ELQz07vrVB9dLXlbqZM5NGwYxOJKko8n6m1/attachments/file.txt', headers=headers, stream=True, timeout=30)
response.raise_for_status()
with open('file.txt', 'wb') as handle:
for chunk in response.iter_content(chunk_size=8192):
if chunk:
handle.write(chunk)
<?php
$fileHandle = fopen('file.txt', 'w');
$ch = curl_init('https://v1.tempmailg.com/api/messages/ap94AWDg123ELQz07vrVB9dLXlbqZM5NGwYxOJKko8n6m1/attachments/file.txt');
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'GET',
CURLOPT_FILE => $fileHandle,
CURLOPT_FOLLOWLOCATION => true,
CURLOPT_HTTPHEADER => [
'Authorization: Bearer YOUR_USER_API_KEY',
'Accept: application/json',
],
]);
if (curl_exec($ch) === false) {
fclose($fileHandle);
throw new RuntimeException(curl_error($ch));
}
curl_close($ch);
fclose($fileHandle);
curl --request GET \
--url 'https://v1.tempmailg.com/api/messages/ap94AWDg123ELQz07vrVB9dLXlbqZM5NGwYxOJKko8n6m1/attachments/file.txt' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer YOUR_USER_API_KEY' \
--output file.txt
| Campo | Tipo | Descrizione |
|---|---|---|
Content-Disposition |
header | La risposta riuscita scarica il nome file richiesto. |
body |
binary | Byte del file in caso di successo, non JSON. Gli errori restituiscono JSON con uno stato non 2xx. |
Limiti di velocità e quote
Monitora i budget delle richieste in tempo reale, i limiti di velocità e le quote dell'account senza consumare crediti.
Limite di velocità e quota
Controlla il tuo limite di velocità e lo stato della quota attuali senza consumare alcun utilizzo dell'API. Questo endpoint è senza quota e non detrae crediti API mensili (limite di protezione contro gli abusi: 60 richieste/min).
const response = await fetch('https://v1.tempmailg.com/api/rate-limit', {
method: 'GET',
headers: {
'Authorization': 'Bearer YOUR_USER_API_KEY',
'Accept': 'application/json',
},
});
if (!response.ok) {
throw new Error(`Request failed with status ${response.status}`);
}
const data = await response.json();
console.log(data);
import requests
headers = {
'Authorization': 'Bearer YOUR_USER_API_KEY',
'Accept': 'application/json',
}
response = requests.get('https://v1.tempmailg.com/api/rate-limit', headers=headers, timeout=30)
response.raise_for_status()
print(response.json())
<?php
$ch = curl_init('https://v1.tempmailg.com/api/rate-limit');
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'GET',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'Authorization: Bearer YOUR_USER_API_KEY',
'Accept: application/json',
],
]);
$response = curl_exec($ch);
if ($response === false) {
throw new RuntimeException(curl_error($ch));
}
$statusCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);
var_dump($statusCode, json_decode($response, true));
curl --request GET \
--url 'https://v1.tempmailg.com/api/rate-limit' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer YOUR_USER_API_KEY'
Risposta illustrativa usando dati sintetici. ID, indirizzi, token, timestamp, limiti e conteggi del piano variano. Le durate di esempio non sovrascrivono il valore predefinito del tuo piano. Le descrizioni dei campi di risposta identificano i campi nullable e specifici del provider.
Esempio di risposta
200 OK • JSON{
"status": "success",
"data": {
"limit": 60,
"remaining": 45,
"reset": 32,
"plan": "premium",
"monthly_limit": 50000,
"monthly_remaining": 48210,
"purchased_credits": 5000,
"quota": {
"enabled": true,
"user_api_status": true,
"plan_name": "Premium Plan",
"period": "2026-10",
"base_limit": 50000,
"extra_requests": 0,
"monthly_limit": 50000,
"monthly_remaining": 48210,
"used": 1790,
"purchased_credits": 5000,
"bonus_credits": 1000,
"direct_purchased_credits": 4000,
"remaining": 53210,
"unlimited": false,
"usage_percent": 3,
"reset_at": "2026-11-01T00:00:00+00:00"
}
}
}
| Campo | Tipo | Descrizione |
|---|---|---|
data.limit |
integer|string | Limite di richieste per minuto dell'account. La stringa unlimited indica un budget di minuti illimitato; questo è indipendente dalla quota mensile. |
data.remaining |
integer|string | Slot di minuti rimanenti del budget dell'account, o la stringa unlimited. Un valore positivo non significa che i crediti API rimangano. |
data.reset |
integer | Secondi per la finestra di un minuto dell'account, non per il reset mensile della quota. I budget di minuti disabilitati o illimitati possono mantenere un valore nominale di 60 secondi; ciò non garantisce l'accesso dopo l'attesa. |
data.plan |
string | Tag del piano corrente. Il nome leggibile del piano è fornito separatamente in data.quota.plan_name. |
data.quota.enabled |
boolean | Indica se l'accesso globale e quello al piano/credito API è abilitato. Questo non indica la capacità rimanente né sostituisce l'interruttore API dell'utente. |
data.quota.user_api_status |
boolean | Se l'utente ha abilitato l'interruttore User API. Le operazioni richiedono questo interruttore così come l'accesso abilitato e la capacità disponibile. |
data.quota.plan_name |
string | Nome leggibile del piano corrente. |
data.quota.period |
string | Periodo di utilizzo mensile del calendario nel formato YYYY-MM, usando il fuso orario dell'applicazione; non necessariamente il periodo di fatturazione dell'abbonamento. |
data.quota.base_limit |
integer | Quota di base del piano mensile. Un valore di -1 significa illimitato. |
data.quota.extra_requests |
integer | Quota mensile aggiuntiva concessa per il periodo di utilizzo corrente; separata dai crediti acquistati. |
data.quota.monthly_limit |
integer | Quota di base più richieste extra del periodo corrente. Un valore di -1 significa illimitato. I crediti acquistati non sono inclusi. |
data.quota.monthly_remaining |
integer|null | Quota mensile finita rimanente, o null quando la quota mensile è illimitata. Null non deve essere interpretato come zero. |
data.quota.used |
integer | Operazioni API riuscite e conteggiate nel periodo di utilizzo corrente, incluse le operazioni che utilizzano crediti. I controlli di stato non aumentano questo valore. |
data.quota.purchased_credits |
integer | Saldo attuale del credito, inclusi i crediti bonus del piano attivo. I crediti bonus non devono essere aggiunti a questo saldo una seconda volta. |
data.quota.bonus_credits |
integer | Quota attiva del bonus del piano del saldo crediti; una ripartizione di purchased_credits, non capacità aggiuntiva. |
data.quota.direct_purchased_credits |
integer | Saldo crediti esclusa la parte di bonus del piano attivo. Questo valore più bonus_credits equivale a purchased_credits. |
data.quota.remaining |
integer|null | Quota mensile residua più il saldo di credito attuale, senza contare due volte i bonus. Null indica una quota mensile illimitata. Le autorizzazioni individuali delle funzionalità e gli altri limiti di richiesta rimangono comunque applicati. |
data.quota.unlimited |
boolean | Indica se la quota mensile è illimitata. Questo non rende illimitato il budget minuti dell'account o altri limiti delle funzionalità. |
data.quota.usage_percent |
integer | Percentuale arrotondata compatibile con il cruscotto da 0 a 100: usato diviso per usato più rimanente, moltiplicato per 100. Include la capacità di credito disponibile, quindi la ricarica può ridurre la percentuale. È 0 per quota illimitata o un pool di dimensione zero; non è la percentuale di limite di velocità al minuto né una decisione di accesso. |
data.quota.reset_at |
string | Timestamp ISO-8601 con offset del fuso orario per il reset della quota del prossimo mese di calendario. Questo non è la data di scadenza dell'abbonamento, e il reset mensile non ricarica i crediti acquistati. |
status |
string | Il successo letterale per questo endpoint di stato. Altri endpoint di casella di posta di successo usano il valore booleano true. |
data.monthly_limit |
integer | Alias di compatibilità del campo data.quota corrispondente; non aggiungerlo nuovamente durante il calcolo dei saldi. |
data.monthly_remaining |
integer|null | Alias di compatibilità del campo data.quota corrispondente; non aggiungerlo nuovamente durante il calcolo dei saldi. |
data.purchased_credits |
integer | Alias di compatibilità del campo data.quota corrispondente; non aggiungerlo nuovamente durante il calcolo dei saldi. |
Webhook per Mailbox (Invio in Tempo Reale)
Invece di interrogare ripetutamente l'API REST (GET /messages) per controllare se ci sono messaggi in arrivo, configura le Webhook per inviare nuovi messaggi al tuo server o al tuo flusso di lavoro di automazione in tempo reale.
Eventi Webhook supportati
Ogni webhook può iscriversi a uno o più tipi di eventi. Il tuo endpoint riceve una notifica di evento ogni volta che uno di questi trigger viene attivato.
Inviato in tempo reale ogni volta che un nuovo messaggio raggiunge la casella di posta selezionata.
Inviato quando la casella di posta temporanea scade e l'elaborazione del webhook è in pausa.
Inviato quando una casella di posta scaduta diventa nuovamente attiva secondo le regole del piano.
Inviato subito prima che il webhook e la sua casella di posta vengano eliminati.
Intestazioni della richiesta & Verifica della firma HMAC
Ogni invio di webhook contiene intestazioni di sicurezza speciali. Utilizza l'intestazione X-TempMailg-Signature per verificare che le richieste in arrivo siano state effettivamente inviate da TempMailg e non siano state alterate.
| Nome intestazione | Valore di esempio | Descrizione |
|---|---|---|
User-Agent |
TempMailg-Webhooks/1.0 | Identificatore standard per il worker di consegna webhook. |
X-TempMailg-Event |
email.received | Il tipo di evento che ha attivato questa consegna. |
X-TempMailg-Event-Id |
e7b1a2c3-4d5e-6f7a-8b9c-0d1e2f3a4b5c | UUID univoco assegnato a questo tentativo di consegna. |
X-TempMailg-Timestamp |
1725192000 | Timestamp Unix epoch che indica quando è stata avviata la richiesta. |
X-TempMailg-Signature |
sha256=d7a8fbb307d7809469ca933b02d82941... | Firma HMAC-SHA256 calcolata da {timestamp}.{raw_body} usando il tuo segreto. |
X-TempMailg-Test |
false | Vero quando inviato dalla funzione "Invia Ping di Test" nella tua dashboard. |
La firma viene calcolata utilizzando HMAC con SHA256 sulla stringa:
hash_hmac('sha256', "${X-TempMailg-Timestamp}.${raw_request_body}", your_webhook_secret)
Esempio di Payload di Evento (email.received)
Inviato come application/json nel corpo della richiesta HTTP POST.
{
"id": "e7b1a2c3-4d5e-6f7a-8b9c-0d1e2f3a4b5c",
"version": "1.0",
"event": "email.received",
"occurred_at": "2026-11-19T02:17:48+00:00",
"test": false,
"mailbox": {
"id": 1024,
"email": "developer@v1.tempmailg.com"
},
"data": {
"message_id": "7a8b9c0d1e2f",
"subject": "Your Verification Code: 948201",
"from": "auth@service.com",
"to": "developer@v1.tempmailg.com",
"date": "2026-11-19T02:17:48+00:00",
"attachments_count": 0,
"text_preview": "Hello, your one-time verification code is 948201. It will expire in 10 minutes.",
"email_url": "https://tempmailg.com/mailbox/1024?message=7a8b9c0d1e2f",
"inbox_url": "https://tempmailg.com/mailbox/1024"
}
}
Esempi di implementazione del ricevitore
Seleziona la tua lingua per vedere come ricevere webhook e verificare le firme HMAC in modo sicuro.
const express = require('express');
const crypto = require('crypto');
const app = express();
const WEBHOOK_SECRET = 'your_webhook_signing_secret';
// Capture raw body buffer for HMAC-SHA256 signature verification
app.use(express.json({
verify: (req, res, buf) => {
req.rawBody = buf.toString('utf8');
}
}));
app.post('/webhook', (req, res) => {
const timestamp = req.headers['x-tempmailg-timestamp'];
const signatureHeader = req.headers['x-tempmailg-signature'] || '';
// Calculate HMAC-SHA256 signature
const expectedSignature = 'sha256=' + crypto
.createHmac('sha256', WEBHOOK_SECRET)
.update(`${timestamp}.${req.rawBody}`)
.digest('hex');
// Verify signature
if (signatureHeader !== expectedSignature) {
return res.status(401).json({ error: 'Invalid webhook signature' });
}
const { event, mailbox, data } = req.body;
console.log(`[Event: ${event}] Mailbox: ${mailbox.email}`);
if (event === 'email.received') {
console.log(`From: ${data.from}`);
console.log(`Subject: ${data.subject}`);
console.log(`Preview: ${data.text_preview}`);
}
// Acknowledge receipt with HTTP 200
res.status(200).json({ received: true });
});
app.listen(3000, () => console.log('Webhook receiver running on port 3000'));
from flask import Flask, request, jsonify
import hmac
import hashlib
app = Flask(__name__)
WEBHOOK_SECRET = b"your_webhook_signing_secret"
@app.route("/webhook", methods=["POST"])
def handle_webhook():
timestamp = request.headers.get("X-TempMailg-Timestamp", "")
signature_header = request.headers.get("X-TempMailg-Signature", "")
# Calculate expected HMAC-SHA256 signature
raw_body = request.get_data()
signed_payload = f"{timestamp}.".encode("utf-8") + raw_body
expected_signature = "sha256=" + hmac.new(
WEBHOOK_SECRET, signed_payload, hashlib.sha256
).hexdigest()
# Verify signature securely
if not hmac.compare_digest(signature_header, expected_signature):
return jsonify({"error": "Invalid signature"}), 401
payload = request.get_json()
event = payload.get("event")
mailbox = payload.get("mailbox", {}).get("email")
data = payload.get("data", {})
print(f"[{event}] Mailbox: {mailbox}")
if event == "email.received":
print(f"From: {data.get('from')}")
print(f"Subject: {data.get('subject')}")
print(f"Preview: {data.get('text_preview')}")
# Return 200 OK to acknowledge receipt
return jsonify({"received": True}), 200
if __name__ == "__main__":
app.run(port=5000)
<?php
$secret = 'your_webhook_signing_secret';
$rawBody = file_get_contents('php://input');
$timestamp = $_SERVER['HTTP_X_TEMPMAILG_TIMESTAMP'] ?? '';
$receivedSignature = $_SERVER['HTTP_X_TEMPMAILG_SIGNATURE'] ?? '';
// Calculate HMAC-SHA256 signature
$expectedSignature = 'sha256=' . hash_hmac('sha256', $timestamp . '.' . $rawBody, $secret);
// Verify signature
if (!hash_equals($expectedSignature, $receivedSignature)) {
http_response_code(401);
echo json_encode(['error' => 'Invalid signature']);
exit;
}
$payload = json_decode($rawBody, true);
$event = $payload['event'] ?? '';
$mailbox = $payload['mailbox']['email'] ?? '';
$data = $payload['data'] ?? [];
if ($event === 'email.received') {
$sender = $data['from'] ?? '';
$subject = $data['subject'] ?? '';
$preview = $data['text_preview'] ?? '';
// Process new incoming email...
}
// Acknowledge receipt
http_response_code(200);
echo json_encode(['received' => true]);
Piattaforme supportate e integrazioni di automazione
I webhook di TempMailg funzionano subito con endpoint HTTPS standard e le principali piattaforme no-code/automazione:
Errori comuni e risoluzione dei problemi
Questi sono i codici di risposta più comuni che potresti vedere durante l'integrazione dell'API dell'utente.
Token Bearer non valido, mancante o revocato.
La proprietà, le autorizzazioni delle funzionalità, l'accesso al dominio o la dimensione dell'allegato hanno impedito l'operazione. Controlla il codice di risposta e il messaggio.
La risorsa non è stata trovata sull'host consentito o non appartiene all'utente.
La chiave dell'operazione è stata riutilizzata con dettagli diversi, un'altra operazione è in sospeso, o la sicurezza della casella di posta è cambiata. Verifica il codice prima di riprovare.
La casella di posta è scaduta o inattiva.
Parametri non validi, una durata non consentita, capacità di alias non disponibile, configurazione PIN non valida o un Idempotency-Key mancante/non valido hanno impedito l'operazione.
Una casella di posta protetta richiede un token X-Mailbox-Unlock valido e con ambito. Usa l'azione e target_id dalla risposta per l'eliminazione. I requisiti di blocco o di recupero devono essere risolti prima di riprovare.
Un limite di richieste, un piano disabilitato, una quota esaurita o un periodo di raffreddamento hanno impedito l'operazione. Controlla il motivo e le intestazioni del budget disponibile. Retry-After è opzionale.
Il server non è riuscito a completare l'operazione. Per la creazione o l'eliminazione protetta, conservare la stessa richiesta e Idempotency-Key durante il nuovo tentativo.
Impossibile verificare l'archiviazione della protezione o il coordinamento. Riprova dopo il ritardo indicato. Questa risposta non è un pagamento fallito.
Lista di controllo rapida
- 401 Unauthorized - Il token Bearer è mancante, errato, revocato o copiato in modo errato.
- 403 Forbidden - Il piano attuale non ha attualmente il diritto di accesso all'API dell'utente.
- 404 Not Found - Risorsa non trovata o parametro invalido
- 410 Gone / Expired - La casella di posta è scaduta o non è più attiva.
- 429 Rate Limited - Controlla il motivo della risposta e le intestazioni del budget. Retry-After si applica solo ai limiti temporizzati; crediti esauriti o accesso disabilitato potrebbero richiedere una modifica dell'account.
Passo successivo consigliato
Se sei connesso, apri prima la gestione dell'API e conferma lo stato del tuo chiave, quota, piano di accesso e l'esatto URL di base dell'API utente prima di eseguire il debug della tua app esterna.