라벨 API

라벨은 에이전트가 받은 메일에 붙이는 자기 메모입니다. 정책 · 위험 검사 · 승인에 쓰이지 않습니다. 두 경로 모두 읽기(messages:read) 권한이 필요합니다. 격리된 메일에는 붙일 수 없고 개수에도 들어가지 않습니다.

메일에 라벨 붙이기#

PUT /v1/messages/inbound/{messageId}/labels

두 모양 중 하나만 보냅니다.

{ "labels": ["invoice", "needs-reply"] }

{ "add": ["done"], "remove": ["needs-reply"] }

응답은 바뀐 뒤의 라벨입니다.

{ "message_id": "e4b2…77d0", "labels": ["done", "invoice"] }

• 라벨은 1~64자: 영문 소문자, 숫자, ., _, -. 첫 글자는 영문자나 숫자입니다.
• 메일 한 통에 20개, 에이전트 하나가 쓰는 서로 다른 라벨은 200개까지입니다.
• 없거나 격리된 메일이면 404 message_not_found입니다.

라벨 목록#

GET /v1/labels?agent_id={agentId}

{
  "agent_id": "7c21…f5a1",
  "labels": [
    { "label": "invoice", "count": 12, "unread": 3 },
    { "label": "needs-reply", "count": 4, "unread": 4 }
  ],
  "limits": { "per_message": 20, "per_agent": 200 }
}

count는 그 라벨이 붙은 보이는 메일 수, unread는 그중 아직 열지 않은 메일 수입니다.

받은편지함 거르기#

GET /v1/messages/inbound가 필터 셋을 더 받습니다. 목록의 메일마다 labels와 read도 옵니다.

메일은 GET /v1/messages/inbound/{messageId}나 MCP read_email로 처음 열 때 읽음이 됩니다. 목록만 봐서는 읽음이 되지 않습니다.

오류#