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 tudo que passa na autenticaçã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 que uma regra bloqueia, ou que falham na DMARC, ainda são armazenados na caixa de correio e permanecem legíveis: são arquivados fora da caixa de entrada em vez de descartados, e não disparam nenhum webhook. A única exceção é uma caixa de correio configurada como drop, que descarta tudo na porta 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 de entrada chegou à caixa de entrada), email_mailbox.thread_created e os eventos de status de entrega para mensagens que você envia. Somente 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, para que uma integração de entrada existente continue funcionando.

Para uma visualização ao vivo sem infraestrutura de webhook, conecte-se a GET /v1/email/mailboxes/{mailbox_id}/events. O stream SSE envia o tipo de evento, o ID da thread e o ID da mensagem para a atividade da caixa de correio, incluindo chegadas de spam e bloqueadas. Busque as mensagens completas com esses IDs. O stream não reproduz eventos após uma desconexão. Use webhooks para entrega durável e use os endpoints de listagem para se atualizar após uma lacuna.

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 mensagem, texto extraído e anexos da caixa, medido a partir do envio ou 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 que o seu plano não inclui é recusado com E17048.

Conteúdo ou ação	Janela de retenção
Cabeçalhos de mensagem, texto extraído e anexos da caixa	Nível selecionado: 30, 90 ou 365 dias
Corpos HTML originais e em texto simples	30 dias em todos os níveis
MIME bruto para mensagens recebidas	30 dias em todos os níveis; mensagens enviadas não possuem MIME bruto armazenado
Encaminhamento de uma mensagem no painel	Requer conteúdo original dentro da janela de 30 dias
Leitura de texto extraído ou resposta 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 tem 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 seu MIME bruto nem encaminhá-la. O texto extraído é limitado a 64 KiB por mensagem e pode omitir partes do original. Anexos armazenados antes de a retenção estendida de anexos ser habilitada 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 horária processa a exclusão em segundo plano; a limpeza física pode ficar atrás da expiração da API.

Reduzir 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 retidas se tornam elegíveis para exclusão e a próxima varredura horária as remove, então uma elevação posterior recupera apenas o que a varredura ainda não alcançou.

Elevar para um nível que o 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. Reduzir pela segunda vez é aceito depois que a primeira alteração tiver atualizado todas as mensagens armazenadas. A atualização inicia a cada dez minutos e pode levar horas para caixas de correio grandes. Até ser concluída, a API retorna E17050; tente novamente mais tarde.

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

Excluir uma caixa de correio faz com que ela pare de receber 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

Reivindique sua primeira caixa de correio: o caminho feliz da API, da criação à resposta.
Construa com IA: acione caixas de correio a partir de um agente via o 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