Get emails from a mailbox folder.

Args: folder: Folder name (Inbox, Sent, Drafts, Deleted, Junk, or custom name). limit: Maximum number of emails to return (default 10, max 50). offset: Number of emails to skip for pagination. include_body: If True, fetch full body for each email (slower). unread_only: If True, only return unread emails. ids_only: If True, return only item IDs and dates (compact, for bulk ops). Max limit raised to 500 in this mode.

Get a single email with full body and details.

Args: item_id: The Exchange ItemId of the email to retrieve.

Send a new email.

Args: to: Comma-separated list of recipient email addresses. subject: Email subject line. body: Email body text. cc: Comma-separated CC recipients (optional). bcc: Comma-separated BCC recipients (optional). importance: Email importance: Low, Normal, or High (default Normal). is_html: If True, body is treated as HTML. Otherwise plain text.

Reply to an email.

Args: item_id: The Exchange ItemId of the email to reply to. body: Reply body text. reply_all: If True, reply to all recipients. Otherwise reply to sender only.

Forward an email to other recipients.

Args: item_id: The Exchange ItemId of the email to forward. to: Comma-separated list of recipient email addresses. body: Optional message to include above the forwarded content.

Mark one or more emails as read or unread.

Args: item_ids: List of Exchange ItemIds to update. is_read: True to mark as read, False to mark as unread (default True).

Move one or more emails to a different folder.

Args: item_ids: List of Exchange ItemIds to move. target_folder: Destination folder name (e.g. Inbox, Sent, Deleted, or custom).

Delete one or more emails.

Args: item_ids: List of Exchange ItemIds to delete. permanent: If True, permanently delete (HardDelete). Otherwise move to Deleted Items.

Download all file attachments from an email to disk.

Args: item_id: The Exchange ItemId of the email to download attachments from. target_folder: Local directory to save files (default /tmp/attachments).

Extract all hyperlinks from an email's HTML body.

Args: item_id: The Exchange ItemId of the email to extract links from.

Get calendar events within a date range.

Args: start_date: Start date in YYYY-MM-DD format. end_date: End date in YYYY-MM-DD format. include_body: If True, fetch full event details (organizer, attendees, body) via GetItem for each event. Slower but more complete. Ignored when expand_recurring=True. expand_recurring: If True, show every individual occurrence of recurring meetings (via GetUserAvailability). This gives an accurate count of all events but returns fewer fields per event (no item_id, attendees, or body). Default False.

Returns: JSON array of event objects with subject, start, end, location, attendees, etc.

Create a new calendar meeting.

Args: subject: Meeting subject/topic. date: Meeting date in YYYY-MM-DD format. start_time: Start time in HH:MM format. duration_minutes: Duration in minutes (default 30). required_attendees: List of email addresses for required attendees. optional_attendees: List of email addresses for optional attendees. location: Location or video link. description: Meeting description/body text. is_all_day: Whether this is an all-day event. reminder_minutes: Minutes before start for reminder (default 15). importance: Importance level: Low, Normal, or High. sensitivity: Sensitivity: Normal, Personal, Private, or Confidential.

Returns: JSON object with creation result including item_id on success.

Update an existing calendar meeting.

Internally cancels the old meeting and creates a new one with updated fields, because OWA's JSON API does not support UpdateItem for calendar items reliably. Unchanged fields are preserved from the original meeting.

Args: item_id: The ItemId of the meeting to update (from get_calendar_events). subject: New subject (omit to keep original). date: New date in YYYY-MM-DD format (omit to keep original). start_time: New start time in HH:MM format (omit to keep original). duration_minutes: New duration in minutes (omit to keep original). location: New location (omit to keep original). description: New description/body text (omit to keep original). required_attendees: Email addresses for required attendees. Replaces existing list. Omit to keep original attendees. optional_attendees: Email addresses for optional attendees. Replaces existing list. Omit to keep original attendees. change_key: Ignored (kept for backward compatibility).

Returns: JSON object with update result including new item_id.

Cancel (delete) a calendar meeting and notify attendees.

Args: item_id: The ItemId of the meeting to cancel. message: Optional cancellation message to attendees.

Returns: JSON object with cancellation result.

Respond to a meeting invitation (accept, decline, or tentative).

Args: item_id: The ItemId of the meeting to respond to. response: Response type: "Accept", "Decline", or "Tentative". message: Optional message to include with the response.

Returns: JSON object with response result.

Download all file attachments from a calendar event to disk.

Args: item_id: The Exchange ItemId of the calendar event. target_folder: Local directory to save files (default /tmp/attachments).

Extract all hyperlinks from a calendar event's HTML description.

Args: item_id: The Exchange ItemId of the calendar event to extract links from.

Search for people in the corporate directory.

Looks up employees by name, email, department, or keyword using the Exchange ResolveNames API against Active Directory.

Args: query: Name, email address, or keyword to search for.

Returns: JSON array of matching people with contact details (name, email, job_title, department, company, office, phones, address, manager, direct_reports, alias).

Check whether the current OWA session is authenticated.

Makes a lightweight GetFolder call on the inbox. Returns session status, the mailbox display name, and cookie file path.

Returns: JSON object with authenticated (bool), mailbox name, and details.

List mail folders from the Exchange mailbox.

Args: parent_folder_id: Parent folder to list children of. Defaults to "msgfolderroot" (top-level). Can be a distinguished folder name or a raw folder ID. recursive: If True, traverse all subfolders recursively (Deep). If False, only list immediate children (Shallow).

Returns: JSON array of folder objects with: name, id, total_count, unread_count, child_folder_count.

Create a new mail folder.

Args: name: Display name for the new folder. parent_folder_id: Parent folder to create under. Defaults to "msgfolderroot" (top-level). Can be a distinguished folder name or a raw folder ID.

Returns: JSON object with the created folder's id and name.

Rename an existing mail folder.

Args: folder_id: The Exchange folder ID to rename (from get_folders). new_name: New display name for the folder.

Returns: JSON object with success status and new folder id.

Empty all items from a mail folder.

Args: folder_id: The Exchange folder ID to empty (from get_folders). delete_sub_folders: If True, also delete sub-folders. Default False. permanent: If True, permanently delete items (HardDelete). Otherwise move to Deleted Items. Default False.

Returns: JSON object with success status.

Delete a mail folder.

Args: folder_id: The Exchange folder ID to delete (from get_folders). permanent: If True, permanently delete (HardDelete). Otherwise move to Deleted Items. Default False.

Returns: JSON object with success status.

Move a mail folder to a different parent folder.

Args: folder_id: The Exchange folder ID to move (from get_folders). target_parent_folder_id: Destination parent folder. Defaults to "msgfolderroot" (top-level). Can be a distinguished folder name or a raw folder ID.

Returns: JSON object with success status and new folder ID.

Find free time slots in your own calendar.

Analyzes your calendar events and returns available time slots within working hours for each weekday in the range.

Args: start_date: Start date in YYYY-MM-DD format. end_date: End date in YYYY-MM-DD format. Defaults to start_date if not provided (single-day search). duration_minutes: Minimum slot duration in minutes. Default 30. start_hour: Working day start hour (0-23). Default 9. end_hour: Working day end hour (0-23). Default 18.

Returns: JSON object with free_slots keyed by date, each containing an array of {start, end, duration_minutes} objects.

Find meeting times that work for multiple people.

Uses the OWA GetUserAvailability API to check cross-mailbox availability and find common free slots for all attendees. Supports multi-day ranges — searches each weekday in the range.

Args: emails: Comma-separated email addresses or names of attendees. start_date: Start date in YYYY-MM-DD format. end_date: End date in YYYY-MM-DD format. Defaults to start_date if not provided (single-day search). duration_minutes: Minimum slot duration in minutes. Default 30. start_hour: Working day start hour (0-23). Default 9. end_hour: Working day end hour (0-23). Default 18.

Returns: JSON object with attendee info and free_slots keyed by date, each containing an array of {start, end, duration_minutes}.

Get meeting count statistics for one or more people over a date range.

Uses GetUserAvailability to count calendar events (including expanded recurring instances) for each person.

Args: people: Comma-separated names or email addresses to analyze. start_date: Start date in YYYY-MM-DD format. end_date: End date in YYYY-MM-DD format.

Returns: JSON object with per-person stats sorted by meeting count: total_meetings, meetings_per_workday, days_with_meetings.

Build a connection matrix: who you meet with most often.

Analyzes your calendar over a date range, accounting for recurring meetings. For each contact found in your meetings, returns the weighted count of shared meetings.

Args: start_date: Start date in YYYY-MM-DD format. end_date: End date in YYYY-MM-DD format. top_n: Number of top contacts to return. Default 30.

Returns: JSON object with total_meetings, unique_contacts, and a ranked contacts array of {name, email, meetings} objects.

Authenticate to Exchange OWA (handles credential setup and 2FA login).

Call this tool when the session has expired or before first use. It performs browser-based SSO login with 2FA mobile push approval. Session cookies are encrypted at rest with the master password.

Two-call 2FA flow: The first call starts the browser login in the background and returns immediately asking you to tell the user to approve 2FA on their phone. Call login again with the same master_password after the user approves — the second call picks up the result.

Args: master_password: Decrypts stored credentials (and cookies), or encrypts new ones if username/password are also provided. username: Email address. Provide together with password for first-time credential setup (replaces login.py --setup). password: Account password. Required together with username for setup.

Returns: JSON result with success status and any error details.