MepMail Docs

Caixas para pessoas e agentes

Separe uma caixa pessoal ou de agente do envio de campanhas e mensagens da aplicação.

Receber mensagens reais exige um domínio verificado com o MX apontando para o MepMail e o recebimento ativado nele. Criar uma caixa, salvar um rascunho ou concluir um Checkout não altera o MX do domínio.

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.

Planos e limites

O Correio é vendido em três planos mensais, com ou sem plano de Envio. Pessoas e agentes custam o mesmo.

PlanoCaixasArmazenamentoDestinatários enviados por mêsMensagens recebidas por mêsPreço por mês
Solo11 GiB5002.000US$ 2,90 (R$ 14,90 no Brasil)
Duo33 GiB2.0005.000US$ 5,90 (R$ 29,90)
Equipe1010 GiB10.00010.000US$ 12,90 (R$ 64,90)
  • Todos os limites são divididos entre as caixas da equipe e renovam a cada mês de cobrança. Nada é cobrado além do plano.
  • Domínios: Solo e Duo incluem 3 domínios de envio, Equipe 10, além do que um plano do Envio já permite.
  • O envio conta destinatários: uma mensagem para três endereços distintos conta três. O plano também limita os bytes enviados (tamanho da mensagem vezes os destinatários): 256 MiB, 1 GiB e 5 GiB por mês. Passado qualquer limite, o envio é recusado com quota até o mês de cobrança seguinte ou um upgrade.
  • O recebimento conta cada mensagem recebida uma vez, não importa quantas caixas ou aliases da equipe ela alcance; a reentrega da mesma mensagem não conta de novo, e apagar mensagens não devolve a franquia. O plano também limita os bytes recebidos: 512 MiB, 1,5 GiB e 3 GiB por mês.
  • O recebimento pausa depois do limite de recebidas mais 10% de margem, ou com o armazenamento cheio. Os remetentes recebem então uma devolução permanente de "caixa indisponível" (5.1.1) e nada é guardado. O recebimento volta sozinho no mês de cobrança seguinte, após um upgrade ou, se o armazenamento estava cheio, em até um minuto depois de liberar espaço. O que foi aceito antes da pausa é sempre guardado.
  • Com o armazenamento cheio, leitura, busca, download de anexos e a API continuam funcionando; novos rascunhos e envios são recusados até haver espaço. Libere com Esvaziar lixeira, ou Excluir para sempre nas mensagens da lixeira (as enviadas ficam; as cópias nos backups somem em até 30 dias), ou passe para um plano maior.
  • E-mails: os donos da equipe recebem um e-mail aos 80% e aos 100% de cada limite, uma vez por mês de cobrança, e quando o recebimento pausa.
  • Teste grátis: a primeira compra começa com 7 dias grátis; o cartão é obrigatório. Durante o teste, a equipe envia para no máximo 50 destinatários por dia e 200 no total.
  • Contratos anteriores a estes planos mantêm preço e condições.

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. Antes de mover seu e-mail existente, crie todas as caixas e apelidos que o domínio recebe e só então troque o MX; depois ative o recebimento em Correio → Recebimento, que confere o MX. 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; não inicie outra compra para contornar controles indisponíveis.

  • Trocar de plano: um plano maior vale na hora e cobra agora a diferença proporcional; durante o teste grátis, encerra o teste e cobra o novo plano. Um plano menor vale na hora quando suas caixas, o armazenamento e o uso deste mês couberem nele, sem reembolso do mês em curso. A data de cobrança não muda.
  • Contratos anteriores aos planos: solicite a nova quantidade e use Concluir pagamento do aumento quando oferecido (as novas unidades só ficam disponíveis após pagamento confirmado), ou programe uma redução para a próxima renovação. Também é possível passar esse contrato para um plano.
  • 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, fale com o suporte (suporte@mepmail.dev) ou, numa instalação própria, com 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. Trocar o plano de Correio não muda o plano de Envio nem ativa o recebimento.

Conecte um agente por MCP

Agentes que falam MCP (Claude Code, Claude Desktop, Cursor e outros) usam a caixa como ferramentas, sem escrever código: mailbox_list_messages, mailbox_read_message, mailbox_save_draft e mailbox_send_draft. Ao criar a chave em Acesso de agentes, o painel mostra o comando pronto. No MepMail Cloud:

Claude Code
claude mcp add --transport http mepmail-correio https://api.mepmail.dev/mcp/correio --header "Authorization: Bearer mmb_..."

Em outros clientes, adicione um servidor Streamable HTTP em https://api.mepmail.dev/mcp/correio com o cabeçalho Authorization: Bearer seguido da chave da caixa. As ferramentas respeitam as mesmas permissões, limites e registros de atividade da API abaixo. O conteúdo das mensagens volta marcado como dado não confiável: o agente não deve seguir instruções que cheguem por e-mail.

Conecte um agente pela API

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.

Leia a entrada desta caixa
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, as mais novas primeiro. A lista retorna até limit itens (padrão 50, máximo 100), o indicador limited e nextCursor: passe-o em cursor para a página seguinte.

Uma chave de equipe (mmt_) cobre várias caixas suas: liste-as em GET /api/mailbox-agent/mailboxes e informe a caixa em cada chamada com o cabeçalho MepMail-Mailbox (ID ou endereço), a menos que a chave tenha uma padrão. Veja a receita Um agente, várias caixas. 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.

Para reagir a e-mail novo sem consultar a lista, assine um webhook em mailbox.received: ele dispara quando uma mensagem chega à Entrada de uma caixa de agente e traz só os IDs da caixa e da mensagem, que você lê com este endpoint.

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.

Corpo de um novo rascunho
{
  "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.

to aceita 1–20 endereços. Os campos opcionais cc e bcc acrescentam cópias e cópias ocultas, com To, Cc e Cco somando no máximo 20. A cópia oculta recebe a mensagem sem que os outros destinatários a vejam: o cabeçalho Bcc fica só no rascunho salvo e na cópia de Enviados, e cada destinatário em Cco conta na franquia de envio como To e Cc. Rascunhos desta API aceitam 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. POST /api/mailbox-agent/send aceita somente o UUID do rascunho salvo e sua revisão exata:

Corpo do pedido de envio — substitua pelos valores do rascunho salvo
{
  "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: fale com o suporte ou com o operador; não crie outro rascunho nem automatize um reenvio para contornar esse estado.

Aprovação do dono

Uma chave de leitura/rascunho, sem a permissão enviar, não envia sozinha: o mesmo pedido registra que o agente quer enviar aquela revisão e responde 202 com "status": "awaiting_approval". O dono da caixa recebe um e-mail (no máximo um a cada 10 minutos por caixa) e vê o rascunho marcado como Aguardando sua aprovação no Correio; ele confere e envia, edita ou apaga. Repetir o pedido da mesma revisão responde 200 com duplicate: true. Editar o rascunho cria outra revisão, que precisa de um novo pedido. É assim que se mantém uma pessoa no circuito: crie a chave do agente sem a permissão de envio.

Trate erros de acesso e serviço

StatusPróximo passo
400Confira campos, UUID e revisão.
401Informe a chave da caixa no cabeçalho Bearer.
403Confira permissões, expiração, revogação e o dono atual da caixa.
404Confirme que o recurso está habilitado e que a mensagem existe.
409Recarregue o rascunho e confira licença, armazenamento e franquia de envio.
413Reduza o tamanho do pedido ou dos anexos.
503Preserve o rascunho e fale com o suporte ou com o operador; não suponha que o envio foi descartado.

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.

Nesta página