Receber

Marcadores e categorias

Arquive automaticamente e-mails enviados e recebidos em marcadores e dê a um agente uma categoria da qual as conversas dele nunca saem.

Marcadores

Um marcador funciona como uma pasta do Gmail. Uma mensagem pode ter até 10 marcadores, e um workspace pode ter 200. Crie um com POST /labels, liste-os com a contagem de mensagens e de não lidas usando GET /labels e leia um com GET /emails?label=Billing. Os marcadores podem ser referenciados pelo nome ou pelo ID lbl_ em qualquer lugar.

Enviar para um marcador

Corpo de POST /emails
{
  "from": "Orders <orders@example.com>",
  "to": [
    "customer@example.net"
  ],
  "subject": "Order 1042",
  "text": "Reply with a delivery window.",
  "labels": [
    "Agent/Orders"
  ]
}

Nomes de marcadores desconhecidos são criados. Todas as mensagens seguintes da conversa, incluindo as respostas do cliente, herdam os marcadores da conversa.

Categorias

Crie um marcador com "skip_inbox": true para transformá-lo em uma categoria. Os e-mails recebidos que ganham um marcador de categoria (por uma regra de arquivamento, por uma resposta a uma conversa marcada ou por POST /emails/:id/labels) são arquivados e aparecem apenas no marcador, nunca na caixa de entrada. E-mails enviados nunca aparecem na caixa de entrada. Assim, as conversas de tarefa de um agente ficam em um só lugar, nas duas direções.

Corpo de POST /labels
{
  "name": "Agent/Orders",
  "skip_inbox": true,
  "rules": [
    {
      "inbox_id": "inb_…"
    }
  ],
  "apply_to_existing": true
}

Regras de arquivamento

As regras arquivam novos e-mails automaticamente. Todas as condições definidas em uma regra precisam corresponder: inbox_id (o endereço que recebe), direction (in ou out) e trechos de from, to (To e Cc) e subject, sem diferenciar maiúsculas de minúsculas. O skip_inbox da própria regra arquiva apenas os e-mails recebidos que ela encontra. Adicione regras com POST /labels/:id/rules; apply_to_existing arquiva também os e-mails retidos.

Trabalhar em uma categoria

Consulte periodicamente GET /emails?label=Agent%2FOrders&direction=in&unread=true, leia a conversa com GET /threads/:id, responda com reply_to_email_id e depois marque como tratada com PATCH /emails/:id {"read": true}. Mova uma mensagem para dentro ou para fora com POST /emails/:id/labels {"add": [...], "remove": [...]}. O servidor MCP expõe as mesmas operações como create_label, create_label_rule, label_email e list_emails.