Security & Data Handling

Understanding the security model and data handling practices for outlookctl.

Overview

outlookctl operates entirely locally using Outlook's COM automation interface. There are no network calls to external services, no cloud storage, and no OAuth/API tokens required.

🔒

Local Only

All operations happen on your workstation through Windows COM.

🔑

No API Keys

Uses your existing Outlook session - no tokens or credentials to manage.

🛠

Your Context

Runs with your Windows user permissions and Outlook settings.

📋

Audit Trail

All send operations are logged locally for accountability.

🛡 No Network Access Required

  • Does NOT require Microsoft Graph API
  • Does NOT require Azure app registration
  • Does NOT require OAuth tokens
  • Does NOT make any network calls to external services

Data Minimization

Default Behavior

By default, commands return metadata only:

  • Subject line
  • Sender/recipient email addresses
  • Timestamps
  • Attachment filenames (not content)
  • Read/unread status
👁

Body Content is Opt-In

Message body content is never retrieved unless explicitly requested using --include-body or --include-body-snippet flags.

Opt-In Body Access

To retrieve message body content, you must explicitly request it:

bash
# Get full body uv run python -m outlookctl.cli get \ --id "..." --store "..." \ --include-body # Get truncated snippet uv run python -m outlookctl.cli list \ --include-body-snippet \ --body-snippet-chars 200

Redaction Options

For sensitive environments, consider:

  • Using --max-body-chars to limit body size
  • Processing only metadata (default behavior)
  • Implementing additional filtering in your workflow

Send Safety Gates

Two-Step Workflow

The recommended workflow for sending email:

1

Create a draft

Use outlookctl draft to create the message

2

Review

Show the user the subject, recipients, and body preview

3

Explicit send

Use outlookctl send --draft-id ... --confirm-send YES

Required Confirmation

The send command will refuse to execute unless one of these conditions is met:

bash
# This will FAIL uv run python -m outlookctl.cli send \ --draft-id "..." --draft-store "..." # This will SUCCEED uv run python -m outlookctl.cli send \ --draft-id "..." --draft-store "..." \ --confirm-send YES

Unsafe Direct Send

Sending a new message without first creating a draft requires additional confirmation:

bash
# Requires BOTH flags - intentionally cumbersome uv run python -m outlookctl.cli send \ --to "recipient@example.com" \ --subject "Subject" \ --body-text "Body" \ --unsafe-send-new \ --confirm-send YES

This is intentionally cumbersome to discourage bypassing the draft workflow.

Audit Logging

Location

Audit logs are stored at:

  • Windows: %LOCALAPPDATA%\outlookctl\audit.log
  • Fallback: ~/.outlookctl/audit.log

What's Logged

For send operations, the audit log records:

json
{ "timestamp": "2025-01-15T10:00:00+00:00", "operation": "send", "success": true, "recipients": { "to_count": 1, "cc_count": 0, "bcc_count": 0 }, "subject_length": 25, "entry_id": "00000..." }
📋

Privacy by Default

By default, the log contains counts and lengths only, not actual content. Use --log-body to include body content (not recommended for sensitive data).

Outlook Security Prompts

Programmatic Access Warning

Outlook may display a security prompt when accessing certain properties programmatically:

"A program is trying to access email addresses stored in Outlook..."

This is a Windows/Outlook security feature. Options:

  1. Click "Allow" when prompted
  2. Configure Outlook Trust Center settings
  3. Use Group Policy (enterprise environments)

COM Security

The tool uses standard COM automation (Outlook.Application). This:

  • Runs in the user's security context
  • Respects Outlook's security settings
  • May be blocked by some antivirus software

Best Practices

For Claude/AI Usage

  • 1
    Always use draft-first workflow - Create drafts, show preview, send after confirmation
  • 2
    Minimize data retrieval - Only fetch body when explicitly needed
  • 3
    Don't store credentials - No passwords or tokens are needed
  • 4
    Respect user intent - Never auto-send without explicit user instruction

For Sensitive Environments

  • 1
    Review audit logs periodically
  • 2
    Use --max-body-chars to limit data exposure
  • 3
    Consider disabling --log-body entirely
  • 4
    Monitor for unexpected send operations

Limitations

  • Only works with Classic Outlook (not New Outlook)
  • Requires Outlook to be running and logged in
  • Subject to corporate Outlook policies
  • COM automation may trigger security prompts