set_flags
Set message flags like read, unread, or flagged status on iCloud emails to organize and manage your inbox efficiently.
Instructions
Set flags on messages (read, unread, flagged, etc.)
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| action | No | Whether to add or remove the flags (default: add) | add |
| flags | Yes | Array of flags to set (e.g., ["\Seen", "\Flagged"]) | |
| mailbox | No | Mailbox name (default: INBOX) | INBOX |
| messageIds | Yes | Array of message IDs to set flags on |
Implementation Reference
- src/lib/icloud-mail-client.ts:756-808 (handler)Core implementation of setFlags method in iCloudMailClient class that adds or removes IMAP flags on all messages in the specified mailbox using imap.addFlags or imap.delFlags.
async setFlags( _messageIds: string[], flags: string[], mailbox: string = 'INBOX', action: 'add' | 'remove' = 'add' ): Promise<{ status: string; message: string }> { return new Promise((resolve) => { this.imap.openBox(mailbox, false, (err: Error) => { if (err) { resolve({ status: 'error', message: `Failed to open mailbox '${mailbox}': ${err.message}`, }); return; } this.imap.search(['ALL'], (err: Error, results: number[]) => { if (err) { resolve({ status: 'error', message: `Failed to search messages: ${err.message}`, }); return; } if (!results || results.length === 0) { resolve({ status: 'error', message: 'No messages found in mailbox', }); return; } const flagOperation = action === 'add' ? 'addFlags' : 'delFlags'; this.imap[flagOperation](results, flags, (err: Error) => { if (err) { resolve({ status: 'error', message: `Failed to ${action} flags: ${err.message}`, }); return; } resolve({ status: 'success', message: `Successfully ${action === 'add' ? 'added' : 'removed'} flags [${flags.join(', ')}] ${action === 'add' ? 'to' : 'from'} ${results.length} messages in '${mailbox}'`, }); }); }); }); }); } - src/index.ts:644-672 (handler)MCP tool dispatch handler for 'set_flags' that extracts parameters and delegates to mailClient.setFlags method.
case 'set_flags': { if (!mailClient) { throw new McpError( ErrorCode.InvalidRequest, 'iCloud Mail not configured. Please set ICLOUD_EMAIL and ICLOUD_APP_PASSWORD environment variables.' ); } const messageIds = args?.messageIds as string[]; const flags = args?.flags as string[]; const mailbox = (args?.mailbox as string) || 'INBOX'; const action = (args?.action as string) || 'add'; const result = await mailClient.setFlags( messageIds, flags, mailbox, action as 'add' | 'remove' ); return { content: [ { type: 'text', text: JSON.stringify(result, null, 2), }, ], }; } - src/index.ts:258-289 (schema)JSON schema definition for the set_flags tool input parameters, including messageIds, flags, mailbox, and action.
{ name: 'set_flags', description: 'Set flags on messages (read, unread, flagged, etc.)', inputSchema: { type: 'object', properties: { messageIds: { type: 'array', items: { type: 'string' }, description: 'Array of message IDs to set flags on', }, flags: { type: 'array', items: { type: 'string' }, description: 'Array of flags to set (e.g., ["\\Seen", "\\Flagged"])', }, mailbox: { type: 'string', description: 'Mailbox name (default: INBOX)', default: 'INBOX', }, action: { type: 'string', enum: ['add', 'remove'], description: 'Whether to add or remove the flags (default: add)', default: 'add', }, }, required: ['messageIds', 'flags'], }, }, - src/index.ts:54-384 (registration)Registration of all tools including 'set_flags' in the ListToolsRequestSchema handler.
server.setRequestHandler(ListToolsRequestSchema, async () => { return { tools: [ { name: 'get_messages', description: 'Get email messages from specified mailbox', inputSchema: { type: 'object', properties: { mailbox: { type: 'string', description: 'Mailbox name (default: INBOX)', default: 'INBOX', }, limit: { type: 'number', description: 'Maximum number of messages to retrieve', default: 10, }, unreadOnly: { type: 'boolean', description: 'Retrieve only unread messages', default: false, }, }, }, }, { name: 'send_email', description: 'Send an email through iCloud Mail', inputSchema: { type: 'object', properties: { to: { oneOf: [ { type: 'string' }, { type: 'array', items: { type: 'string' } }, ], description: 'Recipient email address(es)', }, subject: { type: 'string', description: 'Email subject', }, text: { type: 'string', description: 'Plain text email body', }, html: { type: 'string', description: 'HTML email body', }, }, required: ['to', 'subject'], }, }, { name: 'mark_as_read', description: 'Mark email messages as read', inputSchema: { type: 'object', properties: { messageIds: { type: 'array', items: { type: 'string' }, description: 'Array of message IDs to mark as read', }, mailbox: { type: 'string', description: 'Mailbox name (default: INBOX)', default: 'INBOX', }, }, required: ['messageIds'], }, }, { name: 'get_mailboxes', description: 'List all available mailboxes', inputSchema: { type: 'object', properties: {}, }, }, { name: 'test_connection', description: 'Test the email server connection (IMAP and SMTP)', inputSchema: { type: 'object', properties: {}, }, }, { name: 'create_mailbox', description: 'Create a new mailbox (folder)', inputSchema: { type: 'object', properties: { name: { type: 'string', description: 'Name of the mailbox to create', }, }, required: ['name'], }, }, { name: 'delete_mailbox', description: 'Delete an existing mailbox (folder)', inputSchema: { type: 'object', properties: { name: { type: 'string', description: 'Name of the mailbox to delete', }, }, required: ['name'], }, }, { name: 'move_messages', description: 'Move messages between mailboxes', inputSchema: { type: 'object', properties: { messageIds: { type: 'array', items: { type: 'string' }, description: 'Array of message IDs to move', }, sourceMailbox: { type: 'string', description: 'Source mailbox name', }, destinationMailbox: { type: 'string', description: 'Destination mailbox name', }, }, required: ['messageIds', 'sourceMailbox', 'destinationMailbox'], }, }, { name: 'search_messages', description: 'Search for messages using various criteria', inputSchema: { type: 'object', properties: { query: { type: 'string', description: 'Search query text (searches in subject, from, body)', }, mailbox: { type: 'string', description: 'Mailbox name (default: INBOX)', default: 'INBOX', }, limit: { type: 'number', description: 'Maximum number of messages to retrieve', default: 10, }, dateFrom: { type: 'string', description: 'Start date for search (YYYY-MM-DD format)', }, dateTo: { type: 'string', description: 'End date for search (YYYY-MM-DD format)', }, fromEmail: { type: 'string', description: 'Filter by sender email address', }, unreadOnly: { type: 'boolean', description: 'Search only unread messages', default: false, }, }, }, }, { name: 'delete_messages', description: 'Delete messages from a mailbox', inputSchema: { type: 'object', properties: { messageIds: { type: 'array', items: { type: 'string' }, description: 'Array of message IDs to delete', }, mailbox: { type: 'string', description: 'Mailbox name (default: INBOX)', default: 'INBOX', }, }, required: ['messageIds'], }, }, { name: 'set_flags', description: 'Set flags on messages (read, unread, flagged, etc.)', inputSchema: { type: 'object', properties: { messageIds: { type: 'array', items: { type: 'string' }, description: 'Array of message IDs to set flags on', }, flags: { type: 'array', items: { type: 'string' }, description: 'Array of flags to set (e.g., ["\\Seen", "\\Flagged"])', }, mailbox: { type: 'string', description: 'Mailbox name (default: INBOX)', default: 'INBOX', }, action: { type: 'string', enum: ['add', 'remove'], description: 'Whether to add or remove the flags (default: add)', default: 'add', }, }, required: ['messageIds', 'flags'], }, }, { name: 'download_attachment', description: 'Download an attachment from a specific message', inputSchema: { type: 'object', properties: { messageId: { type: 'string', description: 'Message ID containing the attachment', }, attachmentIndex: { type: 'number', description: 'Index of the attachment to download (0-based)', default: 0, }, mailbox: { type: 'string', description: 'Mailbox name (default: INBOX)', default: 'INBOX', }, }, required: ['messageId'], }, }, { name: 'auto_organize', description: 'Automatically organize emails based on rules (sender, subject keywords, etc.)', inputSchema: { type: 'object', properties: { rules: { type: 'array', items: { type: 'object', properties: { name: { type: 'string', description: 'Rule name', }, condition: { type: 'object', properties: { fromContains: { type: 'string', description: 'Move emails if sender contains this text', }, subjectContains: { type: 'string', description: 'Move emails if subject contains this text', }, }, }, action: { type: 'object', properties: { moveToMailbox: { type: 'string', description: 'Mailbox to move matching emails to', }, }, required: ['moveToMailbox'], }, }, required: ['name', 'condition', 'action'], }, description: 'Array of organization rules', }, sourceMailbox: { type: 'string', description: 'Source mailbox to organize (default: INBOX)', default: 'INBOX', }, dryRun: { type: 'boolean', description: 'If true, only shows what would be organized without moving emails', default: false, }, }, required: ['rules'], }, }, { name: 'check_config', description: 'Check if environment variables are properly configured', inputSchema: { type: 'object', properties: {}, }, }, ], }; });