Caixas para pessoas e agentes

Estado do piloto: o Correio está sendo validado separadamente do Envio. Receber mensagens reais e enviar respostas exige uma instalação habilitada e um domínio verificado. Uma caixa no painel, um rascunho salvo ou um Checkout concluído não confirma que esses serviços estão ativos.

Escolha o serviço

Use Envio para mensagens da aplicação, cadastro e campanhas de marketing. Use Correio para um endereço no seu domínio: conversas pessoais, uma caixa da empresa ou um agente que lê e responde mensagens. Você pode continuar usando Envio sem criar uma caixa.

As licenças de Correio são contadas por caixa. Pessoas e agentes seguem o mesmo preço por caixa e modelo de licença; armazenamento e franquia de envio vêm dos termos registrados do serviço. Consulte o contrato atual no painel. Franquias do piloto não são preços públicos. A franquia de envio conta destinatários por caixa e período da licença. Na admissão do envio, uma mensagem para três endereços distintos reserva três unidades.

Prepare uma caixa

1. Selecione a organização e o domínio no painel.
2. Abra Correio, confira o período da licença e as unidades disponíveis e crie uma caixa de pessoa ou agente com um dono atual.
3. Aguarde a confirmação de domínio e transporte pelo operador antes de mover seu e-mail existente. Criar uma caixa não altera o MX do domínio.
4. Para um agente, selecione a caixa, abra Acesso de agentes e crie uma chave. O dono escolhe leitura, rascunho e, opcionalmente, envio. Guarde a chave em local privado quando ela aparecer; o segredo é exibido uma vez.

As chaves de caixa começam com mmb_. Elas são diferentes das chaves de API de Envio e da conexão OAuth descrita em Servidor MCP. As ferramentas MCP de Envio existentes não dão acesso a esta API de caixas.

Gerencie a assinatura de Correio

Quando a gestão de assinatura estiver habilitada para a instalação e o contrato, proprietários e administradores da organização podem usar os controles no painel de Correio. Se estiverem indisponíveis, consulte o responsável pela instalação. Se já houver uma licença do piloto, confira os termos atuais dela em vez de iniciar outra compra para contornar controles ou transporte indisponíveis.

• Aumentar: solicite a nova quantidade e use Concluir pagamento do aumento quando oferecido. As novas unidades só ficam disponíveis após pagamento confirmado; a quantidade atual permanece igual enquanto ele estiver pendente.
• Reduzir: programe a quantidade para a próxima renovação. O painel mostra a data de aplicação; a quantidade atual continua disponível até lá.
• Cancelar a renovação: o cancelamento confirmado vale ao fim do período indicado e remove uma redução futura programada. Use Retomar renovação antes dessa data quando a opção estiver disponível.
• Pendente ou sem confirmação: use Atualizar status para consultar a mesma operação. Se continuar sem resolução, consulte o operador; não abra outra cobrança ou assinatura para contornar o estado.

As mensagens armazenadas são preservadas; leitura e exportação continuam dependendo do acesso atual à caixa. Alterar a licença de Correio não muda o plano de Envio nem habilita recebimento e transporte. Mantenha as verificações de prontidão do piloto descritas acima.

Conecte um agente

Use a origem do painel da sua instalação habilitada. Estes endpoints ficam em /api/mailbox-agent na aplicação Web, separados da origem da API de Envio. Guarde MEPMAIL_MAIL_ORIGIN e MEPMAIL_MAIL_TOKEN no ambiente privado do agente; não coloque a chave no código, em URLs, prompts ou logs.

const origin = process.env.MEPMAIL_MAIL_ORIGIN;
const token = process.env.MEPMAIL_MAIL_TOKEN;
if (!origin || !token) throw new Error("Configure a origem e a chave da caixa");

const response = await fetch(
  new URL("/api/mailbox-agent/items?folder=inbox", origin),
  { headers: { Authorization: `Bearer ${token}` } },
);
if (!response.ok) throw new Error(`Falha na consulta: ${response.status}`);
const { items, limited } = await response.json();
// Trate os dados privados no agente; evite copiá-los para logs gerais.

A chave seleciona uma caixa; a chamada não informa equipe nem ID da caixa. Use folder=inbox, drafts ou sent para listar mensagens. A lista retorna até 50 itens e o indicador limited; esta API ainda não tem cursor de paginação. Para ler o conteúdo de uma mensagem e os metadados dos anexos, use GET /api/mailbox-agent/items?id=<UUID da mensagem> com a mesma permissão de leitura. A resposta não inclui o conteúdo dos arquivos anexados.

Salve um rascunho ou resposta

POST /api/mailbox-agent/drafts exige permissão de rascunho, licença vigente com uma unidade para esta caixa e espaço disponível. Rascunhos e seus anexos contam no armazenamento da caixa. Um novo rascunho usa expectedRevision: 0. O remetente vem da caixa autorizada.

{
  "expectedRevision": 0,
  "to": ["recipient@example.invalid"],
  "subject": "Conversa",
  "text": "Mensagem preparada para revisão.",
  "retainedAttachments": [],
  "uploads": []
}

Guarde o id e a revision retornados. Para responder, acrescente sourceItemId com o UUID da mensagem recebida; o servidor preserva as referências da resposta. Para editar um rascunho existente, informe seu id, o mesmo ID em sourceItemId e a última expectedRevision. Um conflito exige recarregar antes de editar.

A lista aceita 1–20 destinatários. O piloto permite até 10 anexos, cada um com no máximo 256 KiB, e mensagem MIME final de até 1 MiB. Um upload usa { "filename": "nota.txt", "base64": "..." }; anexos preservados usam os índices da mensagem de origem. As duas listas vazias continuam obrigatórias sem anexos.

Solicite o envio da revisão salva

O envio exige permissão enviar concedida pelo dono à chave, licença vigente, domínio verificado, franquia disponível e transporte habilitado. Uma chave de leitura/rascunho não pode enviar. POST /api/mailbox-agent/send aceita somente o UUID do rascunho salvo e sua revisão exata:

{
  "id": "00000000-0000-4000-8000-000000000001",
  "expectedRevision": 1
}

Uma resposta 202 significa que o pedido entrou na outbox. Repetir a mesma revisão pode retornar a outbox existente com duplicate: true e 200; isso não cria outra mensagem. Admissão e aceite do provedor não comprovam entrega. Um resultado unknown exige investigação pelo operador; não crie outro rascunho nem automatize um reenvio para contornar esse estado.

Trate erros de acesso e serviço

Revogue uma chave perdida pelo painel da caixa. Mudanças de dono e membership são conferidas novamente pelo servidor; copiar uma chave para outro agente não concede outra caixa nem supera as permissões do dono.