Empfangen

Labels und Buckets

Gesendete und empfangene E-Mails automatisch mit Labels ablegen und einem Agenten einen Bucket geben, den seine Konversationen nie verlassen.

Labels

Ein Label funktioniert wie ein Ordner in Gmail. Eine Nachricht kann bis zu 10 Labels tragen, ein Workspace kann 200 haben. Legen Sie eines mit POST /labels an, listen Sie alle mit Nachrichten- und Ungelesen-Zählern über GET /labels auf und lesen Sie eines mit GET /emails?label=Billing. Labels lassen sich überall per Name oder lbl_-ID referenzieren.

In ein Label senden

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

Unbekannte Label-Namen werden angelegt. Jede spätere Nachricht der Konversation, auch die Antworten des Kunden, übernimmt die Labels der Konversation.

Buckets

Legen Sie ein Label mit "skip_inbox": true an, um daraus einen Bucket zu machen. Empfangene E-Mails, die ein Bucket-Label erhalten – durch eine Ablageregel, eine Antwort auf eine gelabelte Konversation oder POST /emails/:id/labels –, werden archiviert, sodass sie nur im Label und nie im Posteingang erscheinen. Gesendete E-Mails erscheinen nie im Posteingang. Zusammen bleiben die Aufgaben-Konversationen eines Agenten in beide Richtungen an einem Ort.

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

Ablageregeln

Regeln legen neue E-Mails automatisch ab. Jede in einer Regel gesetzte Bedingung muss zutreffen: inbox_id (die empfangende Adresse), direction (in oder out) sowie Teilzeichenfolgen von from, to (To und Cc) und subject ohne Beachtung der Groß-/Kleinschreibung. Das eigene skip_inbox einer Regel archiviert nur die empfangenen E-Mails, auf die sie zutrifft. Fügen Sie Regeln mit POST /labels/:id/rules hinzu; apply_to_existing legt auch bereits gespeicherte E-Mails ab.

Einen Bucket abarbeiten

Fragen Sie GET /emails?label=Agent%2FOrders&direction=in&unread=true ab, lesen Sie die Konversation mit GET /threads/:id, antworten Sie mit reply_to_email_id und markieren Sie sie anschließend mit PATCH /emails/:id {"read": true} als erledigt. Verschieben Sie eine Nachricht mit POST /emails/:id/labels {"add": [...], "remove": [...]} hinein oder heraus. Der MCP-Server stellt dieselben Operationen als create_label, create_label_rule, label_email und list_emails bereit.