move_email

Instructions

Implementation Reference

• src/mcp-server.ts:298-303 (handler)

  Handler for the 'move_email' tool. Extracts emailId and targetMailboxId from args, validates them, calls client.moveEmail(), and returns a success message.

  case 'move_email': {
    const { emailId, targetMailboxId } = args as any;
    if (!emailId || !targetMailboxId) throw new McpError(ErrorCode.InvalidParams, 'emailId and targetMailboxId are required');
    await client.moveEmail(emailId, targetMailboxId);
    return { content: [{ type: 'text', text: 'Email moved successfully' }] };
  }

• src/jmap-client.ts:708-752 (helper)

  JMAP client method that implements the email move operation. Fetches the email's current mailboxIds, builds a JMAP patch (removes from all current mailboxes, adds to target), and sends an Email/set request.

  async moveEmail(emailId: string, targetMailboxId: string): Promise<void> {
    const session = await this.getSession();
  
    // Fetch current mailboxIds to build a proper JMAP patch
    const getRequest: JmapRequest = {
      using: ['urn:ietf:params:jmap:core', 'urn:ietf:params:jmap:mail'],
      methodCalls: [
        ['Email/get', {
          accountId: session.accountId,
          ids: [emailId],
          properties: ['mailboxIds']
        }, 'getEmail']
      ]
    };
    const getResponse = await this.makeRequest(getRequest);
    const email = this.getListResult(getResponse, 0)[0];
  
    // Build patch: remove from all current mailboxes, add to target
    const patch: Record<string, boolean | null> = {};
    if (email?.mailboxIds) {
      for (const mbId of Object.keys(email.mailboxIds)) {
        patch[`mailboxIds/${mbId}`] = null;
      }
    }
    patch[`mailboxIds/${targetMailboxId}`] = true;
  
    const request: JmapRequest = {
      using: ['urn:ietf:params:jmap:core', 'urn:ietf:params:jmap:mail'],
      methodCalls: [
        ['Email/set', {
          accountId: session.accountId,
          update: {
            [emailId]: patch
          }
        }, 'moveEmail']
      ]
    };
  
    const response = await this.makeRequest(request);
    const result = this.getMethodResult(response, 0);
  
    if (result.notUpdated && result.notUpdated[emailId]) {
      throw new Error('Failed to move email.');
    }
  }

• src/tool-definitions.ts:478-501 (schema)

  Tool definition/schema for 'move_email' including description and input schema with required emailId and targetMailboxId parameters.

  writeTool(
    'move_email',
    'Move Email',
    description(
      'Move one email to a different Fastmail mailbox.',
      'Use when the user wants a specific message filed into another mailbox.',
      'Do not use to add extra labels while keeping the current mailbox membership; use add_labels.',
    ),
    {
      type: 'object',
      properties: {
        emailId: {
          type: 'string',
          description: 'ID of the email to move',
        },
        targetMailboxId: {
          type: 'string',
          description: 'ID of the target mailbox',
        },
      },
      required: ['emailId', 'targetMailboxId'],
    },
    { idempotentHint: true },
  ),

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

  Tool registration via ListToolsRequestSchema handler that returns TOOL_DEFINITIONS, which includes the move_email definition.

  server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: TOOL_DEFINITIONS }));