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 fica no domínio compartilhado inbox.ai ou em um dos seus próprios domínios de envio. 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.

No seu próprio domínio, passe domain ao criar e escolha qualquer parte local, como support@acme.com. A forma como os e-mails chegam à caixa de correio depende da configuração do domínio:

• Recebimento habilitado: os e-mails chegam diretamente assim que os registros MX do domínio apontam para nós. Consulte Recebimento de e-mails.
• Recebimento não habilitado: o domínio precisa ter a propriedade verificada, e seus registros MX permanecem como estão. A caixa de correio recebe um forwarding_address, como k7q2mzxw4h6p5ra3@eu1.inbound.bird.com. Adicione no seu provedor de e-mail atual uma regra de encaminhamento para support@acme.com que aponte para esse endereço. Os e-mails encaminhados chegam à caixa de correio, e as respostas e os novos e-mails continuam saindo de support@acme.com.

Para uma caixa de correio existente em domínio próprio sem endereço de encaminhamento, abra Mailbox settings e escolha Set up forwarding. Isso mantém inalterados o endereço da caixa de correio, as mensagens, a política de recebimento e a retenção. É necessário ter permissão de escrita no gerenciamento de caixas de correio e propriedade do domínio verificada no espaço de trabalho. Um domínio reivindicado para recebimento por outro espaço de trabalho não pode receber um novo endereço de encaminhamento aqui.

O equivalente na API é POST /v1/email/mailboxes/{mailbox_id}/forwarding-address, sem corpo de solicitação. Ele retorna a caixa de correio completa com seu forwarding_address. Repetir a solicitação retorna o mesmo endereço, inclusive após exclusão e restauração; ela não troca o endereço nem retoma uma caixa de correio suspensa. O comando da CLI é bird email mailboxes forwarding-address create <mailbox-id>.

Criar um endereço não configura o encaminhamento no seu provedor, não altera o DNS nem verifica a entrega. Se o seu provedor já recebe e-mails, mantenha os registros MX dele e adicione a regra de encaminhamento lá. Se os registros MX apontam para nós, primeiro prepare a caixa de correio e a regra de encaminhamento no seu provedor e depois mova os registros MX para esse provedor. Mantenha o recebimento habilitado enquanto a alteração de DNS se propaga. Teste o encaminhamento antes de desativar o recebimento direto.

O Gmail e o Google Workspace enviam uma mensagem de confirmação para um novo endereço de encaminhamento. Abra-a nesta caixa de correio e siga as instruções de confirmação para concluir a configuração. O Microsoft 365 pode exigir que um administrador permita o encaminhamento externo. Com a política replies_only ou allowlist, verifique os e-mails bloqueados; verifique também o spam e as regras de recebimento. Uma política drop não retém a confirmação: altere a política explicitamente antes de solicitar uma nova confirmação. Uma caixa de correio suspensa precisa ser retomada para aceitar mensagens normalmente.

Mantenha uma cópia no seu provedor durante os testes. Envie uma nova mensagem de outra conta para o endereço original da caixa de correio e abra a mensagem recebida nesta caixa de correio. O endereço em Delivered to precisa corresponder ao forwarding_address para comprovar a entrega por essa rota. A API expõe isso como delivered_to. As contagens de mensagens da caixa de correio incluem a atividade de saída e não verificam o encaminhamento.

Para voltar à entrega direta, habilite o recebimento, restaure nossos registros MX e teste a entrega direta antes de remover a regra de encaminhamento do seu provedor. Rotas sobrepostas, como a entrega dupla do Google Workspace, podem colocar cada mensagem duas vezes na caixa de correio. O endereço de encaminhamento continua funcionando quando o recebimento direto é desativado e permanece o mesmo após exclusão e restauração.

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:

• 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.

Uma regra de bloqueio corresponde ao remetente do envelope ou ao endereço From:. Uma regra de permissão corresponde ao remetente do envelope ou ao endereço From: quando a mensagem tem uma assinatura DKIM válida do domínio desse endereço. O cabeçalho From: é fácil de falsificar, por isso um From: sem assinatura nunca obtém permissão. Isso cobre e-mails encaminhados, em que o Gmail e o Microsoft 365 substituem o remetente do envelope pelo próprio endereço, e e-mails de serviços de envio que usam um endereço de devolução separado. E-mails encaminhados cuja assinatura DKIM não se mantém continuam correspondendo pelo endereço do serviço de encaminhamento.

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 Forward 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.

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

• Reserve sua primeira caixa de correio: o fluxo básico do API, da criação à resposta.
• Construa com IA: acione caixas de correio a partir de um agente pelo servidor MCP.