Caixas de correio de agente

Uma caixa de correio de agente é uma caixa de entrada endereçável que o seu código gerencia pela API. Leia e filtre suas threads, responda a mensagens ou componha novos e-mails sem rodar um servidor IMAP nem interpretar MIME bruto.

Uma caixa de correio existe no domínio compartilhado inbox.ai ou no seu próprio domínio de envio habilitado para recebimento. O endereço é reservado no momento em que você cria a caixa e permanece seu: a parte local é reservada ao seu espaço de trabalho e nunca é concedida a mais ninguém, mesmo depois que você exclui a caixa de correio.

Endereços

Toda caixa de correio tem um endereço, {local_part}@inbox.ai. Você obtém um endereço de duas formas:

Gerado: omita a parte local e geramos uma livre de colisão para você (a7f3k2@inbox.ai). Sempre disponível.
Personalizado: solicite uma parte local específica (support@inbox.ai). Identificadores personalizados são globalmente únicos, por ordem de chegada, e fazem parte da cota de um plano pago; um espaço de trabalho gratuito usa endereços gerados.

Um endereço é imutável depois de criado. Para alterá-lo, crie uma nova caixa de correio e exclua a antiga. A parte local antiga fica retida por 30 dias (sua janela de restauração) antes de poder ser reivindicada novamente, e permanece reservada ao seu espaço de trabalho.

Threads e mensagens

E-mails recebidos e enviados são agrupados em threads, uma por conversa. Uma thread contém os endereços participantes, um contador de não lidas, a direção da mensagem mais recente (inbound ou outbound) e o timestamp da atividade mais recente. Respostas são incorporadas à thread que respondem; uma nova composição inicia uma nova thread.

Cada mensagem expõe cabeçalhos, texto simples extraído com histórico de citações removido e anexos. Os corpos originais ficam disponíveis por 30 dias; o MIME bruto está disponível apenas para mensagens recebidas. Os IDs de mensagem são prefixados pela direção: rem_ para uma mensagem recebida, em_ para uma que você enviou.

Decidindo o que entra

Dois controles ficam à frente da caixa de entrada, ambos verificados contra o remetente do envelope em vez do cabeçalho falsificável From::

Política de recebimento: o padrão geral da caixa de correio.
- open aceita e-mails após as regras de bloqueio. Resultados de SPF e DKIM não alteram essa política de admissão.
- replies_only aceita apenas e-mails que continuam uma thread já existente na caixa de correio.
- allowlist aceita apenas remetentes que suas regras permitem, além de respostas a uma thread existente.
- drop descarta tudo, sem exceções.
Regras de recebimento: entradas de permissão ou bloqueio por remetente, correspondendo a um endereço completo ou um domínio (uma regra de domínio também abrange seus subdomínios). Um bloqueio sempre prevalece sobre uma permissão.

E-mails bloqueados por uma regra são armazenados na caixa de correio e continuam legíveis. Eles são arquivados fora da caixa de entrada e não disparam webhook. A única exceção é uma caixa de correio configurada como drop, que descarta tudo na entrada em vez de arquivar.

Envio

Uma caixa de correio envia de duas formas pela API: responder a uma mensagem (a mensagem de saída é incorporada àquela thread) ou compor uma nova mensagem (que abre uma nova thread). No painel, abra uma mensagem e escolha Encaminhar para enviar o corpo e os anexos originais a novos destinatários, dentro da janela de 30 dias do conteúdo original. O e-mail é enviado a partir do endereço da própria caixa de correio, com o nome de exibição e o Reply-To padrão que você configurou nela. O status de entrega é vinculado de volta à mensagem enviada, para que você veja se a resposta foi entregue ou devolvida.

Eventos

Assine a família de webhooks email_mailbox.* para acionar um agente sem polling: email_mailbox.message_received (e-mail recebido chegou à caixa de entrada), email_mailbox.thread_created, e os eventos de status de entrega para mensagens que você envia. Apenas e-mails da caixa de entrada são distribuídos; spam e e-mails bloqueados por regras são armazenados silenciosamente, de modo que uma caixa de correio inundada não se amplifique em uma enxurrada de webhooks. E-mails da caixa de entrada também disparam o evento padrão email.received, então uma integração de entrada existente continua funcionando. Ambos os eventos incluem resultados de autenticação. Verifique esses campos antes do roteamento automatizado: a entrega na caixa de entrada por si só não significa que o remetente foi verificado.

Retenção e exclusão

O nível de retenção de uma caixa de correio controla por quanto tempo você pode ler cabeçalhos de mensagens, texto extraído e anexos da caixa de correio, contado a partir do envio ou do recebimento. O padrão é 30 dias. Se o seu plano inclui retenção de 90 ou 365 dias, defina retention_tier ao criar ou atualizar. Um nível não incluído no seu plano é recusado com E17048.

Conteúdo ou ação	Janela de retenção
Cabeçalhos de mensagens, texto extraído e anexos da caixa de correio	Nível selecionado: 30, 90 ou 365 dias
Corpos originais em HTML e texto simples	30 dias em qualquer nível
MIME bruto para mensagens recebidas	30 dias em qualquer nível; mensagens enviadas não possuem MIME bruto armazenado
Encaminhar uma mensagem no painel	Requer conteúdo original dentro da janela de 30 dias
Ler texto extraído ou responder com novo conteúdo	Disponível enquanto a mensagem estiver retida

Por exemplo, no dia 40, uma mensagem em uma caixa de correio de 90 dias ainda possui texto extraído legível e pesquisável e anexos retidos. Você pode responder com novo conteúdo, mas não pode abrir o corpo original, baixar o MIME bruto ou encaminhá-la. O texto extraído é limitado a 64 KiB por mensagem e pode omitir partes do original. Anexos armazenados antes da ativação da retenção estendida de anexos mantêm sua expiração original de aproximadamente 31 dias; mudar de nível não os migra. Elevar o nível não recupera conteúdo que já foi excluído.

As mensagens deixam de ser retornadas pela API quando sua retenção expira. Uma varredura a cada hora processa a exclusão em segundo plano; a limpeza física pode ficar atrás da expiração de API.

Rebaixar o nível entra em vigor nas leituras imediatamente: qualquer coisa mais antiga que o novo limite deixa de ser retornada na hora. Você tem dez minutos para desfazer, e dez minutos é a única garantia: eleve o nível novamente dentro dessa janela e nada é perdido. Depois disso, as mensagens abandonadas se tornam elegíveis para exclusão e a próxima varredura horária as remove, de modo que uma elevação posterior recupera apenas o que a varredura ainda não alcançou.

Elevar para um nível que seu plano inclui é aceito a qualquer momento, inclusive enquanto uma alteração anterior ainda está sendo aplicada. A atualização em segundo plano é independente da janela de desfazer de dez minutos. Rebaixar uma segunda vez é aceito após a primeira alteração ter atualizado todas as mensagens armazenadas. A atualização inicia a cada dez minutos e pode levar horas em caixas de correio grandes. Até que ela termine, a API retorna E17050; tente novamente mais tarde.

Se o seu plano define uma cota finita de armazenamento de caixa de correio, uma única cota é compartilhada por todas as caixas de correio ativas ou restauráveis. Cada caixa de correio informa sua parte como size_bytes. Um plano sem cota finita possui armazenamento ilimitado de caixa de correio. Quando as caixas de correio juntas atingem a cota finita, o envio é recusado com E17049 até que você libere espaço em qualquer uma delas.

Excluir uma caixa de correio interrompe o recebimento de e-mails imediatamente. A caixa de correio pode ser restaurada por 30 dias, enquanto a expiração normal de retenção de mensagens continua. Após 30 dias, a exclusão permanente remove a caixa de correio e suas mensagens restantes. Quando a exclusão permanente começa, a restauração é recusada mesmo que a limpeza ainda esteja em andamento. O endereço permanece reservado ao seu espaço de trabalho.

Próximos passos

Crie sua primeira caixa de correio: o caminho feliz do API, da criação à resposta.
Construa com IA: acione caixas de correio a partir de um agente pelo servidor MCP.

Recursos relacionados

Continue com a documentação, guias e exemplos sobre este tópico. Os recursos estão em inglês.

Assista ao guiaGetting started with email Explore a funcionalidadeEmail Siga o percurso de aprendizagemBuild your first integration Guia de implementaçãoSend your first email

Experimente na prática e obtenha um resumo de implementação