How to Perform Batch Email Operations

Process multiple emails in a single operation — flag them, move them, export them, or apply categories in bulk.

v3.5.0: The server now includes a callGraphAPIBatch() infrastructure that sends up to 20 Graph API requests in a single $batch call. The batch operations below use the tool-level batch parameters; the underlying $batch API may be used internally for improved performance in future versions. Today, batch flag/unflag/complete, apply-category and folders move update the messages one at a time (one request each), so a large batch takes proportionally longer.

Batch Flag Emails#

Flag multiple emails for follow-up at once:

tool: update-email
params:
  action: "flag"
  ids: ["AAMkAGR1...", "AAMkAGR2...", "AAMkAGR3..."]
  dueDateTime: "2026-03-15T09:00:00"

A due date-time without a zone is read in your configured timezone (OUTLOOK_DEFAULT_TIMEZONE); add Z or an offset such as +11:00 to pin an exact instant. See Flag Emails for Follow-Up.

Batch unflag:

tool: update-email
params:
  action: "unflag"
  ids: ["AAMkAGR1...", "AAMkAGR2...", "AAMkAGR3..."]

Batch complete flagged emails:

tool: update-email
params:
  action: "complete"
  ids: ["AAMkAGR1...", "AAMkAGR2..."]

Batch Move Emails#

Move multiple emails to a folder:

tool: folders
params:
  action: "move"
  emailIds: "AAMkAGR1...,AAMkAGR2...,AAMkAGR3..."
  targetFolder: "Archive"

Note: emailIds in the folders tool is a comma-separated string, not an array.

Batch Export Emails#

Export multiple emails by ID:

tool: export
params:
  target: "messages"
  emailIds: ["AAMkAGR1...", "AAMkAGR2...", "AAMkAGR3..."]
  format: "markdown"
  outputDir: "~/Downloads/export/"

Or export by search criteria:

tool: export
params:
  target: "messages"
  searchQuery:
    from: "finance@company.com"
    receivedAfter: "2026-01-01"
    maxResults: 50
  format: "json"
  outputDir: "~/Documents/finance-export/"

A batch export takes at most 100 messages per call, and a search stops at searchQuery.maxResults (default 25, max 100). When either limit leaves messages out, the result says so; export the rest in another call, or split a search into date ranges with receivedAfter/receivedBefore.

Batch Apply Categories#

Apply categories to multiple emails:

tool: apply-category
params:
  messageIds: ["AAMkAGR1...", "AAMkAGR2...", "AAMkAGR3..."]
  categories: ["Project Alpha", "Urgent"]
  action: "add"

Remove a category from multiple emails:

tool: apply-category
params:
  messageIds: ["AAMkAGR1...", "AAMkAGR2..."]
  categories: ["Urgent"]
  action: "remove"

Batch Operations Summary#

Tips#

• Use search-emails first to find the email IDs you want to process
• The export tool’s searchQuery option lets you skip the search step entirely
• Combine search + batch for workflows: “Find all unread emails from Sarah and flag them for follow-up”
• Every batch operation above also accepts sharedMailbox (alias email) to work on a shared mailbox — see Access Shared Mailboxes

Related#

• Flag Emails for Follow-Up — individual flag operations
• Organise with Folders — folder management
• Export Emails — single email export
• Use Categories — category management