API de email temporário e servidor MCP para testes e agentes de IA

Início rápido com curl

Crie uma caixa, aguarde o próximo email, leia-o e exclua a caixa. Guarde sua chave de API em TEMPGENERATOR_TOKEN e nunca a coloque em uma URL.

Requer curl e jq. O script aguarda até três vezes por 20 segundos, exibe o assunto, os códigos, os links e o texto de cada mensagem e depois exclui a caixa.

export TEMPGENERATOR_URL='https://www.tempgenerator.com'
API="$TEMPGENERATOR_URL/developer-api/v1"
AUTH="Authorization: Bearer $TEMPGENERATOR_TOKEN"
INBOX=$(curl --fail-with-body -sS -X POST "$API/inboxes" -H "$AUTH" -H 'Accept: application/json')
ID=$(printf '%s' "$INBOX" | jq -r .id)
echo "Send a test email to $(printf '%s' "$INBOX" | jq -r .address)"
for ATTEMPT in 1 2 3; do
  RESULT=$(curl --fail-with-body -sS "$API/inboxes/$ID/wait?after=0&timeout=20" -H "$AUTH" -H 'Accept: application/json')
  [ "$(printf '%s' "$RESULT" | jq -r .status)" = message ] && break
done
for MESSAGE in $(printf '%s' "$RESULT" | jq -r '.messages[].id'); do
  curl --fail-with-body -sS "$API/inboxes/$ID/messages/$MESSAGE" -H "$AUTH" -H 'Accept: application/json' \
    | jq '{subject, codes, links, text}'
done
curl --fail-with-body -sS -X DELETE "$API/inboxes/$ID" -H "$AUTH"

A API em resumo

URL base: https://www.tempgenerator.com/developer-api/v1. Envie Authorization: Bearer <key> em todas as solicitações. As respostas são em JSON; os erros têm o formato {"error": {"code", "message", "retry_after"}}, e os erros de cota também enviam um cabeçalho Retry-After.

• POST /inboxes Criar uma caixa e obter o endereço e a data de expiração
• GET /inboxes/{id}/wait?after=0&timeout=20 Aguardar até 20 segundos pela próxima mensagem após um cursor
• GET /inboxes/{id}/messages?after=0 Listar até 50 mensagens após um cursor, da mais antiga para a mais recente
• GET /inboxes/{id}/messages/{message_id} Ler uma mensagem: texto, códigos, links e lista de anexos
• GET /inboxes/{id}/messages/{message_id}/attachments/{index} Baixar um anexo pelo índice
• DELETE /inboxes/{id} Excluir imediatamente a caixa e as mensagens dela

As solicitações de listagem e de espera aceitam os filtros opcionais from e subject_contains: correspondências do tipo “contém” no remetente e no assunto, sem diferenciar maiúsculas de minúsculas.

Exemplo de resposta de leitura

{
    "id": 42,
    "from": "no-reply@app.example",
    "subject": "Your verification code",
    "received_at": "2026-10-03T09:41:07+00:00",
    "text": "Your verification code is 482913.\nOr confirm: https://app.example/verify?token=8f3c",
    "text_truncated": false,
    "codes": [
        "482913"
    ],
    "links": [
        "https://app.example/verify?token=8f3c"
    ],
    "expires_at": "2026-10-03T10:40:12+00:00",
    "attachments": [
        {
            "index": 0,
            "filename": "receipt.pdf",
            "size": 48213
        }
    ],
    "untrusted_content": true
}

Tokens de desenvolvedor

Crie chaves de API em “Acesso de desenvolvedor” depois de verificar seu email. Uma chave de leitura e gravação pode criar, ler e excluir caixas; uma chave somente leitura pode listar, aguardar, ler e baixar. As chaves expiram após 90 dias, uma conta pode ter 10 chaves ativas e a revogação de uma chave tem efeito imediato.

Cada chave é exibida uma única vez e armazenada apenas como hash SHA-256. Revogar uma chave não exclui as caixas dela: as outras chaves válidas da conta mantêm o acesso até que as caixas expirem ou sejam excluídas.

Aguardar o próximo email sem sleep()

GET …/wait mantém a solicitação aberta e responde assim que uma mensagem chega, ou ao fim do tempo limite (no máximo 20 segundos) com status timeout. Passe o next_cursor da resposta anterior como after para nunca ler a mesma mensagem duas vezes.

Um timeout não é uma falha de entrega: aguarde novamente com o mesmo cursor. Só uma espera é executada por caixa, e uma espera mais recente na mesma caixa substitui a anterior; esperas em caixas diferentes são executadas em paralelo, até 2 ao mesmo tempo por conta.

Testes de email com Playwright, Cypress, pytest e CI

Dê a cada teste sua própria caixa, dispare o email de cadastro ou de redefinição de senha da sua aplicação, aguarde a chegada e faça as asserções sobre o código ou o link. Exclua a caixa no teardown.

Guarde a chave como segredo de CI, por exemplo TEMPGENERATOR_TOKEN no GitHub Actions. O Cypress pode fazer as mesmas chamadas HTTP com cy.request, e a receita em Python abaixo funciona no pytest ou em qualquer outro test runner.

Playwright (TypeScript)

import { test, expect } from '@playwright/test';

const api = `${process.env.TEMPGENERATOR_URL}/developer-api/v1`;
const headers = { Authorization: `Bearer ${process.env.TEMPGENERATOR_TOKEN}`, Accept: 'application/json' };

async function call(path: string, method = 'GET') {
  const response = await fetch(api + path, { method, headers });
  if (!response.ok) throw new Error(`${response.status} ${await response.text()}`);
  return response.status === 204 ? null : response.json();
}

async function waitForCode(inboxId: string, after = 0): Promise<string> {
  for (let attempt = 0; attempt < 3; attempt++) {
    const result = await call(`/inboxes/${inboxId}/wait?after=${after}&timeout=20`);
    for (const summary of result.messages) {
      const message = await call(`/inboxes/${inboxId}/messages/${summary.id}`);
      if (message.codes.length) return message.codes[0];
    }
    after = result.next_cursor;
  }
  throw new Error('No verification code arrived');
}

test('signup sends a verification code', async ({ page }) => {
  const inbox = await call('/inboxes', 'POST');
  try {
    await page.goto('/signup');
    await page.getByLabel('Email').fill(inbox.address);
    await page.getByRole('button', { name: 'Create account' }).click();
    await page.getByLabel('Verification code').fill(await waitForCode(inbox.id));
    await expect(page.getByText('Welcome')).toBeVisible();
  } finally {
    await call(`/inboxes/${inbox.id}`, 'DELETE');
  }
});

GitHub Actions

- name: End-to-end tests
  run: npx playwright test
  env:
    TEMPGENERATOR_URL: https://www.tempgenerator.com
    TEMPGENERATOR_TOKEN: ${{ secrets.TEMPGENERATOR_TOKEN }}

Verificação de cadastro em Python

Execute com as variáveis de ambiente definidas. O script exibe uma nova caixa: envie um email de cadastro para esse endereço a partir da sua própria aplicação de teste e pressione Enter. Ele aguarda até 15 segundos, exibe cada mensagem com seus códigos e links e exclui a caixa mesmo se a leitura falhar.

import json, os
from urllib.request import Request, urlopen

base = os.environ["TEMPGENERATOR_URL"].rstrip("/") + "/developer-api/v1"
headers = {"Authorization": "Bearer " + os.environ["TEMPGENERATOR_TOKEN"],
           "Accept": "application/json"}

def request(path, method="GET"):
    with urlopen(Request(base + path, headers=headers, method=method), timeout=30) as response:
        return json.load(response) if response.status != 204 else None

inbox = request("/inboxes", "POST")
print(json.dumps(inbox), flush=True)
try:
    input()
    result = request("/inboxes/" + inbox["id"] + "/wait?after=0&timeout=15")
    print(json.dumps(result))
    for message in result["messages"]:
        detail = request("/inboxes/" + inbox["id"] + "/messages/" + str(message["id"]))
        print(json.dumps(detail))
finally:
    request("/inboxes/" + inbox["id"], "DELETE")

Servidor MCP para agentes de IA

Endpoint https://www.tempgenerator.com/mcp, autenticado com Authorization: Bearer <key>. Streamable HTTP com o protocolo 2026-07-28; clientes mais antigos são atendidos pelo handshake 2025-11-25 ou 2025-06-18.

Conecte seu cliente

Claude Code

claude mcp add --transport http tempgenerator-mail https://www.tempgenerator.com/mcp \
  --header "Authorization: Bearer $TEMPGENERATOR_TOKEN"

Cursor: .cursor/mcp.json

{
  "mcpServers": {
    "tempgenerator-mail": {
      "url": "https://www.tempgenerator.com/mcp",
      "headers": { "Authorization": "Bearer ${env:TEMPGENERATOR_TOKEN}" }
    }
  }
}

VS Code: .vscode/mcp.json

{
  "inputs": [
    { "type": "promptString", "id": "tempgenerator-token", "description": "TempGenerator API key", "password": true }
  ],
  "servers": {
    "tempgenerator-mail": {
      "type": "http",
      "url": "https://www.tempgenerator.com/mcp",
      "headers": { "Authorization": "Bearer ${input:tempgenerator-token}" }
    }
  }
}

Claude na web e no app para desktop: adicione um conector personalizado com a URL do endpoint, escolha a opção sem login e inclua o cabeçalho de solicitação Authorization: Bearer <key>. O Claude se conecta a partir da nuvem da Anthropic, então a URL precisa ser acessível publicamente.

Ferramentas

create_inbox

Cria uma caixa privada e retorna o id e o endereço.

list_messages

Lista resumos de mensagens após um cursor, com filtros opcionais por remetente e assunto.

wait_for_message

Aguarda até 20 segundos pela próxima mensagem.

read_message

Lê o texto, os códigos, os links e a lista de anexos de uma mensagem.

delete_inbox

Exclui a caixa e as mensagens dela.

Exemplo de prompt

Crie uma caixa temporária e me passe o endereço. Depois, aguarde o email de verificação da minha aplicação em homologação e me diga o código.

Permita que os agentes concluam cadastros apenas em contas que sejam suas ou que você tenha autorização para usar. Emails recebidos não são confiáveis: o servidor nunca abre links, e os agentes nunca devem seguir instruções encontradas em uma mensagem.

SDK MCP para Python

Testado com Python 3 e o pacote oficial mcp 2.3.0: pip install "mcp>=2.3,<3". Defina antes TEMPGENERATOR_URL e TEMPGENERATOR_TOKEN.

import asyncio, os

import httpx2
from mcp import Client
from mcp.client.streamable_http import streamable_http_client

async def main():
    url = os.environ["TEMPGENERATOR_URL"].rstrip("/") + "/mcp"
    headers = {"Authorization": "Bearer " + os.environ["TEMPGENERATOR_TOKEN"]}
    async with httpx2.AsyncClient(headers=headers, timeout=httpx2.Timeout(30, read=60)) as http:
        async with Client(streamable_http_client(url, http_client=http)) as client:
            print([tool.name for tool in (await client.list_tools()).tools])
            created = await client.call_tool("create_inbox", {})
            if created.is_error:
                raise RuntimeError(created.content)
            inbox = created.structured_content
            try:
                print("Send a test email to", inbox["address"])
                waited = await client.call_tool("wait_for_message", {"inbox_id": inbox["id"], "timeout": 20})
                for summary in waited.structured_content["messages"]:
                    message = await client.call_tool("read_message", {"inbox_id": inbox["id"], "message_id": summary["id"]})
                    print(message.structured_content["subject"], message.structured_content["codes"])
            finally:
                deleted = await client.call_tool("delete_inbox", {"inbox_id": inbox["id"]})
                if deleted.is_error:
                    raise RuntimeError(deleted.content)

asyncio.run(main())

Anexos

Ao ler uma mensagem, você recebe o índice, o nome do arquivo e o tamanho de cada anexo. Baixe um com GET …/attachments/{index}: arquivos de até 10 MB são servidos como application/octet-stream com nomes de arquivo sanitizados. Clientes MCP veem a mesma lista e baixam por este endpoint REST.

Quando usar em vez de outras ferramentas

Mailpit, MailHog e Ethereal capturam os emails que sua própria aplicação envia para um servidor SMTP local ou falso, o que é ideal quando você controla as configurações de SMTP. Estas caixas são endereços reais em um domínio público, então qualquer remetente consegue alcançá-las: um serviço de terceiros, um servidor de homologação que usa seu provedor de email real ou um fluxo próximo ao de produção.

APIs de email temporário genéricas, como mail.tm ou Guerrilla Mail, são feitas para endereços descartáveis pessoais. Esta API é feita para automação: chaves com permissões e prazo de validade, uma caixa por teste, uma espera limitada com long polling, detecção de códigos e links e um servidor MCP.

Não incluído: envio de email, SMS, pré-visualizações de HTML ou de spam, domínios personalizados e login OAuth para clientes MCP.

Retenção, limites e segurança

Um domínio de recebimento pode definir uma duração menor ou um limite de mensagens mais baixo.

Somente recebimento. Trate emails e anexos como não confiáveis; nada é aberto automaticamente. Excluir uma caixa remove as mensagens dela imediatamente, e as caixas expiradas são removidas por uma limpeza agendada.

Perguntas frequentes