Saltar para a documentação
API

Caixas descartáveis

Um endereço funcional para quem não tem nenhum: sem conta, sem chave, e desaparecido no mesmo dia.

O que é uma caixa descartável

Quem chama pede um endereço num domínio que esta instalação possui, observa-o durante alguns minutos, lê o que lá chegar, e abandona-o. Existe para o código de confirmação, para a pergunta "o que é que este formulário envia afinal", e para o registo que não quer associado ao endereço que ainda vai estar a usar daqui a cinco anos.

  • Recebe e mais nada. Não há envio: uma caixa destas não tem identidade de remetente, e nenhuma destas nove chamadas põe uma mensagem no fio.
  • A validade é de 60 minutos por omissão e pode ser esticada até 24 horas, uma hora de cada vez.
  • Guarda 50 mensagens, contadas à medida que chegam. O correio que chega a uma caixa cheia é descartado em vez de posto em fila, e eliminar uma mensagem não compra espaço para outra.
  • No fim da validade o correio é ELIMINADO, não escondido e não arquivado. A linha sobrevive-lhe uma semana para que o endereço não possa ser reemitido enquanto um remetente lento ainda estiver a insistir nele.
  • Nada disto toca numa caixa de correio. Uma mensagem descartável vive na sua própria tabela, e nenhuma consulta neste caminho consegue alcançar uma real.

Estas são as mesmas chamadas que a ferramenta gratuita deste site faz, por isso tudo o que a página faz o seu código também faz. A API está aqui para o caso em que a página não serve: uma suite de testes que quer um endereço novo por execução.

O endereço não é a credencial

Um endereço descartável é escrito num formulário de registo no momento em que é emitido. Daí viaja num cabeçalho To:, pelos registos do remetente, e vai parar ao CRM que estiver do outro lado. Se conhecer o endereço bastasse para ler o correio, a ferramenta divulgaria todas as caixas que emitisse, por construção, e precisamente à parte que quem chamou estava a manter à distância.

Por isso criar uma caixa devolve um segundo valor: um token, 32 bytes aleatórios como oe_inbox_ mais 43 caracteres base64url. Aparece nessa única resposta e em mais nenhuma. A linha guarda apenas um hash com chave dele, por isso nada o recupera, nem um pedido de suporte nem um dump da base de dados. Perca o token e perdeu a caixa, que é o desfecho correto para uma credencial que lê o correio de alguém.

O fluxo completo
# 1. Mint one. This is the only response that carries a token.curl -s -X POST "$OE/temp-mail/inboxes" -H "Content-Type: application/json" -d '{}' # 2. Keep it, and read with it.export INBOX="Authorization: Bearer oe_inbox_kQ8v…"curl -s "$OE/temp-mail/inboxes/tinb_9c2f…/messages" -H "$INBOX"

Envie uma chave de API oe_live_ ou oe_test_ para uma destas rotas e é recusada como invalid_credential_type em vez de um 401 simples. Aqui dois tipos de credencial partilham um host e um cabeçalho, e "não autorizado" deixá-lo-ia a adivinhar qual das suas estava errada.

A validade, e como estendê-la

Uma hora, em vez dos dez minutos que dão o nome ao género. Dez chegam para um código de confirmação e não chegam para a outra metade daquilo para que estas são usadas: um período experimental que lhe volta a escrever na manhã seguinte, um formulário preenchido duas vezes porque a primeira tentativa expirou. ttlMinutes na criação pede outra coisa, de 1 a 1440; um número fora disso é recusado com um 422 em vez de ajustado em silêncio, porque uma expiração que não pediu é uma com que já contava de outra forma.

POST /temp-mail/inboxes/{id}/extend acrescenta uma hora à expiração, e não ao momento atual, por isso estender cedo não desperdiça o tempo que lhe resta. Funciona 23 vezes, e o dia contado a partir do momento em que a caixa foi criada é o mais duro dos dois tectos: uma validade que já lá chega não tem nada para comprar, por poucas extensões que tenham sido gastas. extensionsLeft em todas as respostas de caixa conta ambos, para que um cliente possa desativar o botão; a zero, a chamada responde 409 extension_limit.

Uma caixa expirada deixa de autenticar no instante em que expira: o seu token responde 404 sem esperar pela varredura. A varredura é o que elimina o correio, e corre no cron horário; DELETE /temp-mail/inboxes/{id} é a mesma eliminação a pedido.

Os tectos

Tudo isto são linhas contadas e não um limitador de taxa. Não há neste código nenhum limitador a que recorrer, e dizê-lo é mais útil do que sugerir uma defesa que não existe. Estão colocados onde o dano seria: na criação, e no armazenamento.

TectoValorO que acontece ao atingi-lo
Validade60 minutos, extensível até 24 horas409 conflict_error / extension_limit
Mensagens por caixa50O correio seguinte é descartado à porta. Não é escrita nenhuma devolução, nada fica em fila, e eliminar uma mensagem não devolve o lugar.
Caixas criadas6 por hora, 30 por dia, por quem chama429 rate_limit_error / too_many_inboxes
Corpo guardado2 MBtruncated: true na mensagem; o resto dela desapareceu.
Bytes de anexo8 MB cadacontent é null e os metadados são mantidos, o que não é o mesmo que um ficheiro vazio.

O tecto de criação conta contra um hash com chave do IP do cliente, e uma caixa destruída continua a contar, por isso deitar uma fora não é forma de comprar outra. Atrás do proxy de outra pessoa, o cabeçalho encaminhado pode ser falsificado, o que é uma fraqueza conhecida do tecto e não um buraco na credencial: nada aqui autoriza com base nesse valor.

O que não está aqui

Ainda não disponível

Descobrir por tentativa é pior do que ser avisado:

  • Sem envio, de forma nenhuma. Uma caixa descartável não tem nenhuma ligação a partir da qual enviar, e acrescentar uma transformaria um endpoint anónimo e não autenticado num open relay.
  • Sem mudança de nome. Mudar de endereço significa criar uma segunda caixa: renomear no lugar libertaria a local-part antiga no instante em que fosse clicado, e uma confirmação já a caminho seria depois entregue a quem a recebesse a seguir.
  • Sem regras, filtros, reencaminhamento, webhooks ou IA. spam é uma flag na mensagem e nada agiu sobre ela. Nada foi arquivado, e nada aqui é resumido ou indexado.
  • Sem devoluções. O correio para um domínio do conjunto que não nomeie nem uma caixa descartável ativa nem um endereço criado pelo operador é descartado em silêncio, de propósito: um gerador público de endereços atrai ataques de dicionário, e escrever um relatório de entrega para o caminho de retorno que o ataque indicar tornaria a instalação numa fonte de backscatter.
  • Sem domínio configurado não há serviço. Quando TEMP_MAIL_DOMAINS está vazio, GET /temp-mail/domains responde com uma lista vazia e criar uma caixa responde 503 temp_mail_unavailable. A entrega de correio a um domínio do conjunto não foi observada de ponta a ponta num domínio ativo.

Configurar um domínio, se for você a gerir a instalação

A lista é configuração: o que TEMP_MAIL_DOMAINS nomear é o que é distribuído. Nada automatiza o DNS, por isso quatro destes cinco passos são uma pessoa num registrar.

  1. Registe um domínio para isso. Use um que esteja disposto a deixar estranhos distribuir. Todos os endereços nele partilham a sua reputação, que é também a razão pela qual o seletor espalha as novas caixas pelo conjunto ao acaso em vez de encher o primeiro.
  2. Acrescente-o na aplicação em Definições → Domínios. Isso cria a identidade de envio e imprime os registos DNS a publicar.
  3. Publique os registos MX, SPF, DKIM e o TXT _openemail-challenge no registrar. A verificação lê o DNS ao vivo e é reavaliada no cron; só um domínio verificado é alguma vez oferecido.
  4. Acrescente o domínio verificado a TEMP_MAIL_DOMAINS no servidor, separado por vírgulas. Até estar listado, é um domínio vulgar do espaço de trabalho.
  5. Deixe o catch-all LIGADO. É o que faz um endereço descartável existir sem ser criado, porque o correio para qualquer local part é aceite e lido antes da procura habitual de destinatário, de modo que nunca é escrita nenhuma linha de endereço para um domínio do conjunto; deixar o catch-all ligado começaria a arquivar correio descartável numa caixa de correio real.

As local-parts reservadas (postmaster, abuse, security e as restantes do RFC 2142) nunca podem ser descartáveis e caem para a caixa de correio normal. Um domínio do conjunto que engula os seus próprios relatórios de abuso é um domínio que deixa de conseguir entregar seja onde for. Um endereço que você próprio crie num domínio do conjunto, como legal@ ou privacy@, comporta-se da mesma maneira: o correio para ele chega à sua caixa de correio, e ninguém o pode receber como endereço descartável.

Nesta secção