Lista de verificação de configuração rápida
- Abra a página de gerenciamento de API do seu painel e crie sua chave de API pessoal.
- Copie a URL Base da API do Usuário exata mostrada lá, por exemplo https://v1.tempmailg.com/api.
- Envie cada solicitação para esse host de API com Authorization: Bearer YOUR_USER_API_KEY e Accept: application/json.
- Acompanhe sua cota mensal de solicitações na mesma página do painel e nos cabeçalhos de cota quando disponíveis nas respostas da API do usuário. Apenas solicitações bem-sucedidas 2xx contam para a cota.
Acesso à chave da API
Faça login para criar sua chave de API pessoal e visualizar detalhes de cota ao vivo.
Fluxo de autenticação
- Gere sua chave de API pessoal na página de Gerenciamento de API do painel.
- Envie a chave como um token Bearer em cada solicitação.
- Use a URL Base dedicada da API do usuário mostrada na sua página de Gerenciamento de API.
- Regenere a chave sempre que você quiser invalidar a antiga e começar a usar uma nova chave imediatamente.
Cabeçalhos necessários
Authorization: Bearer YOUR_USER_API_KEY
Accept: application/json
Cabeçalhos de Limite de Taxa e Cota
Os cabeçalhos de limite de taxa descrevem o orçamento de solicitações indicado. Os cabeçalhos de cota são incluídos quando as informações de cota estão disponíveis; as rejeições de limite por minuto não calculam sua cota mensal 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 solicitações permitidas por minuto (RPM) para o seu plano.X-RateLimit-Remaining— Solicitações RPM restantes na janela atual de um minuto.X-RateLimit-Reset— Carimbo de data/hora Unix quando a janela de limite de taxa do minuto atual é redefinida.X-Quota-Limit— Capacidade total mensal e de crédito adquirido para sua conta.X-Quota-Remaining— Solicitações de API restantes disponíveis no mês atual.X-Quota-Used— Total de solicitações de API consumidas durante o período de faturamento atual.X-Quota-Reset— Carimbo de data/hora ISO‑8601 quando sua cota mensal é redefinida.X-RateLimit-Scope— O orçamento descrito pelos cabeçalhos: account, ip, status_endpoint, ou mailbox.X-Mailbox-RateLimit-*— Orçamento separado para criação/atualização de caixa de correio. Respostas bem-sucedidas de caixa de correio mantêm o RPM da conta em X-RateLimit-*; uma rejeição apenas de caixa de correio usa o escopo da caixa de correio e sua própria janela de nova tentativa.Retry-After— Segundos até que uma nova tentativa programada seja apropriada. Um plano desativado ou cota esgotada pode exigir uma mudança de conta, portanto este cabeçalho nem sempre está presente.503 protection_unavailable— O armazenamento ou a coordenação de proteção da API está temporariamente indisponível. Tente novamente mais tarde; isso não é uma falha de pagamento ou um débito de crédito.
Gerenciamento de Caixa de Correio
Buscar domínios permitidos, criar ou alternar caixas de correio, escolher períodos de vida permitidos e excluir endereços próprios.
Listar domínios permitidos
Liste os domínios disponíveis para criar e‑mails temporários. Filtre por tipo para ver apenas domínios gratuitos, premium ou personalizados suportados pelo seu plano de assinatura.
| Parâmetro | Localização | Tipo | Status | Descrição |
|---|---|---|---|---|
type
|
query | string | opcional |
Filtro de nível de domínio. Omissão usa todos quando o acesso premium-domain está habilitado, caso contrário gratuito. Valores reconhecidos: free, basic, pro, premium, custom, ultimate, all
Padrão:
Dependente da conta
|
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'
Resposta ilustrativa usando dados sintéticos. IDs, endereços, tokens, timestamps, limites e contagens do plano variam. As durações de exemplo não substituem o padrão do seu plano. As descrições dos campos de resposta identificam campos anuláveis e específicos do provedor.
Exemplo de resposta
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 | Descrição |
|---|---|---|
status |
boolean | Se a operação foi bem-sucedida. |
data.requested_type |
string | Filtro de domínio aplicado. |
data.plan |
string | Etiqueta do plano atual. |
data.plan_name |
string | Nome legível do plano atual. |
data.allowed_types |
array<string> | Filtros de domínio disponíveis para esta conta. Um filtro reconhecido ainda pode ser proibido para o seu plano. |
data.domains |
array | Domínios selecionáveis após filtragem; um array vazio é válido. |
data.domains[].domain |
string | Nome de domínio selecionável. |
data.domains[].type |
string | Rótulo de nível de domínio legível. |
data.domains[].custom |
boolean | Se este é um domínio personalizado. |
Criar caixa de correio temporária
Crie uma caixa de correio temporária própria. Omitir nome de usuário e domínio para geração aleatória, ou fornecer um nome de usuário personalizado permitido e um domínio permitido. O parâmetro provider pode selecionar a geração de alias Gmail ou Outlook.
| Parâmetro | Localização | Tipo | Status | Descrição |
|---|---|---|---|---|
username
|
body | string | opcional |
Nome de usuário personalizado opcional: de 2 a 64 caracteres ASCII, incluindo letras, dígitos, pontos, sublinhados ou hífens. Requer permissão do plano; custom_username também é aceito.
Padrão:
Gerado aleatoriamente
|
domain
|
body | string | opcional |
Um dos domínios permitidos retornados por GET /domains. A omissão escolhe um domínio permitido aleatório.
Padrão:
Domínio permitido aleatório
|
lifetime
|
body | string | opcional |
valores permitidos:
10m — 10 Minutos
1h — 1 Hora
2h — 2 Horas
1d — 1 Dia
1w — 1 Semana
1m — 30 Dias
3m — 90 dias
6m — 180 Dias
1y — 365 Dias
unlimited — Ilimitado
Padrão:
Tempo de vida padrão do plano
|
provider
|
body | string | opcional |
Provedor de caixa de correio: standard, gmail_alias, ou outlook_alias.
Padrão:
standard
|
pin_enabled
|
body | boolean | opcional |
Proteção opcional por PIN para a nova caixa de correio, quando permitida pelo seu plano. Não altera o PIN de uma caixa de correio existente.
Padrão:
false
|
pin
|
body | string | opcional |
Obrigatório quando pin_enabled for true: um PIN de 6 a 8 dígitos, enviado como string para preservar zeros à esquerda.
|
pin_confirmation
|
body | string | opcional |
Obrigatório quando pin_enabled for verdadeiro. Deve corresponder exatamente ao pin.
|
Idempotency-Key
|
header | string | opcional |
Necessário para criação ou exclusão protegida por PIN: uma chave estável de 16 a 128 caracteres. Refaça a mesma solicitação com a mesma chave para evitar trabalho duplicado.
|
username (nome de usuário personalizado se permitido pelo plano), domain (domínio permitido, ex. example.com), lifetime (valores permitidos: 10m, 1h, 2h, 1d, 1w, 1m, 3m, 6m, 1y, unlimited), provider (standard, gmail_alias, outlook_alias). Omitir o tempo de vida, ou deixá-lo vazio, para usar o Tempo de Vida de Email Padrão configurado para o seu plano mensal/anual atual. Envie um tempo de vida permitido, como 1h, para substituir esse padrão. Ilimitado é usado somente quando configurado como padrão do plano ou explicitamente solicitado e permitido. Os parâmetros de corpo mailbox_lifetime e email_lifetime também são aceitos; o primeiro valor não vazio tem prioridade nesta ordem: lifetime, mailbox_lifetime, email_lifetime. Valores inválidos ou não permitidos retornam HTTP 422 em vez de selecionar silenciosamente um padrão.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'
Resposta ilustrativa usando dados sintéticos. IDs, endereços, tokens, timestamps, limites e contagens do plano variam. As durações de exemplo não substituem o padrão do seu plano. As descrições dos campos de resposta identificam campos anuláveis e específicos do provedor.
Exemplo de resposta
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:59+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:59+00:00",
"email_token": "encrypted-email-token"
}
}
| Campo | Tipo | Descrição |
|---|---|---|
status |
boolean | Se a operação foi bem-sucedida. |
data.id |
integer | ID da caixa de correio. IDs, endereços e tokens gerados diferem para cada caixa de correio. |
data.pin_protected |
boolean | Se esta caixa de correio tem proteção por PIN. Nenhum PIN ou hash de PIN é retornado. |
data.email |
string | Endereço completo da caixa de correio gerado. |
data.domain |
string | Domínio da caixa de correio gerada. |
data.provider |
string | Provedor de caixa de correio: standard, gmail_alias, ou outlook_alias. |
data.expire_at |
string|null | Expiração efetiva como um timestamp ISO-8601, ou null para uma caixa de correio ilimitada. |
data.expires_in_seconds |
number|null | Segundos restantes não negativos quando calculado; segundos fracionários são possíveis. Null significa ilimitado, não zero. |
data.mailbox_state |
string | Estado atual da caixa de correio: ativo, pausado, expirado ou inativo. |
data.receiving_enabled |
boolean | Se esta caixa de correio aceita mensagens recebidas atualmente. |
data.message_count |
integer | Contagem total de mensagens conhecida; pode refletir a última sincronização da caixa de correio. |
data.unread_message_count |
integer | Contagem conhecida de mensagens não lidas; pode refletir a última sincronização da caixa de correio. |
data.last_message_received_at |
string|null | Último horário conhecido de mensagem recebida no formato ISO-8601, ou null quando indisponível. |
data.message_count_synced_at |
string|null | Última hora de sincronização da contagem de mensagens no formato ISO-8601, ou null antes da sincronização. |
data.created_at |
string|null | Hora de criação da caixa de correio no formato ISO-8601. |
data.email_token |
string | Referência de caixa de correio criptografada opaca. Não substitui a autenticação Bearer, verificações de propriedade ou autorização por PIN. |
data.pin_grant |
object | Condicional: a criação de caixa de correio protegida por PIN ativo retorna esta concessão de leitura; a criação comum sem proteção a omite. |
data.pin_grant.mailbox_id |
integer | ID da caixa de correio ao qual a concessão de leitura condicional está vinculada. |
data.pin_grant.unlock_token |
string | Token de leitura opaco para X-Mailbox-Unlock com a mesma credencial do proprietário. Mantenha-o privado e em memória; uma concessão de leitura não autoriza a exclusão. |
data.pin_grant.scope |
string | O escopo lido para a concessão de criação condicional. |
data.pin_grant.idle_timeout_seconds |
integer | Tempo ocioso permitido para a concessão de leitura, normalmente 3600 segundos. |
data.pin_grant.absolute_timeout_seconds |
integer | Tempo máximo de vida da concessão de leitura, normalmente 86400 segundos. |
data.pin_grant.expires_at |
string | Expiração atual da concessão de leitura no formato ISO-8601. |
data.pin_grant.absolute_expires_at |
string | Data de expiração absoluta da concessão de leitura no formato ISO-8601. Alterações de segurança podem revogar a concessão mais cedo. |
Atualizar / Trocar Caixa de Correio
Crie ou selecione uma caixa de correio no novo nome de usuário e domínio após verificar a propriedade da caixa de correio atual. Isso não renomeia a caixa de correio antiga nem altera sua duração no local. Quando o destino difere, a caixa de correio antiga permanece no histórico e pode ser pausada pelos limites de caixas de correio ativas. Reutilizar seu próprio destino ativo reaplica sua duração solicitada ou o padrão do plano.
| Parâmetro | Localização | Tipo | Status | Descrição |
|---|---|---|---|---|
email
|
path | string | obrigatório |
Endereço de e‑mail completo atual da caixa de correio de propriedade a ser trocado. URL-encode cada segmento de caminho; codifique um sinal de mais como %2B.
|
username
|
path | string | obrigatório |
Novo nome de usuário desejado: de 2 a 64 caracteres alfanuméricos; sujeito à permissão de nome de usuário personalizado.
|
domain
|
path | string | obrigatório |
Novo nome de domínio permitido.
|
lifetime
|
body | string | opcional |
valores permitidos:
10m — 10 Minutos
1h — 1 Hora
2h — 2 Horas
1d — 1 Dia
1w — 1 Semana
1m — 30 Dias
3m — 90 dias
6m — 180 Dias
1y — 365 Dias
unlimited — Ilimitado
Padrão:
Tempo de vida padrão do plano
|
pin_enabled
|
body | boolean | opcional |
Proteção opcional por PIN para a nova caixa de correio, quando permitida pelo seu plano. Não altera o PIN de uma caixa de correio existente.
Padrão:
false
|
pin
|
body | string | opcional |
Obrigatório quando pin_enabled for true: um PIN de 6 a 8 dígitos, enviado como string para preservar zeros à esquerda.
|
pin_confirmation
|
body | string | opcional |
Obrigatório quando pin_enabled for verdadeiro. Deve corresponder exatamente ao pin.
|
Idempotency-Key
|
header | string | opcional |
Necessário para criação ou exclusão protegida por PIN: uma chave estável de 16 a 128 caracteres. Refaça a mesma solicitação com a mesma chave para evitar trabalho duplicado.
|
X-Mailbox-Unlock
|
header | string | opcional |
Cabeçalho, apenas caixas de correio protegidas: use um unlock_token de leitura. Primeiro faça POST de pin e scope=read para a URL de desbloqueio de PIN. Mantenha sua autenticação 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). Omitir o tempo de vida, ou deixá-lo vazio, para usar o Tempo de Vida de Email Padrão configurado para o seu plano mensal/anual atual. Envie um tempo de vida permitido, como 1h, para substituir esse padrão. Ilimitado é usado somente quando configurado como padrão do plano ou explicitamente solicitado e permitido. Os parâmetros de corpo mailbox_lifetime e email_lifetime também são aceitos; o primeiro valor não vazio tem prioridade nesta ordem: lifetime, mailbox_lifetime, email_lifetime. Valores inválidos ou não permitidos retornam HTTP 422 em vez de selecionar silenciosamente um padrão.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'
Resposta ilustrativa usando dados sintéticos. IDs, endereços, tokens, timestamps, limites e contagens do plano variam. As durações de exemplo não substituem o padrão do seu plano. As descrições dos campos de resposta identificam campos anuláveis e específicos do provedor.
Exemplo de resposta
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:59+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:59+00:00",
"email_token": "encrypted-email-token"
}
}
| Campo | Tipo | Descrição |
|---|---|---|
status |
boolean | Se a operação foi bem-sucedida. |
data.id |
integer | ID da caixa de correio. IDs, endereços e tokens gerados diferem para cada caixa de correio. |
data.pin_protected |
boolean | Se esta caixa de correio tem proteção por PIN. Nenhum PIN ou hash de PIN é retornado. |
data.email |
string | Endereço completo da caixa de correio gerado. |
data.domain |
string | Domínio da caixa de correio gerada. |
data.provider |
string | Provedor de caixa de correio: standard, gmail_alias, ou outlook_alias. |
data.expire_at |
string|null | Expiração efetiva como um timestamp ISO-8601, ou null para uma caixa de correio ilimitada. |
data.expires_in_seconds |
number|null | Segundos restantes não negativos quando calculado; segundos fracionários são possíveis. Null significa ilimitado, não zero. |
data.mailbox_state |
string | Estado atual da caixa de correio: ativo, pausado, expirado ou inativo. |
data.receiving_enabled |
boolean | Se esta caixa de correio aceita mensagens recebidas atualmente. |
data.message_count |
integer | Contagem total de mensagens conhecida; pode refletir a última sincronização da caixa de correio. |
data.unread_message_count |
integer | Contagem conhecida de mensagens não lidas; pode refletir a última sincronização da caixa de correio. |
data.last_message_received_at |
string|null | Último horário conhecido de mensagem recebida no formato ISO-8601, ou null quando indisponível. |
data.message_count_synced_at |
string|null | Última hora de sincronização da contagem de mensagens no formato ISO-8601, ou null antes da sincronização. |
data.created_at |
string|null | Hora de criação da caixa de correio no formato ISO-8601. |
data.email_token |
string | Referência de caixa de correio criptografada opaca. Não substitui a autenticação Bearer, verificações de propriedade ou autorização por PIN. |
data.pin_grant |
object | Condicional: a criação de caixa de correio protegida por PIN ativo retorna esta concessão de leitura; a criação comum sem proteção a omite. |
data.pin_grant.mailbox_id |
integer | ID da caixa de correio ao qual a concessão de leitura condicional está vinculada. |
data.pin_grant.unlock_token |
string | Token de leitura opaco para X-Mailbox-Unlock com a mesma credencial do proprietário. Mantenha-o privado e em memória; uma concessão de leitura não autoriza a exclusão. |
data.pin_grant.scope |
string | O escopo lido para a concessão de criação condicional. |
data.pin_grant.idle_timeout_seconds |
integer | Tempo ocioso permitido para a concessão de leitura, normalmente 3600 segundos. |
data.pin_grant.absolute_timeout_seconds |
integer | Tempo máximo de vida da concessão de leitura, normalmente 86400 segundos. |
data.pin_grant.expires_at |
string | Expiração atual da concessão de leitura no formato ISO-8601. |
data.pin_grant.absolute_expires_at |
string | Data de expiração absoluta da concessão de leitura no formato ISO-8601. Alterações de segurança podem revogar a concessão mais cedo. |
Excluir caixa de correio
Exclua uma caixa de correio de propriedade e invoque a limpeza de suas mensagens e arquivos. Registros de caixa de correio retidos podem ser excluídos suavemente internamente; o endereço não está mais utilizável através da API.
| Parâmetro | Localização | Tipo | Status | Descrição |
|---|---|---|---|---|
email
|
path | string | obrigatório |
Endereço de e‑mail completo da caixa de correio proprietária a ser excluída. Codifique o endereço em URL; codifique o sinal de mais como %2B.
|
X-Mailbox-Unlock
|
header | string | opcional |
Cabeçalho, apenas caixas de correio protegidas: use o unlock_token de exclusão de uso único. Primeiro POST pin, scope=delete e o action/target_id retornado pela resposta 423 para a PIN unlock URL. Um token de leitura não pode excluir. <code>https://v1.tempmailg.com/api/mailboxes/{mailbox}/pin/unlock</code>
|
Idempotency-Key
|
header | string | opcional |
Necessário para criação ou exclusão protegida por PIN: uma chave estável de 16 a 128 caracteres. Refaça a mesma solicitação com a mesma chave para evitar trabalho 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'
Resposta ilustrativa usando dados sintéticos. IDs, endereços, tokens, timestamps, limites e contagens do plano variam. As durações de exemplo não substituem o padrão do seu plano. As descrições dos campos de resposta identificam campos anuláveis e específicos do provedor.
Exemplo de resposta
200 OK • JSON{
"status": true,
"message": "Email has been successfully deleted."
}
| Campo | Tipo | Descrição |
|---|---|---|
status |
boolean | Se a operação foi bem-sucedida. |
message |
string | Resultado da exclusão. Um recurso ausente retorna HTTP 404. |
Aliases do Gmail e Outlook
Gerar caixas de correio de alias Gmail e Outlook/Hotmail de alta reputação.
Criar alias do Gmail
Crie uma nova caixa de correio temporária de alias do Gmail, de propriedade do usuário autenticado.
| Parâmetro | Localização | Tipo | Status | Descrição |
|---|---|---|---|---|
mode
|
body | string | opcional |
Modo de geração: auto, dot, plus ou plus_dot. Também aceita gmail_alias_mode. Se a seleção de estilo não for permitida, auto será usado.
Padrão:
auto
|
username
|
body | string | opcional |
Sufixo de alias personalizado opcional: de 2 a 32 letras ou dígitos ASCII, normalizado para minúsculas; sujeito a permissão de recurso. Também aceita custom_username ou alias_username.
Padrão:
Gerado automaticamente
|
domain
|
body | string | opcional |
Use aleatório, gmail.com ou googlemail.com; alias_domain também é aceito. Omissão ou permissão de seleção de domínio indisponível usa aleatório.
Padrão:
random
|
lifetime
|
body | string | opcional |
valores permitidos:
10m — 10 Minutos
1h — 1 Hora
2h — 2 Horas
1d — 1 Dia
1w — 1 Semana
1m — 30 Dias
3m — 90 dias
6m — 180 Dias
1y — 365 Dias
unlimited — Ilimitado
Padrão:
Tempo de vida padrão do plano
|
pin_enabled
|
body | boolean | opcional |
Proteção opcional por PIN para a nova caixa de correio, quando permitida pelo seu plano. Não altera o PIN de uma caixa de correio existente.
Padrão:
false
|
pin
|
body | string | opcional |
Obrigatório quando pin_enabled for true: um PIN de 6 a 8 dígitos, enviado como string para preservar zeros à esquerda.
|
pin_confirmation
|
body | string | opcional |
Obrigatório quando pin_enabled for verdadeiro. Deve corresponder exatamente ao pin.
|
Idempotency-Key
|
header | string | opcional |
Necessário para criação ou exclusão protegida por PIN: uma chave estável de 16 a 128 caracteres. Refaça a mesma solicitação com a mesma chave para evitar trabalho duplicado.
|
mode (auto, dot, plus, plus_dot), username (nome de usuário de alias personalizado), domain (ex.: gmail.com, googlemail.com), lifetime (valores permitidos: 10m, 1h, 2h, 1d, 1w, 1m, 3m, 6m, 1y, unlimited). Omitir o tempo de vida, ou deixá-lo vazio, para usar o Tempo de Vida de Email Padrão configurado para o seu plano mensal/anual atual. Envie um tempo de vida permitido, como 1h, para substituir esse padrão. Ilimitado é usado somente quando configurado como padrão do plano ou explicitamente solicitado e permitido. Os parâmetros de corpo mailbox_lifetime e email_lifetime também são aceitos; o primeiro valor não vazio tem prioridade nesta ordem: lifetime, mailbox_lifetime, email_lifetime. Valores inválidos ou não permitidos retornam HTTP 422 em vez de selecionar silenciosamente um padrão.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'
Resposta ilustrativa usando dados sintéticos. IDs, endereços, tokens, timestamps, limites e contagens do plano variam. As durações de exemplo não substituem o padrão do seu plano. As descrições dos campos de resposta identificam campos anuláveis e específicos do provedor.
Exemplo de resposta
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:59+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:59+00:00",
"email_token": "encrypted-email-token"
}
}
| Campo | Tipo | Descrição |
|---|---|---|
status |
boolean | Se a operação foi bem-sucedida. |
data.id |
integer | ID da caixa de correio. IDs, endereços e tokens gerados diferem para cada caixa de correio. |
data.pin_protected |
boolean | Se esta caixa de correio tem proteção por PIN. Nenhum PIN ou hash de PIN é retornado. |
data.email |
string | Endereço completo da caixa de correio gerado. |
data.domain |
string | Domínio da caixa de correio gerada. |
data.provider |
string | Provedor de caixa de correio: standard, gmail_alias, ou outlook_alias. |
data.expire_at |
string|null | Expiração efetiva como um timestamp ISO-8601, ou null para uma caixa de correio ilimitada. |
data.expires_in_seconds |
number|null | Segundos restantes não negativos quando calculado; segundos fracionários são possíveis. Null significa ilimitado, não zero. |
data.mailbox_state |
string | Estado atual da caixa de correio: ativo, pausado, expirado ou inativo. |
data.receiving_enabled |
boolean | Se esta caixa de correio aceita mensagens recebidas atualmente. |
data.message_count |
integer | Contagem total de mensagens conhecida; pode refletir a última sincronização da caixa de correio. |
data.unread_message_count |
integer | Contagem conhecida de mensagens não lidas; pode refletir a última sincronização da caixa de correio. |
data.last_message_received_at |
string|null | Último horário conhecido de mensagem recebida no formato ISO-8601, ou null quando indisponível. |
data.message_count_synced_at |
string|null | Última hora de sincronização da contagem de mensagens no formato ISO-8601, ou null antes da sincronização. |
data.created_at |
string|null | Hora de criação da caixa de correio no formato ISO-8601. |
data.email_token |
string | Referência de caixa de correio criptografada opaca. Não substitui a autenticação Bearer, verificações de propriedade ou autorização por PIN. |
data.pin_grant |
object | Condicional: a criação de caixa de correio protegida por PIN ativo retorna esta concessão de leitura; a criação comum sem proteção a omite. |
data.pin_grant.mailbox_id |
integer | ID da caixa de correio ao qual a concessão de leitura condicional está vinculada. |
data.pin_grant.unlock_token |
string | Token de leitura opaco para X-Mailbox-Unlock com a mesma credencial do proprietário. Mantenha-o privado e em memória; uma concessão de leitura não autoriza a exclusão. |
data.pin_grant.scope |
string | O escopo lido para a concessão de criação condicional. |
data.pin_grant.idle_timeout_seconds |
integer | Tempo ocioso permitido para a concessão de leitura, normalmente 3600 segundos. |
data.pin_grant.absolute_timeout_seconds |
integer | Tempo máximo de vida da concessão de leitura, normalmente 86400 segundos. |
data.pin_grant.expires_at |
string | Expiração atual da concessão de leitura no formato ISO-8601. |
data.pin_grant.absolute_expires_at |
string | Data de expiração absoluta da concessão de leitura no formato ISO-8601. Alterações de segurança podem revogar a concessão mais cedo. |
Domínios de Alias do Outlook
Buscar domínios de alias do Outlook / Hotmail ativos disponíveis para geração de caixa de correio.
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'
Resposta ilustrativa usando dados sintéticos. IDs, endereços, tokens, timestamps, limites e contagens do plano variam. As durações de exemplo não substituem o padrão do seu plano. As descrições dos campos de resposta identificam campos anuláveis e específicos do provedor.
Exemplo de resposta
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 | Descrição |
|---|---|---|
status |
boolean | Se a operação foi bem-sucedida. |
data.domains |
array | Domínios Outlook/Hotmail ativos; um array vazio é válido. |
data.domains[].domain |
string | Nome de domínio disponível. |
data.domains[].type |
string | Rótulo legível do provedor. |
data.domains[].selectable |
boolean | Se a sua conta pode escolher explicitamente este domínio. |
data.domains[].locked |
boolean | Se a seleção explícita de domínio está bloqueada para sua conta. |
data.domains[].disabled_reason |
string|null | Motivo pelo qual a seleção de domínio está bloqueada, ou nulo quando selecionável. |
Criar alias do Outlook
Crie uma nova caixa de correio temporária de alias do Outlook / Hotmail de propriedade do usuário autenticado.
| Parâmetro | Localização | Tipo | Status | Descrição |
|---|---|---|---|---|
domain
|
body | string | opcional |
Use aleatório ou um domínio de GET /outlook-alias/domains; outlook_alias_domain também é aceito. Sem permissão de seleção, aleatório é usado.
Padrão:
Domínio disponível aleatório
|
username
|
body | string | opcional |
Sufixo de alias personalizado opcional: de 2 a 32 letras ou dígitos ASCII, normalizado para minúsculas; sujeito a permissão de recurso. Também aceita custom_username ou alias_username.
Padrão:
Gerado automaticamente
|
lifetime
|
body | string | opcional |
valores permitidos:
10m — 10 Minutos
1h — 1 Hora
2h — 2 Horas
1d — 1 Dia
1w — 1 Semana
1m — 30 Dias
3m — 90 dias
6m — 180 Dias
1y — 365 Dias
unlimited — Ilimitado
Padrão:
Tempo de vida padrão do plano
|
pin_enabled
|
body | boolean | opcional |
Proteção opcional por PIN para a nova caixa de correio, quando permitida pelo seu plano. Não altera o PIN de uma caixa de correio existente.
Padrão:
false
|
pin
|
body | string | opcional |
Obrigatório quando pin_enabled for true: um PIN de 6 a 8 dígitos, enviado como string para preservar zeros à esquerda.
|
pin_confirmation
|
body | string | opcional |
Obrigatório quando pin_enabled for verdadeiro. Deve corresponder exatamente ao pin.
|
Idempotency-Key
|
header | string | opcional |
Necessário para criação ou exclusão protegida por PIN: uma chave estável de 16 a 128 caracteres. Refaça a mesma solicitação com a mesma chave para evitar trabalho duplicado.
|
domain (ex. outlook.com, hotmail.com), username (nome de usuário de alias personalizado), lifetime (valores permitidos: 10m, 1h, 2h, 1d, 1w, 1m, 3m, 6m, 1y, unlimited). Omitir o tempo de vida, ou deixá-lo vazio, para usar o Tempo de Vida de Email Padrão configurado para o seu plano mensal/anual atual. Envie um tempo de vida permitido, como 1h, para substituir esse padrão. Ilimitado é usado somente quando configurado como padrão do plano ou explicitamente solicitado e permitido. Os parâmetros de corpo mailbox_lifetime e email_lifetime também são aceitos; o primeiro valor não vazio tem prioridade nesta ordem: lifetime, mailbox_lifetime, email_lifetime. Valores inválidos ou não permitidos retornam HTTP 422 em vez de selecionar silenciosamente um padrão.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'
Resposta ilustrativa usando dados sintéticos. IDs, endereços, tokens, timestamps, limites e contagens do plano variam. As durações de exemplo não substituem o padrão do seu plano. As descrições dos campos de resposta identificam campos anuláveis e específicos do provedor.
Exemplo de resposta
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:59+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:59+00:00",
"email_token": "encrypted-email-token"
}
}
| Campo | Tipo | Descrição |
|---|---|---|
status |
boolean | Se a operação foi bem-sucedida. |
data.id |
integer | ID da caixa de correio. IDs, endereços e tokens gerados diferem para cada caixa de correio. |
data.pin_protected |
boolean | Se esta caixa de correio tem proteção por PIN. Nenhum PIN ou hash de PIN é retornado. |
data.email |
string | Endereço completo da caixa de correio gerado. |
data.domain |
string | Domínio da caixa de correio gerada. |
data.provider |
string | Provedor de caixa de correio: standard, gmail_alias, ou outlook_alias. |
data.expire_at |
string|null | Expiração efetiva como um timestamp ISO-8601, ou null para uma caixa de correio ilimitada. |
data.expires_in_seconds |
number|null | Segundos restantes não negativos quando calculado; segundos fracionários são possíveis. Null significa ilimitado, não zero. |
data.mailbox_state |
string | Estado atual da caixa de correio: ativo, pausado, expirado ou inativo. |
data.receiving_enabled |
boolean | Se esta caixa de correio aceita mensagens recebidas atualmente. |
data.message_count |
integer | Contagem total de mensagens conhecida; pode refletir a última sincronização da caixa de correio. |
data.unread_message_count |
integer | Contagem conhecida de mensagens não lidas; pode refletir a última sincronização da caixa de correio. |
data.last_message_received_at |
string|null | Último horário conhecido de mensagem recebida no formato ISO-8601, ou null quando indisponível. |
data.message_count_synced_at |
string|null | Última hora de sincronização da contagem de mensagens no formato ISO-8601, ou null antes da sincronização. |
data.created_at |
string|null | Hora de criação da caixa de correio no formato ISO-8601. |
data.email_token |
string | Referência de caixa de correio criptografada opaca. Não substitui a autenticação Bearer, verificações de propriedade ou autorização por PIN. |
data.pin_grant |
object | Condicional: a criação de caixa de correio protegida por PIN ativo retorna esta concessão de leitura; a criação comum sem proteção a omite. |
data.pin_grant.mailbox_id |
integer | ID da caixa de correio ao qual a concessão de leitura condicional está vinculada. |
data.pin_grant.unlock_token |
string | Token de leitura opaco para X-Mailbox-Unlock com a mesma credencial do proprietário. Mantenha-o privado e em memória; uma concessão de leitura não autoriza a exclusão. |
data.pin_grant.scope |
string | O escopo lido para a concessão de criação condicional. |
data.pin_grant.idle_timeout_seconds |
integer | Tempo ocioso permitido para a concessão de leitura, normalmente 3600 segundos. |
data.pin_grant.absolute_timeout_seconds |
integer | Tempo máximo de vida da concessão de leitura, normalmente 86400 segundos. |
data.pin_grant.expires_at |
string | Expiração atual da concessão de leitura no formato ISO-8601. |
data.pin_grant.absolute_expires_at |
string | Data de expiração absoluta da concessão de leitura no formato ISO-8601. Alterações de segurança podem revogar a concessão mais cedo. |
Mensagens e Anexos
Buscar caixas de entrada recebidas, ler mensagens completas em HTML/texto e transmitir anexos.
Listar mensagens da caixa de correio
Recupere os resumos de mensagens disponíveis e os metadados da caixa de correio. As varreduras padrão da caixa de entrada retornam um lote recente de até 25 mensagens; este não é um endpoint paginado de histórico completo. Use GET /messages/{messageId} para obter os corpos completos e os anexos.
| Parâmetro | Localização | Tipo | Status | Descrição |
|---|---|---|---|---|
email
|
query | string | obrigatório |
Endereço de e-mail completo da caixa de correio de propriedade para ler mensagens. Codifique o valor da consulta em URL; codifique um sinal de mais como %2B.
|
X-Mailbox-Unlock
|
header | string | opcional |
Cabeçalho, apenas caixas de correio protegidas: use um unlock_token de leitura. Primeiro faça POST de pin e scope=read para a URL de desbloqueio de PIN. Mantenha sua autenticação 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'
Resposta ilustrativa usando dados sintéticos. IDs, endereços, tokens, timestamps, limites e contagens do plano variam. As durações de exemplo não substituem o padrão do seu plano. As descrições dos campos de resposta identificam campos anuláveis e específicos do provedor.
Exemplo de resposta
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:59",
"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:59+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:59+00:00",
"message_count_synced_at": "2026-11-19T02:17:59+00:00"
}
| Campo | Tipo | Descrição |
|---|---|---|
status |
boolean | Se a operação foi bem-sucedida. |
mailbox |
string | Endereço da caixa de correio cujas mensagens foram solicitadas. |
email_token |
string | Referência opaca de caixa de correio criptografada; a autenticação normal ainda é necessária. |
mailbox_provider |
string | Provedor de caixa de correio: standard, gmail_alias, ou outlook_alias. |
messages |
array | Resumos de mensagens. Uma caixa de entrada vazia retorna um array vazio; recupere uma única mensagem para seu corpo e anexos. |
expire_at |
string|null | Expiração efetiva como um timestamp ISO-8601, ou null para uma caixa de correio ilimitada. |
expires_in_seconds |
number|null | Segundos restantes não negativos quando calculado; segundos fracionários são possíveis. Null significa ilimitado, não zero. |
mailbox_state |
string | Estado atual da caixa de correio: ativo, pausado, expirado ou inativo. |
receiving_enabled |
boolean | Se esta caixa de correio aceita mensagens recebidas atualmente. |
message_count |
integer | Contagem total de mensagens conhecida; pode refletir a última sincronização da caixa de correio. |
unread_message_count |
integer | Contagem conhecida de mensagens não lidas; pode refletir a última sincronização da caixa de correio. |
last_message_received_at |
string|null | Último horário conhecido de mensagem recebida no formato ISO-8601, ou null quando indisponível. |
message_count_synced_at |
string|null | Última hora de sincronização da contagem de mensagens no formato ISO-8601, ou null antes da sincronização. |
mailbox_limit.limit |
integer | Limite ativo de caixas de correio para este provedor; -1 significa ilimitado. |
mailbox_limit.limit_label |
string | Rótulo de exibição para o limite da caixa de correio. |
mailbox_limit.active_count |
integer | Número de caixas de correio ativas para este provedor. |
mailbox_limit.paused_count |
integer | Número de caixas de correio pausadas para este provedor. |
mailbox_limit.paused_mailboxes |
array<string> | Endereços pausados pelo limite da caixa de correio. |
mailbox_limit.remaining |
integer | Slots de caixa de correio ativos restantes; -1 significa ilimitado. Isto não é quota de requisições da API. |
mailbox_limit.remaining_label |
string | Exibir rótulo para vagas restantes da caixa de correio. |
mailbox_limit.reached |
boolean | Se o limite de caixas de correio ativas foi atingido. |
mailbox_limit.blocked |
boolean | Se o limite de caixa de correio ativa é zero. |
mailbox_limit.provider |
string|null | Provedor ao qual o limite da caixa de correio se aplica. |
messages[].id |
string | ID de mensagem opaca usado pelos endpoints de mensagem única, exclusão e anexo. |
messages[].is_seen |
boolean | Se a mensagem está marcada como lida. |
messages[].subject |
string | Assunto da mensagem. |
messages[].from |
string | Nome de exibição ou endereço do remetente. |
messages[].from_email |
string | Endereço de e‑mail do remetente. |
messages[].receivedAt |
string | Hora recebida no fuso horário da aplicação, formatada como YYYY-MM-DD HH:mm:ss. |
messages[].otp |
string|null | Detectado código de uso único quando disponível e permitido; caso contrário, nulo. |
messages[].otp_locked |
boolean | Se um código de uso único detectado está oculto pelas permissões do recurso. |
messages[].verification_link |
string|null | URL de verificação detectada quando disponível e permitida; caso contrário, nulo. |
messages[].verification_link_locked |
boolean | Se um link de verificação detectado está oculto pelas permissões de recurso. |
messages[].from_name |
string|null | Campo de resumo do Outlook: nome do remetente original. Ausente dos resumos padrão e do Gmail. |
messages[].snippet |
string|null | Campo de resumo do Outlook: pré‑visualização curta da mensagem. |
messages[].received_at |
string|null | Campo de resumo do Outlook: hora recebida em ISO-8601, quando conhecida. |
messages[].has_attachments |
boolean | Campo de resumo do Outlook: se os metadados do anexo existem. A disponibilidade de download é verificada separadamente. |
Obter mensagem única
Recupere uma mensagem de propriedade própria pelo seu ID de mensagem opaco. Retorna formatos de corpo e metadados de anexos. Os campos do corpo dependem do formato da mensagem; o Outlook adiciona campos específicos do provedor listados abaixo.
| Parâmetro | Localização | Tipo | Status | Descrição |
|---|---|---|---|---|
messageId
|
path | string | obrigatório |
ID de mensagem única retornado na lista de mensagens.
|
X-Mailbox-Unlock
|
header | string | opcional |
Cabeçalho, apenas caixas de correio protegidas: use um unlock_token de leitura. Primeiro faça POST de pin e scope=read para a URL de desbloqueio de PIN. Mantenha sua autenticação 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'
Resposta ilustrativa usando dados sintéticos. IDs, endereços, tokens, timestamps, limites e contagens do plano variam. As durações de exemplo não substituem o padrão do seu plano. As descrições dos campos de resposta identificam campos anuláveis e específicos do provedor.
Exemplo de resposta
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:59",
"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 | Descrição |
|---|---|---|
status |
boolean | Se a operação foi bem-sucedida. |
data.id |
string | ID de mensagem opaco. |
data.is_seen |
boolean | Estado de leitura da mensagem. Ler pode marcá-la como vista; dados em cache podem refletir um estado anterior. |
data.subject |
string | Assunto da mensagem. |
data.from |
string | Nome de exibição ou endereço do remetente. |
data.from_email |
string | Endereço de e‑mail do remetente. |
data.to |
string | Endereço da caixa de correio do destinatário. |
data.mailbox_provider |
string | Provedor de caixa de correio: standard, gmail_alias, ou outlook_alias. |
data.receivedAt |
string | Hora recebida no fuso horário da aplicação, formatada como YYYY-MM-DD HH:mm:ss. |
data.html |
boolean | Se a mensagem tem um corpo HTML. |
data.html_content |
string | Corpo HTML quando presente. Mensagens padrão sem HTML podem omitir este campo. Trate o conteúdo da mensagem como não confiável. |
data.text_content |
string | Corpo de texto quando presente; Mensagens padrão podem conter texto escapado em um elemento pre ou omitir este campo. |
data.content |
string | Corpo preferido para exibição, normalmente HTML quando disponível. |
data.attachments |
array | Metadados do anexo, ou um array vazio. Downloads requerem autenticação normal e autorização de PIN aplicável. |
data.attachments[].name |
string | Nome do arquivo a codificar em URL como um único segmento de caminho ao baixar. |
data.attachments[].size |
integer | Tamanho do anexo em bytes. |
data.attachments[].url |
string | URL de download da API de Usuário Autenticado adicionada aos anexos com um nome de arquivo. Uma URL não garante que o arquivo local esteja disponível. |
data.attachments[].extension |
string | Campo de metadados padrão/Gmail: extensão de arquivo quando fornecida. |
data.attachments[].id |
string | Campo de metadados do Outlook: ID de anexo do provedor. |
data.attachments[].content_type |
string | Campo de metadados do Outlook: tipo de conteúdo MIME. |
data.from_name |
string|null | Campo de detalhe do Outlook: nome do remetente original. |
data.to_email |
string|null | Campo de detalhe do Outlook: endereço do destinatário original. |
data.received_at |
string|null | Campo de detalhe do Outlook: hora recebida no formato ISO-8601. |
data.has_html |
boolean | Campo de detalhe do Outlook: se existe um corpo HTML. |
Excluir Mensagem
Excluir uma mensagem de propriedade única.
| Parâmetro | Localização | Tipo | Status | Descrição |
|---|---|---|---|---|
messageId
|
path | string | obrigatório |
String de ID de mensagem única para excluir permanentemente.
|
X-Mailbox-Unlock
|
header | string | opcional |
Cabeçalho, apenas caixas de correio protegidas: use o unlock_token de exclusão de uso único. Primeiro POST pin, scope=delete e o action/target_id retornado pela resposta 423 para a PIN unlock URL. Um token de leitura não pode excluir. <code>https://v1.tempmailg.com/api/mailboxes/{mailbox}/pin/unlock</code>
|
Idempotency-Key
|
header | string | opcional |
Necessário para criação ou exclusão protegida por PIN: uma chave estável de 16 a 128 caracteres. Refaça a mesma solicitação com a mesma chave para evitar trabalho 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'
Resposta ilustrativa usando dados sintéticos. IDs, endereços, tokens, timestamps, limites e contagens do plano variam. As durações de exemplo não substituem o padrão do seu plano. As descrições dos campos de resposta identificam campos anuláveis e específicos do provedor.
Exemplo de resposta
200 OK • JSON{
"status": true,
"message": "Message was deleted successfully."
}
| Campo | Tipo | Descrição |
|---|---|---|
status |
boolean | Se a operação foi bem-sucedida. |
message |
string | Resultado da exclusão. Um recurso ausente retorna HTTP 404. |
Baixar anexo
Baixar um anexo de uma mensagem de propriedade.
| Parâmetro | Localização | Tipo | Status | Descrição |
|---|---|---|---|---|
messageId
|
path | string | obrigatório |
ID da mensagem que contém o arquivo.
|
filename
|
path | string | obrigatório |
Nome do arquivo e extensão do anexo para download.
|
X-Mailbox-Unlock
|
header | string | opcional |
Cabeçalho, apenas caixas de correio protegidas: use um unlock_token de leitura. Primeiro faça POST de pin e scope=read para a URL de desbloqueio de PIN. Mantenha sua autenticação 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 | Descrição |
|---|---|---|
Content-Disposition |
header | Resposta bem-sucedida baixa o nome de arquivo solicitado. |
body |
binary | Bytes do arquivo em caso de sucesso, não JSON. Erros retornam JSON com um status diferente de 2xx. |
Limites de Taxas e Cotas
Monitore orçamentos de solicitações em tempo real, limites de taxa e cotas de conta sem consumir créditos.
Limite de taxa & cota
Verifique seu limite de taxa atual e o status da cota sem consumir nenhum uso da API. Este endpoint é livre de cota e não deduz créditos mensais da API (limite de proteção contra abuso: 60 solicitações/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'
Resposta ilustrativa usando dados sintéticos. IDs, endereços, tokens, timestamps, limites e contagens do plano variam. As durações de exemplo não substituem o padrão do seu plano. As descrições dos campos de resposta identificam campos anuláveis e específicos do provedor.
Exemplo de resposta
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 | Descrição |
|---|---|---|
data.limit |
integer|string | Limite de solicitações por minuto da conta. A string unlimited indica um orçamento ilimitado por minuto; isso é independente da cota mensal. |
data.remaining |
integer|string | Slots de orçamento de minutos restantes da conta, ou a string unlimited. Um valor positivo não significa que créditos da API permanecem. |
data.reset |
integer | Segundos para a janela de minuto da conta, não para a redefinição mensal da cota. Orçamentos de minuto desativados ou ilimitados podem manter um valor nominal de 60 segundos; isso não garante acesso após a espera. |
data.plan |
string | Etiqueta do plano atual. O nome legível do plano é fornecido separadamente em data.quota.plan_name. |
data.quota.enabled |
boolean | Se o acesso global e de plano/crédito à API está habilitado. Isso não indica a capacidade restante nem substitui a chave de API do usuário. |
data.quota.user_api_status |
boolean | Se o usuário ativou o interruptor da API do usuário. As operações requerem esse interruptor, bem como acesso habilitado e capacidade disponível. |
data.quota.plan_name |
string | Nome legível do plano atual. |
data.quota.period |
string | Período de uso de calendário-mês no formato YYYY-MM, usando o fuso horário da aplicação; não necessariamente o período de faturamento da assinatura. |
data.quota.base_limit |
integer | Cota base do plano mensal. Um valor de -1 significa ilimitado. |
data.quota.extra_requests |
integer | Aumento mensal adicional concedido para o período de uso atual; separado dos créditos comprados. |
data.quota.monthly_limit |
integer | Cota base mais solicitações extras do período atual. Um valor de -1 significa ilimitado. Créditos comprados não estão incluídos. |
data.quota.monthly_remaining |
integer|null | Alocação mensal finita restante, ou null quando a cota mensal é ilimitada. Null não deve ser interpretado como zero. |
data.quota.used |
integer | Operações de API bem-sucedidas e contabilizadas no período de uso atual, incluindo operações usando créditos. Verificações de status não aumentam esse valor. |
data.quota.purchased_credits |
integer | Saldo atual de créditos, incluindo créditos bônus do plano ativo. Créditos bônus não devem ser adicionados a este saldo uma segunda vez. |
data.quota.bonus_credits |
integer | Parte de bônus do plano ativo do saldo de crédito; uma divisão de purchased_credits, não capacidade adicional. |
data.quota.direct_purchased_credits |
integer | Saldo de crédito excluindo a parte de bônus do plano ativo. Este valor mais bonus_credits equivale a purchased_credits. |
data.quota.remaining |
integer|null | Cota mensal restante mais o saldo de crédito atual, sem contar bônus duas vezes. Null significa quota mensal ilimitada. Permissões individuais de recursos e outros limites de requisição ainda se aplicam. |
data.quota.unlimited |
boolean | Indica se a cota mensal é ilimitada. Isso não torna ilimitado o orçamento de minutos da conta ou outros limites de recursos. |
data.quota.usage_percent |
integer | Porcentagem arredondada compatível com o painel de 0 a 100: usado dividido por usado mais restante, multiplicado por 100. Inclui a capacidade de crédito disponível, portanto recarregar pode reduzir a porcentagem. É 0 para cota ilimitada ou um pool de tamanho zero; não é a porcentagem de limite de taxa por minuto nem uma decisão de acesso. |
data.quota.reset_at |
string | Carimbo de data/hora ISO-8601 com deslocamento de fuso horário para a redefinição da cota do próximo mês calendário. Isso não é a data de expiração da assinatura, e a redefinição mensal não recarrega os créditos comprados. |
status |
string | O sucesso literal para este endpoint de status. Outros endpoints de caixa de correio bem-sucedidos usam o booleano true. |
data.monthly_limit |
integer | Alias de compatibilidade do campo data.quota correspondente; não o adicione novamente ao calcular saldos. |
data.monthly_remaining |
integer|null | Alias de compatibilidade do campo data.quota correspondente; não o adicione novamente ao calcular saldos. |
data.purchased_credits |
integer | Alias de compatibilidade do campo data.quota correspondente; não o adicione novamente ao calcular saldos. |
Webhooks de Caixa Postal (Empurrar em Tempo Real)
Em vez de verificar repetidamente a API REST (GET /messages) para verificar se há e-mails entrantes, configure Webhooks para enviar novas mensagens para seu servidor ou fluxo de trabalho de automação em tempo real.
Eventos de Webhook Suportados
Cada webhook pode se inscrever em um ou mais tipos de eventos. Seu endpoint recebe uma notificação de evento sempre que um desses gatilhos for acionado.
Enviado em tempo real sempre que uma nova mensagem chega à caixa de correio selecionada.
Enviado quando a caixa de correio temporária expira e o processamento do webhook é pausado.
Enviado quando uma caixa de correio expirada se torna ativa novamente sob as regras do plano.
Enviado imediatamente antes de o webhook e sua caixa de correio serem excluídos.
Cabeçalhos de Requisição & Verificação de Assinatura HMAC
Toda entrega de webhook contém cabeçalhos de segurança especiais. Use o cabeçalho X-TempMailg-Signature para verificar que as solicitações entrantes foram realmente enviadas pelo TempMailg e não foram alteradas.
| Nome do Cabeçalho | Valor de Exemplo | Descrição |
|---|---|---|
User-Agent |
TempMailg-Webhooks/1.0 | Identificador padrão para o trabalhador de entrega de webhook. |
X-TempMailg-Event |
email.received | O tipo de evento que acionou esta entrega. |
X-TempMailg-Event-Id |
e7b1a2c3-4d5e-6f7a-8b9c-0d1e2f3a4b5c | UUID único atribuído a esta tentativa de entrega. |
X-TempMailg-Timestamp |
1725192000 | Timestamp Unix epoch indicando quando a solicitação foi iniciada. |
X-TempMailg-Signature |
sha256=d7a8fbb307d7809469ca933b02d82941... | Assinatura HMAC-SHA256 calculada a partir de {timestamp}.{raw_body} usando seu segredo. |
X-TempMailg-Test |
false | Verdadeiro quando enviado pelo recurso "Send Test Ping" no seu painel. |
A assinatura é calculada usando HMAC com SHA256 sobre a string:
hash_hmac('sha256', "${X-TempMailg-Timestamp}.${raw_request_body}", your_webhook_secret)
Payload de Evento de Exemplo (email.received)
Enviado como application/json no corpo da solicitação HTTP POST.
{
"id": "e7b1a2c3-4d5e-6f7a-8b9c-0d1e2f3a4b5c",
"version": "1.0",
"event": "email.received",
"occurred_at": "2026-11-19T02:18:00+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:00+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"
}
}
Exemplos de Implementação do Receptor
Selecione seu idioma para ver como receber webhooks e verificar assinaturas HMAC com segurança.
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 Suportadas e Integrações de Automação
Webhooks do TempMailg funcionam imediatamente com endpoints HTTPS padrão e as principais plataformas sem código/automação:
Erros comuns e solução de problemas
Estes são os códigos de resposta mais comuns que você pode ver ao integrar a API do usuário.
Token Bearer inválido, ausente ou revogado.
Propriedade, permissões de recursos, acesso ao domínio ou tamanho do anexo impediram a operação. Verifique o código de resposta e a mensagem.
O recurso não foi encontrado no host permitido ou não pertence ao usuário.
A chave de operação foi reutilizada com detalhes diferentes, outra operação está pendente ou a segurança da caixa de correio mudou. Inspecione o código antes de tentar novamente.
Caixa de correio expirou ou está inativa.
Parâmetros inválidos, um tempo de vida não permitido, capacidade de alias indisponível, configuração de PIN inválida ou uma Idempotency-Key ausente/inválida impediram a operação.
Uma caixa de correio protegida precisa de um token X-Mailbox-Unlock válido e com escopo. Use a ação e target_id da resposta para exclusão. Requisitos de bloqueio ou recuperação devem ser resolvidos antes de tentar novamente.
Um limite de solicitação, plano desativado, cota esgotada ou tempo de espera impediu a operação. Verifique o motivo e os cabeçalhos de orçamento disponível. Retry-After é opcional.
O servidor não pôde concluir a operação. Para criação ou exclusão protegida, preserve a mesma solicitação e Idempotency-Key ao tentar novamente.
O armazenamento de proteção ou a coordenação não puderam ser verificados. Tente novamente após o atraso indicado. Esta resposta não é um pagamento falhado.
Lista de verificação rápida
- 401 Unauthorized - O token Bearer está faltando, errado, revogado ou copiado incorretamente.
- 403 Forbidden - O plano atual não tem acesso à API do usuário no momento.
- 404 Not Found - Recurso não encontrado ou parâmetro inválido
- 410 Gone / Expired - Caixa de correio expirou ou não está mais ativa.
- 429 Rate Limited - Verifique o motivo da resposta e os cabeçalhos de orçamento. Retry-After se aplica apenas a limites de tempo; créditos esgotados ou acesso desativado podem exigir uma alteração de conta.
Próxima etapa recomendada
Se você estiver conectado, abra primeiro o Gerenciamento de API e confirme seu chave, status de cota, plano de acesso e a URL de API de usuário exata antes de depurar seu aplicativo externo.