Lista de verificación de configuración rápida
- Abra la página de administración de API de su panel de control y cree su clave de API personal.
- Copie la URL base de la API de usuario exacta que se muestra allí, por ejemplo https://v1.tempmailg.com/api.
- Envíe cada solicitud al host de API con Authorization: Bearer YOUR_USER_API_KEY y Accept: application/json.
- Rastrea tu cuota mensual de solicitudes desde la misma página del panel y desde los encabezados de cuota cuando estén disponibles en las respuestas de la API de usuario. Solo las solicitudes exitosas 2xx cuentan para la cuota.
Acceso a la clave de API
Inicie sesión para crear su clave de API personal y ver los detalles de la cuota en vivo.
Flujo de autenticación
- Genera tu clave de API personal desde la página de Administración de API del panel.
- Envía la clave como un token Bearer en cada solicitud.
- Usa la URL base de la API de usuario dedicada que se muestra en tu página de Administración de API.
- Regenera la clave cada vez que desees invalidar la antigua y comenzar a usar una nueva clave de inmediato.
Encabezados requeridos
Authorization: Bearer YOUR_USER_API_KEY
Accept: application/json
Encabezados de límite de velocidad & cuota
Los encabezados de límite de velocidad describen el presupuesto de solicitudes indicado. Los encabezados de cuota se incluyen cuando la información de cuota está disponible; los rechazos por límite de minuto no calculan su cuota mensual 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— Máximo de solicitudes permitidas por minuto (RPM) para su plan.X-RateLimit-Remaining— Solicitudes RPM restantes en la ventana actual de un minuto.X-RateLimit-Reset— Marca de tiempo Unix cuando se restablece la ventana de límite de velocidad del minuto actual.X-Quota-Limit— Capacidad total mensual y de crédito adquirido para su cuenta.X-Quota-Remaining— Solicitudes de API disponibles restantes en el mes actual.X-Quota-Used— Total de solicitudes API consumidas durante el período de facturación actual.X-Quota-Reset— Marca de tiempo ISO-8601 cuando se restablece tu cuota mensual.X-RateLimit-Scope— El presupuesto descrito por los encabezados: account, ip, status_endpoint, o mailbox.X-Mailbox-RateLimit-*— Presupuesto separado para la creación/actualización de buzones. Las respuestas exitosas de buzón mantienen el RPM de la cuenta en X-RateLimit-*; un rechazo solo de buzón utiliza el alcance del buzón y su propia ventana de reintento.Retry-After— Segundos hasta que sea apropiado un reintento programado. Un plan deshabilitado o una cuota agotada pueden requerir un cambio de cuenta en su lugar, por lo que este encabezado no siempre está presente.503 protection_unavailable— El almacenamiento o la coordinación de protección de API no está disponible temporalmente. Intente de nuevo más tarde; esto no es un fallo de pago ni un débito de crédito.
Gestión del buzón
Obtenga dominios permitidos, cree o cambie buzones, elija duraciones permitidas y elimine direcciones propias.
Listar dominios permitidos
Enumere los dominios disponibles para crear correos electrónicos temporales. Filtre por tipo para ver solo dominios gratuitos, premium o personalizados compatibles con su plan de suscripción.
| Parámetro | Ubicación | Tipo | Estado | Descripción |
|---|---|---|---|---|
type
|
query | string | opcional |
Filtro de nivel de dominio. La omisión usa todos cuando el acceso a dominio premium está habilitado, de lo contrario gratuito. Valores reconocidos: free, basic, pro, premium, custom, ultimate, all
Predeterminado:
Dependiente de la cuenta
|
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'
Respuesta ilustrativa usando datos sintéticos. Los IDs, direcciones, tokens, marcas de tiempo, límites y recuentos del plan varían. Las duraciones de muestra no sobrescriben la configuración predeterminada de su plan. Las descripciones de los campos de respuesta identifican los campos que pueden ser nulos y los específicos del proveedor.
Ejemplo de respuesta
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 | Descripción |
|---|---|---|
status |
boolean | Si la operación tuvo éxito. |
data.requested_type |
string | Filtro de dominio aplicado. |
data.plan |
string | Etiqueta del plan actual. |
data.plan_name |
string | Nombre legible del plan actual. |
data.allowed_types |
array<string> | Filtros de dominio disponibles para esta cuenta. Un filtro reconocido aún puede estar prohibido para su plan. |
data.domains |
array | Dominios seleccionables después del filtrado; una matriz vacía es válida. |
data.domains[].domain |
string | Nombre de dominio seleccionable. |
data.domains[].type |
string | Etiqueta del nivel de dominio legible. |
data.domains[].custom |
boolean | Si esto es un dominio personalizado. |
Crear buzón temporal
Cree un buzón temporal propio. Omitir nombre de usuario y dominio para generación aleatoria, o proporcionar un nombre de usuario personalizado permitido y un dominio permitido. El parámetro provider puede seleccionar la generación de alias de Gmail u Outlook.
| Parámetro | Ubicación | Tipo | Estado | Descripción |
|---|---|---|---|---|
username
|
body | string | opcional |
Nombre de usuario personalizado opcional: de 2 a 64 caracteres ASCII, incluyendo letras, dígitos, puntos, guiones bajos o guiones. Requiere permiso del plan; también se acepta custom_username.
Predeterminado:
Generado aleatoriamente
|
domain
|
body | string | opcional |
Uno de los dominios permitidos devueltos por GET /domains. La omisión elige un dominio permitido aleatorio.
Predeterminado:
Dominio permitido aleatorio
|
lifetime
|
body | string | opcional |
valores permitidos:
10m — 10 minutos
1h — 1 Hora
2h — 2 Horas
1d — 1 día
1w — 1 Semana
1m — 30 Días
3m — 90 días
6m — 180 días
1y — 365 días
unlimited — Ilimitado
Predeterminado:
Vida útil predeterminada del plan
|
provider
|
body | string | opcional |
Proveedor de buzón: standard, gmail_alias, o outlook_alias.
Predeterminado:
standard
|
pin_enabled
|
body | boolean | opcional |
Protección opcional con PIN para el nuevo buzón, cuando lo permita su plan. No cambia el PIN de un buzón existente.
Predeterminado:
false
|
pin
|
body | string | opcional |
Requerido cuando pin_enabled es true: un PIN de 6 a 8 dígitos, enviado como una cadena para preservar los ceros iniciales.
|
pin_confirmation
|
body | string | opcional |
Requerido cuando pin_enabled es true. Debe coincidir exactamente con pin.
|
Idempotency-Key
|
header | string | opcional |
Requerido para la creación o eliminación protegida por PIN: una clave estable de 16 a 128 caracteres. Reintente la solicitud idéntica con la misma clave para evitar trabajo duplicado.
|
username (nombre de usuario personalizado si lo permite el plan), domain (dominio permitido, p. ej. example.com), lifetime (valores permitidos: 10m, 1h, 2h, 1d, 1w, 1m, 3m, 6m, 1y, unlimited), provider (standard, gmail_alias, outlook_alias). Omita la duración, o déjela vacía, para usar la Duración de Correo Electrónico Predeterminada configurada para su plan mensual/anual actual. Envíe una duración permitida, como 1h, para sobrescribir esa predeterminada. Ilimitado se usa solo cuando está configurado como la opción predeterminada del plan o se solicita explícitamente y está permitido. Los parámetros del cuerpo mailbox_lifetime y email_lifetime también son aceptados; el primer valor no vacío gana en este orden: lifetime, mailbox_lifetime, email_lifetime. Los valores inválidos o no permitidos devuelven HTTP 422 en lugar de seleccionar silenciosamente un valor predeterminado.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'
Respuesta ilustrativa usando datos sintéticos. Los IDs, direcciones, tokens, marcas de tiempo, límites y recuentos del plan varían. Las duraciones de muestra no sobrescriben la configuración predeterminada de su plan. Las descripciones de los campos de respuesta identifican los campos que pueden ser nulos y los específicos del proveedor.
Ejemplo de respuesta
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:18:04+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:18:04+00:00",
"email_token": "encrypted-email-token"
}
}
| Campo | Tipo | Descripción |
|---|---|---|
status |
boolean | Si la operación tuvo éxito. |
data.id |
integer | ID del buzón. Los IDs generados, direcciones y tokens difieren para cada buzón. |
data.pin_protected |
boolean | Indica si este buzón tiene protección con PIN. No se devuelve el PIN ni el hash del PIN. |
data.email |
string | Dirección completa del buzón generada. |
data.domain |
string | Dominio del buzón generado. |
data.provider |
string | Proveedor de buzón: standard, gmail_alias, o outlook_alias. |
data.expire_at |
string|null | Fecha de expiración efectiva como una marca de tiempo ISO-8601, o null para un buzón ilimitado. |
data.expires_in_seconds |
number|null | Segundos restantes no negativos al calcular; pueden ser segundos fraccionarios. Null significa ilimitado, no cero. |
data.mailbox_state |
string | Estado actual del buzón: activo, en pausa, expirado o inactivo. |
data.receiving_enabled |
boolean | Si este buzón actualmente acepta mensajes entrantes. |
data.message_count |
integer | Recuento total de mensajes conocido; puede reflejar la última sincronización del buzón. |
data.unread_message_count |
integer | Recuento de mensajes no leídos conocidos; puede reflejar la última sincronización del buzón. |
data.last_message_received_at |
string|null | Última hora conocida de mensaje recibido en formato ISO-8601, o null cuando no esté disponible. |
data.message_count_synced_at |
string|null | Última hora de sincronización del recuento de mensajes en formato ISO-8601, o null antes de la sincronización. |
data.created_at |
string|null | Hora de creación del buzón en formato ISO-8601. |
data.email_token |
string | Referencia opaca de buzón cifrado. No reemplaza la autenticación Bearer, las verificaciones de propiedad o la autorización PIN. |
data.pin_grant |
object | Condicional: la creación de buzón protegido por PIN activo devuelve esta concesión de lectura; la creación ordinaria sin protección la omite. |
data.pin_grant.mailbox_id |
integer | ID del buzón al que está vinculada la concesión de lectura condicional. |
data.pin_grant.unlock_token |
string | Token de lectura opaco para X-Mailbox-Unlock con la misma credencial del propietario. Manténgalo privado y en memoria; una concesión de lectura no autoriza la eliminación. |
data.pin_grant.scope |
string | El alcance leído para la concesión de creación condicional. |
data.pin_grant.idle_timeout_seconds |
integer | Tiempo de inactividad permitido para la concesión de lectura, normalmente 3600 segundos. |
data.pin_grant.absolute_timeout_seconds |
integer | Duración máxima del permiso de lectura, normalmente 86400 segundos. |
data.pin_grant.expires_at |
string | Vencimiento actual de la concesión de lectura en formato ISO-8601. |
data.pin_grant.absolute_expires_at |
string | Vencimiento absoluto de la concesión de lectura en formato ISO-8601. Los cambios de seguridad pueden revocar la concesión antes. |
Actualizar / Cambiar Buzón
Crear o seleccionar un buzón en el nuevo nombre de usuario y dominio después de verificar la propiedad del buzón actual. Esto no renombra el buzón antiguo ni cambia su duración en el lugar. Cuando el destino difiere, el buzón antiguo permanece en el historial y puede ser pausado por los límites de buzones activos. Reutilizar su propio destino activo reaplica su duración solicitada o la predeterminada del plan.
| Parámetro | Ubicación | Tipo | Estado | Descripción |
|---|---|---|---|---|
email
|
path | string | requerido |
Dirección de correo electrónico completa actual del buzón propio a cambiar. Codifique en URL cada segmento de ruta; codifique un signo más como %2B.
|
username
|
path | string | requerido |
Nuevo nombre de usuario deseado: de 2 a 64 caracteres alfanuméricos; sujeto a permiso de nombre de usuario personalizado.
|
domain
|
path | string | requerido |
Nuevo nombre de dominio permitido.
|
lifetime
|
body | string | opcional |
valores permitidos:
10m — 10 minutos
1h — 1 Hora
2h — 2 Horas
1d — 1 día
1w — 1 Semana
1m — 30 Días
3m — 90 días
6m — 180 días
1y — 365 días
unlimited — Ilimitado
Predeterminado:
Vida útil predeterminada del plan
|
pin_enabled
|
body | boolean | opcional |
Protección opcional con PIN para el nuevo buzón, cuando lo permita su plan. No cambia el PIN de un buzón existente.
Predeterminado:
false
|
pin
|
body | string | opcional |
Requerido cuando pin_enabled es true: un PIN de 6 a 8 dígitos, enviado como una cadena para preservar los ceros iniciales.
|
pin_confirmation
|
body | string | opcional |
Requerido cuando pin_enabled es true. Debe coincidir exactamente con pin.
|
Idempotency-Key
|
header | string | opcional |
Requerido para la creación o eliminación protegida por PIN: una clave estable de 16 a 128 caracteres. Reintente la solicitud idéntica con la misma clave para evitar trabajo duplicado.
|
X-Mailbox-Unlock
|
header | string | opcional |
Encabezado, solo buzones protegidos: use un unlock_token de lectura. Primero haga POST pin y scope=read a la URL de desbloqueo PIN. Mantenga su autenticación Bearer normal. <code>https://v1.tempmailg.com/api/mailboxes/{mailbox}/pin/unlock</code>
|
lifetime (valores permitidos: 10m, 1h, 2h, 1d, 1w, 1m, 3m, 6m, 1y, unlimited). Omita la duración, o déjela vacía, para usar la Duración de Correo Electrónico Predeterminada configurada para su plan mensual/anual actual. Envíe una duración permitida, como 1h, para sobrescribir esa predeterminada. Ilimitado se usa solo cuando está configurado como la opción predeterminada del plan o se solicita explícitamente y está permitido. Los parámetros del cuerpo mailbox_lifetime y email_lifetime también son aceptados; el primer valor no vacío gana en este orden: lifetime, mailbox_lifetime, email_lifetime. Los valores inválidos o no permitidos devuelven HTTP 422 en lugar de seleccionar silenciosamente un valor predeterminado.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'
Respuesta ilustrativa usando datos sintéticos. Los IDs, direcciones, tokens, marcas de tiempo, límites y recuentos del plan varían. Las duraciones de muestra no sobrescriben la configuración predeterminada de su plan. Las descripciones de los campos de respuesta identifican los campos que pueden ser nulos y los específicos del proveedor.
Ejemplo de respuesta
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:28:04+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:18:04+00:00",
"email_token": "encrypted-email-token"
}
}
| Campo | Tipo | Descripción |
|---|---|---|
status |
boolean | Si la operación tuvo éxito. |
data.id |
integer | ID del buzón. Los IDs generados, direcciones y tokens difieren para cada buzón. |
data.pin_protected |
boolean | Indica si este buzón tiene protección con PIN. No se devuelve el PIN ni el hash del PIN. |
data.email |
string | Dirección completa del buzón generada. |
data.domain |
string | Dominio del buzón generado. |
data.provider |
string | Proveedor de buzón: standard, gmail_alias, o outlook_alias. |
data.expire_at |
string|null | Fecha de expiración efectiva como una marca de tiempo ISO-8601, o null para un buzón ilimitado. |
data.expires_in_seconds |
number|null | Segundos restantes no negativos al calcular; pueden ser segundos fraccionarios. Null significa ilimitado, no cero. |
data.mailbox_state |
string | Estado actual del buzón: activo, en pausa, expirado o inactivo. |
data.receiving_enabled |
boolean | Si este buzón actualmente acepta mensajes entrantes. |
data.message_count |
integer | Recuento total de mensajes conocido; puede reflejar la última sincronización del buzón. |
data.unread_message_count |
integer | Recuento de mensajes no leídos conocidos; puede reflejar la última sincronización del buzón. |
data.last_message_received_at |
string|null | Última hora conocida de mensaje recibido en formato ISO-8601, o null cuando no esté disponible. |
data.message_count_synced_at |
string|null | Última hora de sincronización del recuento de mensajes en formato ISO-8601, o null antes de la sincronización. |
data.created_at |
string|null | Hora de creación del buzón en formato ISO-8601. |
data.email_token |
string | Referencia opaca de buzón cifrado. No reemplaza la autenticación Bearer, las verificaciones de propiedad o la autorización PIN. |
data.pin_grant |
object | Condicional: la creación de buzón protegido por PIN activo devuelve esta concesión de lectura; la creación ordinaria sin protección la omite. |
data.pin_grant.mailbox_id |
integer | ID del buzón al que está vinculada la concesión de lectura condicional. |
data.pin_grant.unlock_token |
string | Token de lectura opaco para X-Mailbox-Unlock con la misma credencial del propietario. Manténgalo privado y en memoria; una concesión de lectura no autoriza la eliminación. |
data.pin_grant.scope |
string | El alcance leído para la concesión de creación condicional. |
data.pin_grant.idle_timeout_seconds |
integer | Tiempo de inactividad permitido para la concesión de lectura, normalmente 3600 segundos. |
data.pin_grant.absolute_timeout_seconds |
integer | Duración máxima del permiso de lectura, normalmente 86400 segundos. |
data.pin_grant.expires_at |
string | Vencimiento actual de la concesión de lectura en formato ISO-8601. |
data.pin_grant.absolute_expires_at |
string | Vencimiento absoluto de la concesión de lectura en formato ISO-8601. Los cambios de seguridad pueden revocar la concesión antes. |
Eliminar buzón
Eliminar un buzón propio e invocar su limpieza de mensajes y archivos. Los registros de buzón retenidos pueden ser eliminados suavemente internamente; la dirección ya no es utilizable a través de la API.
| Parámetro | Ubicación | Tipo | Estado | Descripción |
|---|---|---|---|---|
email
|
path | string | requerido |
Dirección de correo electrónico completa del buzón propio a eliminar. Codifique la dirección en URL; codifique el signo más como %2B.
|
X-Mailbox-Unlock
|
header | string | opcional |
Encabezado, solo buzones protegidos: use el token de desbloqueo de eliminación de un solo uso unlock_token. Primero POST pin, scope=delete y la acción/target_id devuelta por la respuesta 423 a la URL de desbloqueo PIN. Un token de lectura no puede eliminar. <code>https://v1.tempmailg.com/api/mailboxes/{mailbox}/pin/unlock</code>
|
Idempotency-Key
|
header | string | opcional |
Requerido para la creación o eliminación protegida por PIN: una clave estable de 16 a 128 caracteres. Reintente la solicitud idéntica con la misma clave para evitar trabajo duplicado.
|
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'
Respuesta ilustrativa usando datos sintéticos. Los IDs, direcciones, tokens, marcas de tiempo, límites y recuentos del plan varían. Las duraciones de muestra no sobrescriben la configuración predeterminada de su plan. Las descripciones de los campos de respuesta identifican los campos que pueden ser nulos y los específicos del proveedor.
Ejemplo de respuesta
200 OK • JSON{
"status": true,
"message": "Email has been successfully deleted."
}
| Campo | Tipo | Descripción |
|---|---|---|
status |
boolean | Si la operación tuvo éxito. |
message |
string | Resultado de la eliminación. Un recurso faltante devuelve HTTP 404. |
Alias de Gmail y Outlook
Generar buzones alias de Gmail y Outlook/Hotmail de alta reputación.
Crear alias de Gmail
Crear un nuevo buzón temporal de alias de Gmail, propiedad del usuario autenticado.
| Parámetro | Ubicación | Tipo | Estado | Descripción |
|---|---|---|---|---|
mode
|
body | string | opcional |
Modo de generación: auto, dot, plus o plus_dot. También acepta gmail_alias_mode. Si la selección de estilo no está permitida, se usa auto.
Predeterminado:
auto
|
username
|
body | string | opcional |
Sufijo de alias personalizado opcional: de 2 a 32 letras o dígitos ASCII, normalizado a minúsculas; sujeto a permiso de la función. También acepta custom_username o alias_username.
Predeterminado:
Generado automáticamente
|
domain
|
body | string | opcional |
Utilice aleatorio, gmail.com o googlemail.com; alias_domain también es aceptado. La omisión o la falta de permiso de selección de dominio utiliza aleatorio.
Predeterminado:
random
|
lifetime
|
body | string | opcional |
valores permitidos:
10m — 10 minutos
1h — 1 Hora
2h — 2 Horas
1d — 1 día
1w — 1 Semana
1m — 30 Días
3m — 90 días
6m — 180 días
1y — 365 días
unlimited — Ilimitado
Predeterminado:
Vida útil predeterminada del plan
|
pin_enabled
|
body | boolean | opcional |
Protección opcional con PIN para el nuevo buzón, cuando lo permita su plan. No cambia el PIN de un buzón existente.
Predeterminado:
false
|
pin
|
body | string | opcional |
Requerido cuando pin_enabled es true: un PIN de 6 a 8 dígitos, enviado como una cadena para preservar los ceros iniciales.
|
pin_confirmation
|
body | string | opcional |
Requerido cuando pin_enabled es true. Debe coincidir exactamente con pin.
|
Idempotency-Key
|
header | string | opcional |
Requerido para la creación o eliminación protegida por PIN: una clave estable de 16 a 128 caracteres. Reintente la solicitud idéntica con la misma clave para evitar trabajo duplicado.
|
mode (auto, dot, plus, plus_dot), username (nombre de usuario de alias personalizado), domain (p. ej. gmail.com, googlemail.com), lifetime (valores permitidos: 10m, 1h, 2h, 1d, 1w, 1m, 3m, 6m, 1y, unlimited). Omita la duración, o déjela vacía, para usar la Duración de Correo Electrónico Predeterminada configurada para su plan mensual/anual actual. Envíe una duración permitida, como 1h, para sobrescribir esa predeterminada. Ilimitado se usa solo cuando está configurado como la opción predeterminada del plan o se solicita explícitamente y está permitido. Los parámetros del cuerpo mailbox_lifetime y email_lifetime también son aceptados; el primer valor no vacío gana en este orden: lifetime, mailbox_lifetime, email_lifetime. Los valores inválidos o no permitidos devuelven HTTP 422 en lugar de seleccionar silenciosamente un valor predeterminado.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'
Respuesta ilustrativa usando datos sintéticos. Los IDs, direcciones, tokens, marcas de tiempo, límites y recuentos del plan varían. Las duraciones de muestra no sobrescriben la configuración predeterminada de su plan. Las descripciones de los campos de respuesta identifican los campos que pueden ser nulos y los específicos del proveedor.
Ejemplo de respuesta
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:18:04+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:18:04+00:00",
"email_token": "encrypted-email-token"
}
}
| Campo | Tipo | Descripción |
|---|---|---|
status |
boolean | Si la operación tuvo éxito. |
data.id |
integer | ID del buzón. Los IDs generados, direcciones y tokens difieren para cada buzón. |
data.pin_protected |
boolean | Indica si este buzón tiene protección con PIN. No se devuelve el PIN ni el hash del PIN. |
data.email |
string | Dirección completa del buzón generada. |
data.domain |
string | Dominio del buzón generado. |
data.provider |
string | Proveedor de buzón: standard, gmail_alias, o outlook_alias. |
data.expire_at |
string|null | Fecha de expiración efectiva como una marca de tiempo ISO-8601, o null para un buzón ilimitado. |
data.expires_in_seconds |
number|null | Segundos restantes no negativos al calcular; pueden ser segundos fraccionarios. Null significa ilimitado, no cero. |
data.mailbox_state |
string | Estado actual del buzón: activo, en pausa, expirado o inactivo. |
data.receiving_enabled |
boolean | Si este buzón actualmente acepta mensajes entrantes. |
data.message_count |
integer | Recuento total de mensajes conocido; puede reflejar la última sincronización del buzón. |
data.unread_message_count |
integer | Recuento de mensajes no leídos conocidos; puede reflejar la última sincronización del buzón. |
data.last_message_received_at |
string|null | Última hora conocida de mensaje recibido en formato ISO-8601, o null cuando no esté disponible. |
data.message_count_synced_at |
string|null | Última hora de sincronización del recuento de mensajes en formato ISO-8601, o null antes de la sincronización. |
data.created_at |
string|null | Hora de creación del buzón en formato ISO-8601. |
data.email_token |
string | Referencia opaca de buzón cifrado. No reemplaza la autenticación Bearer, las verificaciones de propiedad o la autorización PIN. |
data.pin_grant |
object | Condicional: la creación de buzón protegido por PIN activo devuelve esta concesión de lectura; la creación ordinaria sin protección la omite. |
data.pin_grant.mailbox_id |
integer | ID del buzón al que está vinculada la concesión de lectura condicional. |
data.pin_grant.unlock_token |
string | Token de lectura opaco para X-Mailbox-Unlock con la misma credencial del propietario. Manténgalo privado y en memoria; una concesión de lectura no autoriza la eliminación. |
data.pin_grant.scope |
string | El alcance leído para la concesión de creación condicional. |
data.pin_grant.idle_timeout_seconds |
integer | Tiempo de inactividad permitido para la concesión de lectura, normalmente 3600 segundos. |
data.pin_grant.absolute_timeout_seconds |
integer | Duración máxima del permiso de lectura, normalmente 86400 segundos. |
data.pin_grant.expires_at |
string | Vencimiento actual de la concesión de lectura en formato ISO-8601. |
data.pin_grant.absolute_expires_at |
string | Vencimiento absoluto de la concesión de lectura en formato ISO-8601. Los cambios de seguridad pueden revocar la concesión antes. |
Dominios de alias de Outlook
Obtener dominios alias activos de Outlook / Hotmail disponibles para la generación de buzones.
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'
Respuesta ilustrativa usando datos sintéticos. Los IDs, direcciones, tokens, marcas de tiempo, límites y recuentos del plan varían. Las duraciones de muestra no sobrescriben la configuración predeterminada de su plan. Las descripciones de los campos de respuesta identifican los campos que pueden ser nulos y los específicos del proveedor.
Ejemplo de respuesta
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 | Descripción |
|---|---|---|
status |
boolean | Si la operación tuvo éxito. |
data.domains |
array | Dominios Outlook/Hotmail activos; una matriz vacía es válida. |
data.domains[].domain |
string | Nombre de dominio disponible. |
data.domains[].type |
string | Etiqueta de proveedor legible. |
data.domains[].selectable |
boolean | Si su cuenta puede elegir explícitamente este dominio. |
data.domains[].locked |
boolean | Si la selección explícita de dominio está bloqueada para su cuenta. |
data.domains[].disabled_reason |
string|null | Razón por la que la selección de dominio está bloqueada, o nulo cuando es seleccionable. |
Crear alias de Outlook
Crear un nuevo buzón temporal de alias de Outlook / Hotmail propiedad del usuario autenticado.
| Parámetro | Ubicación | Tipo | Estado | Descripción |
|---|---|---|---|---|
domain
|
body | string | opcional |
Use aleatorio o un dominio de GET /outlook-alias/domains; outlook_alias_domain también es aceptado. Sin permiso de selección, se usa aleatorio.
Predeterminado:
Dominio disponible aleatorio
|
username
|
body | string | opcional |
Sufijo de alias personalizado opcional: de 2 a 32 letras o dígitos ASCII, normalizado a minúsculas; sujeto a permiso de la función. También acepta custom_username o alias_username.
Predeterminado:
Generado automáticamente
|
lifetime
|
body | string | opcional |
valores permitidos:
10m — 10 minutos
1h — 1 Hora
2h — 2 Horas
1d — 1 día
1w — 1 Semana
1m — 30 Días
3m — 90 días
6m — 180 días
1y — 365 días
unlimited — Ilimitado
Predeterminado:
Vida útil predeterminada del plan
|
pin_enabled
|
body | boolean | opcional |
Protección opcional con PIN para el nuevo buzón, cuando lo permita su plan. No cambia el PIN de un buzón existente.
Predeterminado:
false
|
pin
|
body | string | opcional |
Requerido cuando pin_enabled es true: un PIN de 6 a 8 dígitos, enviado como una cadena para preservar los ceros iniciales.
|
pin_confirmation
|
body | string | opcional |
Requerido cuando pin_enabled es true. Debe coincidir exactamente con pin.
|
Idempotency-Key
|
header | string | opcional |
Requerido para la creación o eliminación protegida por PIN: una clave estable de 16 a 128 caracteres. Reintente la solicitud idéntica con la misma clave para evitar trabajo duplicado.
|
domain (p. ej. outlook.com, hotmail.com), username (nombre de usuario de alias personalizado), lifetime (valores permitidos: 10m, 1h, 2h, 1d, 1w, 1m, 3m, 6m, 1y, unlimited). Omita la duración, o déjela vacía, para usar la Duración de Correo Electrónico Predeterminada configurada para su plan mensual/anual actual. Envíe una duración permitida, como 1h, para sobrescribir esa predeterminada. Ilimitado se usa solo cuando está configurado como la opción predeterminada del plan o se solicita explícitamente y está permitido. Los parámetros del cuerpo mailbox_lifetime y email_lifetime también son aceptados; el primer valor no vacío gana en este orden: lifetime, mailbox_lifetime, email_lifetime. Los valores inválidos o no permitidos devuelven HTTP 422 en lugar de seleccionar silenciosamente un valor predeterminado.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'
Respuesta ilustrativa usando datos sintéticos. Los IDs, direcciones, tokens, marcas de tiempo, límites y recuentos del plan varían. Las duraciones de muestra no sobrescriben la configuración predeterminada de su plan. Las descripciones de los campos de respuesta identifican los campos que pueden ser nulos y los específicos del proveedor.
Ejemplo de respuesta
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:18:04+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:18:04+00:00",
"email_token": "encrypted-email-token"
}
}
| Campo | Tipo | Descripción |
|---|---|---|
status |
boolean | Si la operación tuvo éxito. |
data.id |
integer | ID del buzón. Los IDs generados, direcciones y tokens difieren para cada buzón. |
data.pin_protected |
boolean | Indica si este buzón tiene protección con PIN. No se devuelve el PIN ni el hash del PIN. |
data.email |
string | Dirección completa del buzón generada. |
data.domain |
string | Dominio del buzón generado. |
data.provider |
string | Proveedor de buzón: standard, gmail_alias, o outlook_alias. |
data.expire_at |
string|null | Fecha de expiración efectiva como una marca de tiempo ISO-8601, o null para un buzón ilimitado. |
data.expires_in_seconds |
number|null | Segundos restantes no negativos al calcular; pueden ser segundos fraccionarios. Null significa ilimitado, no cero. |
data.mailbox_state |
string | Estado actual del buzón: activo, en pausa, expirado o inactivo. |
data.receiving_enabled |
boolean | Si este buzón actualmente acepta mensajes entrantes. |
data.message_count |
integer | Recuento total de mensajes conocido; puede reflejar la última sincronización del buzón. |
data.unread_message_count |
integer | Recuento de mensajes no leídos conocidos; puede reflejar la última sincronización del buzón. |
data.last_message_received_at |
string|null | Última hora conocida de mensaje recibido en formato ISO-8601, o null cuando no esté disponible. |
data.message_count_synced_at |
string|null | Última hora de sincronización del recuento de mensajes en formato ISO-8601, o null antes de la sincronización. |
data.created_at |
string|null | Hora de creación del buzón en formato ISO-8601. |
data.email_token |
string | Referencia opaca de buzón cifrado. No reemplaza la autenticación Bearer, las verificaciones de propiedad o la autorización PIN. |
data.pin_grant |
object | Condicional: la creación de buzón protegido por PIN activo devuelve esta concesión de lectura; la creación ordinaria sin protección la omite. |
data.pin_grant.mailbox_id |
integer | ID del buzón al que está vinculada la concesión de lectura condicional. |
data.pin_grant.unlock_token |
string | Token de lectura opaco para X-Mailbox-Unlock con la misma credencial del propietario. Manténgalo privado y en memoria; una concesión de lectura no autoriza la eliminación. |
data.pin_grant.scope |
string | El alcance leído para la concesión de creación condicional. |
data.pin_grant.idle_timeout_seconds |
integer | Tiempo de inactividad permitido para la concesión de lectura, normalmente 3600 segundos. |
data.pin_grant.absolute_timeout_seconds |
integer | Duración máxima del permiso de lectura, normalmente 86400 segundos. |
data.pin_grant.expires_at |
string | Vencimiento actual de la concesión de lectura en formato ISO-8601. |
data.pin_grant.absolute_expires_at |
string | Vencimiento absoluto de la concesión de lectura en formato ISO-8601. Los cambios de seguridad pueden revocar la concesión antes. |
Mensajes y archivos adjuntos
Obtenga bandejas de entrada entrantes, lea mensajes completos en HTML/texto y transmita los archivos adjuntos.
Listar mensajes del buzón
Recuperar los resúmenes de mensajes disponibles y los metadatos del buzón. Los escaneos estándar de la bandeja de entrada devuelven un lote reciente de hasta 25 mensajes; este no es un endpoint paginado de historial completo. Use GET /messages/{messageId} para obtener los cuerpos completos y los archivos adjuntos.
| Parámetro | Ubicación | Tipo | Estado | Descripción |
|---|---|---|---|---|
email
|
query | string | requerido |
Dirección de correo electrónico completa del buzón propio del que leer los mensajes. Codifique la consulta en URL; codifique el signo más como %2B.
|
X-Mailbox-Unlock
|
header | string | opcional |
Encabezado, solo buzones protegidos: use un unlock_token de lectura. Primero haga POST pin y scope=read a la URL de desbloqueo PIN. Mantenga su autenticación Bearer normal. <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'
Respuesta ilustrativa usando datos sintéticos. Los IDs, direcciones, tokens, marcas de tiempo, límites y recuentos del plan varían. Las duraciones de muestra no sobrescriben la configuración predeterminada de su plan. Las descripciones de los campos de respuesta identifican los campos que pueden ser nulos y los específicos del proveedor.
Ejemplo de respuesta
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:18:04",
"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:18:04+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:18:04+00:00",
"message_count_synced_at": "2026-11-19T02:18:04+00:00"
}
| Campo | Tipo | Descripción |
|---|---|---|
status |
boolean | Si la operación tuvo éxito. |
mailbox |
string | Dirección del buzón cuyos mensajes fueron solicitados. |
email_token |
string | Referencia opaca de buzón cifrado; aún se requiere autenticación normal. |
mailbox_provider |
string | Proveedor de buzón: standard, gmail_alias, o outlook_alias. |
messages |
array | Resúmenes de mensajes. Un buzón vacío devuelve una matriz vacía; recupera un solo mensaje para su cuerpo y archivos adjuntos. |
expire_at |
string|null | Fecha de expiración efectiva como una marca de tiempo ISO-8601, o null para un buzón ilimitado. |
expires_in_seconds |
number|null | Segundos restantes no negativos al calcular; pueden ser segundos fraccionarios. Null significa ilimitado, no cero. |
mailbox_state |
string | Estado actual del buzón: activo, en pausa, expirado o inactivo. |
receiving_enabled |
boolean | Si este buzón actualmente acepta mensajes entrantes. |
message_count |
integer | Recuento total de mensajes conocido; puede reflejar la última sincronización del buzón. |
unread_message_count |
integer | Recuento de mensajes no leídos conocidos; puede reflejar la última sincronización del buzón. |
last_message_received_at |
string|null | Última hora conocida de mensaje recibido en formato ISO-8601, o null cuando no esté disponible. |
message_count_synced_at |
string|null | Última hora de sincronización del recuento de mensajes en formato ISO-8601, o null antes de la sincronización. |
mailbox_limit.limit |
integer | Límite activo de buzones para este proveedor; -1 significa ilimitado. |
mailbox_limit.limit_label |
string | Etiqueta de visualización para el límite del buzón. |
mailbox_limit.active_count |
integer | Número de buzones activos para este proveedor. |
mailbox_limit.paused_count |
integer | Número de buzones en pausa para este proveedor. |
mailbox_limit.paused_mailboxes |
array<string> | Direcciones pausadas por el límite del buzón. |
mailbox_limit.remaining |
integer | Ranuras de buzón activo restantes; -1 significa ilimitado. Esto no es cuota de solicitudes API. |
mailbox_limit.remaining_label |
string | Etiqueta de visualización para los espacios de buzón restantes. |
mailbox_limit.reached |
boolean | Si se ha alcanzado el límite de buzones activos. |
mailbox_limit.blocked |
boolean | Si el límite de buzón activo es cero. |
mailbox_limit.provider |
string|null | Proveedor al que se aplica el límite del buzón. |
messages[].id |
string | ID de mensaje opaco utilizado por los puntos finales de mensaje único, eliminación y adjunto. |
messages[].is_seen |
boolean | Si el mensaje está marcado como leído. |
messages[].subject |
string | Asunto del mensaje. |
messages[].from |
string | Nombre para mostrar o dirección del remitente. |
messages[].from_email |
string | Dirección de correo electrónico del remitente. |
messages[].receivedAt |
string | Hora de recepción en la zona horaria de la aplicación, formateada como YYYY-MM-DD HH:mm:ss. |
messages[].otp |
string|null | Detectado código de un solo uso cuando esté disponible y permitido; de lo contrario null. |
messages[].otp_locked |
boolean | Si un código de un solo uso detectado está oculto por los permisos de la función. |
messages[].verification_link |
string|null | URL de verificación detectada cuando está disponible y permitido; de lo contrario, null. |
messages[].verification_link_locked |
boolean | Si un enlace de verificación detectado está oculto por los permisos de la función. |
messages[].from_name |
string|null | Campo de resumen de Outlook: nombre del remitente original. Ausente de los resúmenes estándar y de Gmail. |
messages[].snippet |
string|null | Campo de resumen de Outlook: vista previa corta del mensaje. |
messages[].received_at |
string|null | Campo de resumen de Outlook: hora de recepción en formato ISO-8601, cuando se conozca. |
messages[].has_attachments |
boolean | Campo de resumen de Outlook: si existe metadata de adjuntos. La disponibilidad de descarga se verifica por separado. |
Obtener mensaje único
Recupera un mensaje propio mediante su ID de mensaje opaco. Devuelve los formatos del cuerpo y los metadatos de los archivos adjuntos. Los campos del cuerpo dependen del formato del mensaje; Outlook agrega campos específicos del proveedor que se enumeran a continuación.
| Parámetro | Ubicación | Tipo | Estado | Descripción |
|---|---|---|---|---|
messageId
|
path | string | requerido |
ID de mensaje único devuelto en la lista de mensajes.
|
X-Mailbox-Unlock
|
header | string | opcional |
Encabezado, solo buzones protegidos: use un unlock_token de lectura. Primero haga POST pin y scope=read a la URL de desbloqueo PIN. Mantenga su autenticación Bearer normal. <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'
Respuesta ilustrativa usando datos sintéticos. Los IDs, direcciones, tokens, marcas de tiempo, límites y recuentos del plan varían. Las duraciones de muestra no sobrescriben la configuración predeterminada de su plan. Las descripciones de los campos de respuesta identifican los campos que pueden ser nulos y los específicos del proveedor.
Ejemplo de respuesta
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:18:04",
"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 | Descripción |
|---|---|---|
status |
boolean | Si la operación tuvo éxito. |
data.id |
string | ID de mensaje opaco. |
data.is_seen |
boolean | Estado de lectura del mensaje. Leer puede marcarlo como visto; los datos en caché pueden reflejar un estado anterior. |
data.subject |
string | Asunto del mensaje. |
data.from |
string | Nombre para mostrar o dirección del remitente. |
data.from_email |
string | Dirección de correo electrónico del remitente. |
data.to |
string | Dirección del buzón del destinatario. |
data.mailbox_provider |
string | Proveedor de buzón: standard, gmail_alias, o outlook_alias. |
data.receivedAt |
string | Hora de recepción en la zona horaria de la aplicación, formateada como YYYY-MM-DD HH:mm:ss. |
data.html |
boolean | Si el mensaje tiene un cuerpo HTML. |
data.html_content |
string | Cuerpo HTML cuando está presente. Los mensajes estándar sin HTML pueden omitir este campo. Trate el contenido del mensaje como no confiable. |
data.text_content |
string | Cuerpo de texto cuando está presente; los mensajes estándar pueden contener texto escapado en un elemento pre o omitir este campo. |
data.content |
string | Cuerpo preferido para mostrar, normalmente HTML cuando está disponible. |
data.attachments |
array | Metadatos del adjunto, o una matriz vacía. Las descargas requieren autenticación normal y la autorización de PIN aplicable. |
data.attachments[].name |
string | Nombre de archivo para codificar en URL como un solo segmento de ruta al descargar. |
data.attachments[].size |
integer | Tamaño del adjunto en bytes. |
data.attachments[].url |
string | Se añadió la URL de descarga de la API de usuario autenticado a los archivos adjuntos con un nombre de archivo. Una URL no garantiza que el archivo local esté disponible. |
data.attachments[].extension |
string | Campo de metadatos estándar/Gmail: extensión de archivo cuando se proporciona. |
data.attachments[].id |
string | Campo de metadatos de Outlook: ID de adjunto del proveedor. |
data.attachments[].content_type |
string | Campo de metadatos de Outlook: tipo de contenido MIME. |
data.from_name |
string|null | Campo de detalle de Outlook: nombre del remitente original. |
data.to_email |
string|null | Campo de detalle de Outlook: dirección del destinatario original. |
data.received_at |
string|null | Campo de detalle de Outlook: hora recibida en ISO-8601. |
data.has_html |
boolean | Campo de detalle de Outlook: si existe un cuerpo HTML. |
Eliminar mensaje
Eliminar un mensaje único propiedad del usuario.
| Parámetro | Ubicación | Tipo | Estado | Descripción |
|---|---|---|---|---|
messageId
|
path | string | requerido |
Cadena de ID de mensaje única para eliminar permanentemente.
|
X-Mailbox-Unlock
|
header | string | opcional |
Encabezado, solo buzones protegidos: use el token de desbloqueo de eliminación de un solo uso unlock_token. Primero POST pin, scope=delete y la acción/target_id devuelta por la respuesta 423 a la URL de desbloqueo PIN. Un token de lectura no puede eliminar. <code>https://v1.tempmailg.com/api/mailboxes/{mailbox}/pin/unlock</code>
|
Idempotency-Key
|
header | string | opcional |
Requerido para la creación o eliminación protegida por PIN: una clave estable de 16 a 128 caracteres. Reintente la solicitud idéntica con la misma clave para evitar trabajo duplicado.
|
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'
Respuesta ilustrativa usando datos sintéticos. Los IDs, direcciones, tokens, marcas de tiempo, límites y recuentos del plan varían. Las duraciones de muestra no sobrescriben la configuración predeterminada de su plan. Las descripciones de los campos de respuesta identifican los campos que pueden ser nulos y los específicos del proveedor.
Ejemplo de respuesta
200 OK • JSON{
"status": true,
"message": "Message was deleted successfully."
}
| Campo | Tipo | Descripción |
|---|---|---|
status |
boolean | Si la operación tuvo éxito. |
message |
string | Resultado de la eliminación. Un recurso faltante devuelve HTTP 404. |
Descargar archivo adjunto
Descargar un archivo adjunto de un mensaje propiedad del usuario.
| Parámetro | Ubicación | Tipo | Estado | Descripción |
|---|---|---|---|---|
messageId
|
path | string | requerido |
ID del mensaje que contiene el archivo.
|
filename
|
path | string | requerido |
Nombre de archivo y extensión del adjunto a descargar.
|
X-Mailbox-Unlock
|
header | string | opcional |
Encabezado, solo buzones protegidos: use un unlock_token de lectura. Primero haga POST pin y scope=read a la URL de desbloqueo PIN. Mantenga su autenticación Bearer normal. <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 | Descripción |
|---|---|---|
Content-Disposition |
header | La respuesta exitosa descarga el nombre de archivo solicitado. |
body |
binary | Bytes del archivo en caso de éxito, no JSON. Los errores devuelven JSON con un estado que no es 2xx. |
Límites de velocidad y cuotas
Supervise los presupuestos de solicitudes en tiempo real, los límites de velocidad y las cuotas de cuenta sin consumir créditos.
Límite de velocidad y cuota
Verifique su límite de velocidad actual y el estado de la cuota sin consumir ningún uso de API. Este endpoint está libre de cuota y no deduce créditos mensuales de API (límite de protección contra abuso: 60 solicitudes/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'
Respuesta ilustrativa usando datos sintéticos. Los IDs, direcciones, tokens, marcas de tiempo, límites y recuentos del plan varían. Las duraciones de muestra no sobrescriben la configuración predeterminada de su plan. Las descripciones de los campos de respuesta identifican los campos que pueden ser nulos y los específicos del proveedor.
Ejemplo de respuesta
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 | Descripción |
|---|---|---|
data.limit |
integer|string | Límite de solicitudes por minuto de la cuenta. La cadena unlimited denota un presupuesto ilimitado por minuto; esto es independiente de la cuota mensual. |
data.remaining |
integer|string | Ranuras de presupuesto de minutos restantes de la cuenta, o la cadena unlimited. Un valor positivo no significa que queden créditos de API. |
data.reset |
integer | Segundos para la ventana de minuto de la cuenta, no el restablecimiento mensual de la cuota. Los presupuestos de minuto deshabilitados o ilimitados pueden conservar un valor nominal de 60 segundos; esto no garantiza el acceso después de esperar. |
data.plan |
string | Etiqueta del plan actual. El nombre legible del plan se proporciona por separado en data.quota.plan_name. |
data.quota.enabled |
boolean | Indica si el acceso global y de plan/crédito a la API está habilitado. Esto no indica la capacidad restante ni reemplaza el interruptor de API del usuario. |
data.quota.user_api_status |
boolean | Si el usuario ha activado su interruptor de API de usuario. Las operaciones requieren este interruptor así como acceso habilitado y capacidad disponible. |
data.quota.plan_name |
string | Nombre legible del plan actual. |
data.quota.period |
string | Periodo de uso de calendario-mes en formato YYYY-MM, usando la zona horaria de la aplicación; no necesariamente el período de facturación de la suscripción. |
data.quota.base_limit |
integer | Asignación base del plan mensual. Un valor de -1 significa ilimitado. |
data.quota.extra_requests |
integer | Asignación mensual adicional concedida para el período de uso actual; separada de los créditos comprados. |
data.quota.monthly_limit |
integer | Asignación base más solicitudes extra del período actual. Un valor de -1 significa ilimitado. Los créditos comprados no están incluidos. |
data.quota.monthly_remaining |
integer|null | Asignación mensual finita restante, o null cuando la cuota mensual es ilimitada. Null no debe interpretarse como cero. |
data.quota.used |
integer | Operaciones API exitosas y contabilizadas en el período de uso actual, incluidas las operaciones que usan créditos. Las verificaciones de estado no aumentan este valor. |
data.quota.purchased_credits |
integer | Saldo actual de créditos, incluidos los créditos de bonificación del plan activo. Los créditos de bonificación no deben añadirse a este saldo una segunda vez. |
data.quota.bonus_credits |
integer | Porción de bonificación del plan activo del saldo de créditos; un desglose de purchased_credits, no capacidad adicional. |
data.quota.direct_purchased_credits |
integer | Saldo de crédito excluyendo la parte de bonificación del plan activo. Este valor más bonus_credits equivale a purchased_credits. |
data.quota.remaining |
integer|null | Asignación mensual restante más el saldo de crédito actual, sin contar los bonos dos veces. Null significa cuota mensual ilimitada. Los permisos individuales de funciones y otros límites de solicitud siguen aplicando. |
data.quota.unlimited |
boolean | Si la cuota mensual es ilimitada. Esto no hace que el presupuesto de minutos de la cuenta u otros límites de funciones sean ilimitados. |
data.quota.usage_percent |
integer | Porcentaje redondeado compatible con el panel, de 0 a 100: usado dividido por usado más restante, multiplicado por 100. Incluye la capacidad de crédito disponible, por lo que recargar puede reducir el porcentaje. Es 0 para cuota ilimitada o un pool de tamaño cero; no es el porcentaje de límite de velocidad por minuto ni una decisión de acceso. |
data.quota.reset_at |
string | Marca de tiempo ISO-8601 con desplazamiento de zona horaria para el próximo restablecimiento de cuota del mes calendario. Esto no es la fecha de vencimiento de la suscripción, y el restablecimiento mensual no recarga los créditos comprados. |
status |
string | El éxito literal para este punto final de estado. Otros puntos finales de buzón exitosos usan el booleano true. |
data.monthly_limit |
integer | Alias de compatibilidad del campo data.quota correspondiente; no lo añada de nuevo al calcular los saldos. |
data.monthly_remaining |
integer|null | Alias de compatibilidad del campo data.quota correspondiente; no lo añada de nuevo al calcular los saldos. |
data.purchased_credits |
integer | Alias de compatibilidad del campo data.quota correspondiente; no lo añada de nuevo al calcular los saldos. |
Webhooks de Mailbox (Envío en tiempo real)
En lugar de consultar repetidamente la API REST (GET /messages) para verificar el correo entrante, configure Webhooks para enviar nuevos mensajes a su servidor o flujo de trabajo de automatización en tiempo real.
Eventos de Webhook admitidos
Cada webhook puede suscribirse a uno o más tipos de eventos. Su punto final recibe una notificación de evento cada vez que uno de estos disparadores se activa.
Enviado en tiempo real cada vez que un nuevo mensaje llega al buzón seleccionado.
Se envía cuando el buzón temporal expira y el procesamiento del webhook se pausa.
Enviado cuando un buzón expirado vuelve a estar activo bajo las reglas del plan.
Enviado justo antes de que el webhook y su buzón sean eliminados.
Cabeceras de Solicitud y Verificación de Firma HMAC
Cada entrega de webhook contiene encabezados de seguridad especiales. Utilice el encabezado X-TempMailg-Signature para verificar que las solicitudes entrantes fueron enviadas genuina y exclusivamente por TempMailg y no han sido alteradas.
| Nombre del encabezado | Valor de ejemplo | Descripción |
|---|---|---|
User-Agent |
TempMailg-Webhooks/1.0 | Identificador estándar para el trabajador de entrega de webhook. |
X-TempMailg-Event |
email.received | El tipo de evento que desencadenó esta entrega. |
X-TempMailg-Event-Id |
e7b1a2c3-4d5e-6f7a-8b9c-0d1e2f3a4b5c | UUID único asignado a este intento de entrega. |
X-TempMailg-Timestamp |
1725192000 | Marca de tiempo Unix epoch que indica cuándo se inició la solicitud. |
X-TempMailg-Signature |
sha256=d7a8fbb307d7809469ca933b02d82941... | Firma HMAC-SHA256 calculada a partir de {timestamp}.{raw_body} usando su secreto. |
X-TempMailg-Test |
false | Verdadero cuando se envía mediante la función "Send Test Ping" en su panel. |
La firma se calcula utilizando HMAC con SHA256 sobre la cadena:
hash_hmac('sha256', "${X-TempMailg-Timestamp}.${raw_request_body}", your_webhook_secret)
Payload de evento de ejemplo (email.received)
Entregado como application/json en el cuerpo de la solicitud HTTP POST.
{
"id": "e7b1a2c3-4d5e-6f7a-8b9c-0d1e2f3a4b5c",
"version": "1.0",
"event": "email.received",
"occurred_at": "2026-11-19T02:18:04+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:18:04+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"
}
}
Ejemplos de implementación del receptor
Seleccione su idioma para ver cómo recibir webhooks y verificar firmas HMAC de forma segura.
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]);
Plataformas compatibles e integraciones de automatización
Los webhooks de TempMailg funcionan listos para usar con puntos finales HTTPS estándar y las principales plataformas sin código/automatización:
Errores comunes y solución de problemas
Estos son los códigos de respuesta más comunes que puedes ver mientras integras la API de usuario.
Token Bearer inválido, ausente o revocado.
La propiedad, los permisos de funciones, el acceso al dominio o el tamaño del adjunto impidieron la operación. Verifique el código de respuesta y el mensaje.
El recurso no se encontró en el host permitido o no pertenece al usuario.
La clave de operación se reutilizó con detalles diferentes, hay otra operación pendiente o la seguridad del buzón cambió. Inspeccione el código antes de reintentar.
La bandeja de entrada ha caducado o está inactiva.
Parámetros inválidos, una vida útil no permitida, capacidad de alias no disponible, configuración de PIN inválida o una Idempotency-Key faltante/inválida impidió la operación.
Un buzón protegido necesita un token X-Mailbox-Unlock válido y con alcance. Use la acción y target_id de la respuesta para la eliminación. Los requisitos de bloqueo o recuperación deben resolverse antes de volver a intentarlo.
Un límite de solicitud, plan deshabilitado, cuota agotada o tiempo de enfriamiento impidió la operación. Verifique la razón y los encabezados de presupuesto disponible. Retry-After es opcional.
El servidor no pudo completar la operación. Para la creación o eliminación protegida, preserve la misma solicitud y Idempotency-Key al reintentar.
No se pudo verificar el almacenamiento de protección o la coordinación. Reintente después del retraso indicado. Esta respuesta no es un pago fallido.
Lista de verificación rápida
- 401 Unauthorized - El token Bearer está ausente, incorrecto, revocado o copiado incorrectamente.
- 403 Forbidden - El plan actual no tiene derecho de acceso a la API de usuario en este momento.
- 404 Not Found - Recurso no encontrado o parámetro inválido
- 410 Gone / Expired - La bandeja de entrada ha caducado o ya no está activa.
- 429 Rate Limited - Verifique la razón de la respuesta y los encabezados de presupuesto. Retry-After se aplica solo a límites temporales; los créditos agotados o el acceso deshabilitado pueden requerir un cambio de cuenta.
Paso recomendado siguiente
Si ha iniciado sesión, abra API Management primero y confirme su clave, estado de cuota, acceso al plan y la URL de base de la API de usuario exacta antes de depurar su aplicación externa.