outlook-mail

What this skill does

# Outlook Mail

Manage Microsoft Outlook email using PowerShell COM objects.

## Prerequisites

- Microsoft Outlook installed and running
- PowerShell 5.1+ (included in Windows 10/11)

## Safety Rules

1. **Never auto-send** - Always create drafts first for user review
2. `outlook-send.ps1` requires `-Confirm` flag to actually send
3. `outlook-send-as.ps1`, `outlook-reply.ps1`, `outlook-forward.ps1`, `outlook-voting.ps1`, `outlook-request-receipt.ps1` also require `-Confirm`
4. Confirm with user before any send operation
5. `outlook-delete.ps1` requires `-Confirm` to delete; `-Permanent` attempts identity-verified purge and safe-fails when identity cannot be verified
6. `outlook-recall.ps1 -DeleteUnread` only removes from your Sent Items and requires `-ConfirmDeleteFromSent`

## Email Targeting

**Always use EntryID as the primary method to target emails.** Index is a fallback only.

- **Listing scripts** (`outlook-find.ps1`, `outlook-read.ps1`, `outlook-search.ps1`, `outlook-search-advanced.ps1`) output an `EntryID` for each email
- **Action scripts** accept `-EntryID` as the preferred parameter (alternative to `-Index`)
- EntryID is stable for exact targeting in the current mailbox context, but can change if an item is moved/copied across stores
- Index numbers are volatile — they can shift between commands if new emails arrive

**Workflow:**
1. Run `outlook-find.ps1`, `outlook-read.ps1`, `outlook-search.ps1`, or `outlook-search-advanced.ps1` to get EntryIDs
2. Use `-EntryID` on any action script to target the exact email

```powershell
# Step 1: Find emails matching criteria, get stable EntryIDs
& "./scripts/outlook-find.ps1" -Days 1 -UnreadOnly

# Step 2: Act on email using stable EntryID
& "./scripts/outlook-reply.ps1" -EntryID "00000000..." -Body "Got it, thanks!"
```

## Link Stripping

Scripts that output email body content support a `-StripLinks` parameter (type: `bool`, default: `$true`). When enabled, all URLs in the output are replaced with `[URL]` to reduce context window bloat from long tracking URLs, Safe Links wrappers, and marketing links.

- **Default ON**: No action needed — URLs are stripped automatically
- **To preserve URLs**: Pass `-StripLinks $false`

**Scripts with `-StripLinks` support:**
`outlook-read-body.ps1`, `outlook-find.ps1`, `outlook-draft.ps1`, `outlook-forward.ps1`, `outlook-reply.ps1`, `outlook-out-of-office.ps1`, `outlook-request-receipt.ps1`, `outlook-rules-create.ps1`, `outlook-rules-list.ps1`, `outlook-schedule-send.ps1`, `outlook-send-as.ps1`, `outlook-send.ps1`, `outlook-voting.ps1`

## Scripts Overview

**Find and Target**
- `outlook-find.ps1` - Find emails by criteria, return stable EntryIDs for action scripts

**Read and Search**
- `outlook-read.ps1` - List recent inbox emails
- `outlook-read-body.ps1` - Read full email body by EntryID or index
- `outlook-search.ps1` - Search by subject, sender, or body
- `outlook-search-advanced.ps1` - Multi-filter advanced search

**Compose and Send**
- `outlook-draft.ps1` - Create draft email
- `outlook-draft-update.ps1` - Modify existing draft
- `outlook-send.ps1` - Send email directly (requires -Confirm)
- `outlook-send-as.ps1` - Send from specific account (requires -Confirm)
- `outlook-reply.ps1` - Reply to email (requires -Confirm to send)
- `outlook-forward.ps1` - Forward email (requires -Confirm to send)
- `outlook-voting.ps1` - Send email with voting buttons (requires -Confirm)

**Organize**
- `outlook-move.ps1` - Move email to folder
- `outlook-delete.ps1` - Delete email (requires -Confirm)
- `outlook-mark-read.ps1` - Mark email read or unread
- `outlook-conversation.ps1` - View email conversation thread
- `outlook-print.ps1` - Print email

**Flags, Importance and Sensitivity**
- `outlook-flag.ps1` - Flag email for follow-up
- `outlook-unflag.ps1` - Remove or complete flag
- `outlook-set-importance.ps1` - Set email priority level
- `outlook-set-sensitivity.ps1` - Set email sensitivity level
- `outlook-save-as.ps1` - Export email to file

**Categories**
- `outlook-list-categories.ps1` - List all categories
- `outlook-create-category.ps1` - Create new category
- `outlook-assign-category.ps1` - Assign category to email
- `outlook-remove-category.ps1` - Remove category from email
- `outlook-delete-category.ps1` - Delete category from master list

**Scheduling and Receipts**
- `outlook-schedule-send.ps1` - Schedule delayed send
- `outlook-request-receipt.ps1` - Send with read/delivery receipts
- `outlook-recall.ps1` - Recall guidance and optional Sent Items deletion

**Account and Rule Management**
- `outlook-folders.ps1` - List all mail folders
- `outlook-accounts-list.ps1` - List configured email accounts
- `outlook-rules-list.ps1` - List email rules
- `outlook-rules-create.ps1` - Create new email rule
- `outlook-out-of-office.ps1` - Configure auto-replies
- `outlook-attachment-save.ps1` - Save email attachments

## Find and Target

Search and filter emails to retrieve stable EntryIDs for use with action scripts.

### outlook-find.ps1
Find emails matching search criteria and return their EntryIDs. This is the primary way to get stable email identifiers before performing actions (reply, forward, delete, etc.).

**Required Parameters:** None

**Optional Parameters:**

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `-Days` | int | 7 | How many days back to search |
| `-DateFrom` | datetime | — | Start date (overrides -Days when used with -DateTo) |
| `-DateTo` | datetime | — | End date (inclusive, end-of-day) |
| `-From` | string | — | Sender name or email address contains |
| `-To` | string | — | Recipient name or email contains |
| `-Subject` | string | — | Subject line contains |
| `-BodyContains` | string | — | Body text contains (plain text search) |
| `-UnreadOnly` | switch | off | Only unread emails |
| `-ReadOnly` | switch | off | Only read emails |
| `-HasAttachment` | switch | off | Only emails with attachments |
| `-Flagged` | switch | off | Only flagged/follow-up emails |
| `-Importance` | string | — | Filter by importance: High, Normal, Low |
| `-Category` | string | — | Only emails assigned this category |
| `-Folder` | string | Inbox | Folder to search (e.g., "Sent Items", "Archive") |
| `-Limit` | int | 50 | Max results to return |
| `-StripLinks` | bool | `$true` | Replace URLs in body snippets with `[URL]` |

**Output per result:** EntryID, Subject, From (name + email), Date, Read/Unread status, Body snippet (~150 chars), Attachments (count + filenames), Importance (if non-normal), Flag status, Categories.

**Examples:**

```powershell
# Find all unread emails from today
& "./scripts/outlook-find.ps1" -Days 1 -UnreadOnly

# Find emails about "lunch" from today
& "./scripts/outlook-find.ps1" -Days 1 -Subject "lunch"

# Find emails with "invoice" in the body
& "./scripts/outlook-find.ps1" -Days 30 -BodyContains "invoice"

# Find flagged high-importance emails
& "./scripts/outlook-find.ps1" -Days 7 -Flagged -Importance High

# Find emails from a specific sender with attachments
& "./scripts/outlook-find.ps1" -From "[email protected]" -HasAttachment

# Find read emails in a specific category
& "./scripts/outlook-find.ps1" -ReadOnly -Category "Project Alpha"

# Find emails sent to a specific person
& "./scripts/outlook-find.ps1" -To "[email protected]" -Days 14

# Search in Sent Items folder
& "./scripts/outlook-find.ps1" -Folder "Sent Items" -Days 3 -Subject "report"

# Then act on a found email using its EntryID
& "./scripts/outlook-reply.ps1" -EntryID "00000000..." -Body "Got it, thanks!"
```

---

## Read and Search

Read recent emails, view full message bodies, and search with simple or advanced filters.

### outlook-read.ps1
List recent emails from the Inbox with sender name, email address, date, unread status, and EntryID. Results include a stable EntryID for use with action scripts (e.g., `outlook-read-body.ps1 -EntryID "..."`). Also numbered with an index as a fallback.

**Required Parameters:** None