Recevoir

Libellés et catégories

Classez automatiquement le courrier envoyé et reçu sous des libellés, et donnez à un agent une catégorie dont ses conversations ne sortent jamais.

Libellés

Un libellé fonctionne comme un dossier Gmail. Un message peut porter jusqu’à 10 libellés, et un espace de travail peut en compter 200. Créez-en un avec POST /labels, listez-les avec leur nombre de messages et de non-lus via GET /labels, et consultez-en un avec GET /emails?label=Billing. Partout, un libellé peut être désigné par son nom ou par son identifiant lbl_.

Envoyer sous un libellé

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

Les libellés inconnus sont créés. Chaque message ultérieur de la conversation, y compris les réponses du client, hérite des libellés de la conversation.

Catégories

Créez un libellé avec "skip_inbox": true pour en faire une catégorie. Le courrier reçu qui obtient un libellé de catégorie, via une règle de classement, une réponse à une conversation libellée ou POST /emails/:id/labels, est archivé : il n’apparaît que dans le libellé, jamais dans la Boîte de réception. Le courrier envoyé n’apparaît jamais dans la Boîte de réception. Ainsi, les conversations d’un agent pour une tâche restent regroupées au même endroit, dans les deux sens.

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

Règles de classement

Les règles classent automatiquement le nouveau courrier. Chaque condition définie sur une règle doit correspondre : inbox_id (l’adresse de réception), direction (in ou out), et des sous-chaînes insensibles à la casse de from, to (To et Cc) et subject. Le skip_inbox propre à une règle n’archive que le courrier reçu qu’elle cible. Ajoutez des règles avec POST /labels/:id/rules ; apply_to_existing classe aussi le courrier déjà conservé.

Traiter une catégorie

Interrogez régulièrement GET /emails?label=Agent%2FOrders&direction=in&unread=true, lisez la conversation avec GET /threads/:id, répondez avec reply_to_email_id, puis marquez le message comme traité avec PATCH /emails/:id {"read": true}. Déplacez un message vers une catégorie ou hors de celle-ci avec POST /emails/:id/labels {"add": [...], "remove": [...]}. Le serveur MCP expose les mêmes opérations sous les noms create_label, create_label_rule, label_email et list_emails.