## Tool: `unlabel_message`

> [!WARNING]
> **Developer Preview:** Available as part of the [Google Workspace Developer Preview Program](https://developers.google.com/workspace/preview), which grants early access to certain features.

Removes one or more labels from a specific message in the authenticated user's Gmail account. To find the message ID, use tools like `search_threads` or `get_thread`. If unsure of a user label's ID, use the `list_labels` tool first to discover available labels and their IDs.

The following sample demonstrate how to use `curl` to invoke the `unlabel_message` MCP tool.

| Curl Request |
|---|
| ```bash curl --location 'https://gmailmcp.googleapis.com/mcp/v1' \ --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \ --header 'content-type: application/json' \ --header 'accept: application/json, text/event-stream' \ --data '{ "method": "tools/call", "params": { "name": "unlabel_message", "arguments": { // provide these details according to the tool's MCP specification } }, "jsonrpc": "2.0", "id": 1 }' ``` |

## Input Schema

Request message for UnlabelMessage RPC.

### UnlabelMessageRequest

| JSON representation |
|---|
| ``` { "messageId": string, "labelIds": [ string ] } ``` |

| Fields ||
|---|---|
| `messageId` | `string` Required. The ID of the message to remove the labels from. |
| `labelIds[]` | `string` Required. The IDs of the labels to remove. Can be a system label ID (e.g., 'INBOX', 'TRASH', 'SPAM', 'STARRED', 'UNREAD', 'IMPORTANT') or a user-defined label ID. The tool accepts `label_ids` and not label names. Use the list_labels tool to get the corresponding label id to a display name for user-defined labels. |

## Output Schema

Response message for UnlabelMessage RPC.

### Tool Annotations

Destructive Hint: ✅ \| Idempotent Hint: ✅ \| Read Only Hint: ❌ \| Open World Hint: ❌

## Authorization Scopes

Requires one of the following OAuth scopes:

- `https://mail.google.com/`
- `https://www.googleapis.com/auth/gmail.modify`