bulk_remove_labels

Instructions

Implementation Reference

• src/jmap-client.ts:844-874 (handler)

  The actual implementation of bulk_remove_labels. Sends a JMAP Email/set request with patch objects that null out the mailboxIds for each emailId to remove labels. Throws if some emails were not updated.

  async bulkRemoveLabels(emailIds: string[], mailboxIds: string[]): Promise<void> {
    const session = await this.getSession();
  
    // Build patch object to remove specific mailboxIds
    const patch: Record<string, any> = {};
    mailboxIds.forEach(mailboxId => {
      patch[`mailboxIds/${mailboxId}`] = null;
    });
  
    const updates: Record<string, any> = {};
    emailIds.forEach(id => {
      updates[id] = patch;
    });
  
    const request: JmapRequest = {
      using: ['urn:ietf:params:jmap:core', 'urn:ietf:params:jmap:mail'],
      methodCalls: [
        ['Email/set', {
          accountId: session.accountId,
          update: updates
        }, 'bulkRemoveLabels']
      ]
    };
  
    const response = await this.makeRequest(request);
    const result = this.getMethodResult(response, 0);
  
    if (result.notUpdated && Object.keys(result.notUpdated).length > 0) {
      throw new Error('Failed to remove labels from some emails.');
    }
  }

• src/mcp-server.ts:398-406 (registration)

  The tool handler registration in the MCP server. Receives args, validates them (emailIds and mailboxIds must be non-empty arrays), then delegates to client.bulkRemoveLabels().

  case 'bulk_remove_labels': {
    const { emailIds: rawEmailIdsBRL, mailboxIds: rawMailboxIdsBRL } = args as any;
    const emailIds = normalizeStringArray(rawEmailIdsBRL);
    const mailboxIds = normalizeStringArray(rawMailboxIdsBRL);
    if (emailIds.length === 0) throw new McpError(ErrorCode.InvalidParams, 'emailIds array is required and must not be empty');
    if (mailboxIds.length === 0) throw new McpError(ErrorCode.InvalidParams, 'mailboxIds array is required and must not be empty');
    await client.bulkRemoveLabels(emailIds, mailboxIds);
    return { content: [{ type: 'text', text: `Labels removed successfully from ${emailIds.length} emails` }] };
  }

• src/tool-definitions.ts:797-820 (schema)

  The tool definition/schema for bulk_remove_labels. Describes the tool name 'bulk_remove_labels', its description, input properties (emailIds and mailboxIds arrays), and required fields.

  writeTool(
    'bulk_remove_labels',
    'Bulk Remove Labels',
    description(
      'Remove labels from multiple emails in one call.',
      'Use when the user wants to untag a batch of specific messages together.',
      'Do not use to delete or move email.',
    ),
    {
      type: 'object',
      properties: {
        emailIds: {
          ...stringArraySchema,
          description: 'Array of email IDs to remove labels from',
        },
        mailboxIds: {
          ...stringArraySchema,
          description: 'Array of mailbox IDs to remove as labels',
        },
      },
      required: ['emailIds', 'mailboxIds'],
    },
    { idempotentHint: true },
  ),