Receive

Labels and buckets

File sent and received mail into labels automatically, and give an agent a bucket its conversations never leave.

Labels

A label works like a Gmail folder. A message can carry up to 10 labels, and a workspace can have 200. Create one with POST /labels, list them with message and unread counts with GET /labels, and read one with GET /emails?label=Billing. Labels can be referenced by name or lbl_ ID everywhere.

Send into a label

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

Unknown label names are created. Every later message in the conversation, including the customer's replies, inherits the conversation's labels.

Buckets

Create a label with "skip_inbox": true to make it a bucket. Received mail that gets a bucket label, from a filing rule, a reply to a labelled conversation, or POST /emails/:id/labels, is archived so it appears only in the label and never in the Inbox. Sent mail never appears in the Inbox. Together, an agent's task conversations stay in one place in both directions.

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

Filing rules

Rules file new mail automatically. Every condition set on a rule must match: inbox_id (the receiving address), direction (in or out), and case-insensitive substrings of from, to (To and Cc), and subject. A rule's own skip_inbox archives only the received mail it matches. Add rules with POST /labels/:id/rules; apply_to_existing files retained mail too.

Work a bucket

Poll GET /emails?label=Agent%2FOrders&direction=in&unread=true, read the conversation with GET /threads/:id, reply with reply_to_email_id, then mark handled with PATCH /emails/:id {"read": true}. Move a message in or out with POST /emails/:id/labels {"add": [...], "remove": [...]}. The MCP server exposes the same operations as create_label, create_label_rule, label_email, and list_emails.