outlook-email-and-calendar-manager

id	ailey-com-outlook
name	Outlook Email and Calendar Manager
description	Send, read, and manage Outlook/Office 365 emails with attachments and templates. Create and manage calendar events, search contacts, organize folders and rules. Uses Microsoft Graph API. Automatically provides setup instructions when connection fails.
keywords	["outlook","office365","email","calendar","contacts","microsoft-graph","send-email","read-email"]
tools	["microsoft-graph-api","azure-ad","typescript","cli"]

Outlook Email and Calendar Manager

Comprehensive Outlook and Office 365 integration for email management, calendar events, contacts, and folder organization via Microsoft Graph API.

Overview

This skill provides:

• Email Operations: Send, read, search, delete, move emails with attachments
• Email Templates: Handlebars templates for personalized bulk emails
• Calendar Management: Create, read, update, delete events with Teams meetings
• Contact Management: Search, create, and manage contacts
• Folder Organization: Create and manage mail folders
• Bulk Operations: Send multiple emails with CSV data
• Attachment Handling: Upload and download email attachments

When to Use

Use this skill when:

• Sending emails programmatically from Outlook/Office 365
• Reading and searching mailbox content
• Managing calendar events and meetings
• Automating email workflows
• Bulk email operations with templates
• Integrating Outlook with other tools
• Automatic setup help: Detects connection failures and provides setup instructions

Installation

cd .github/skills/ailey-com-outlook
npm install

Prerequisites:

• Node.js 18+
• Azure AD app registration
• Microsoft Graph API permissions

Quick Start

# Show setup instructions
npm run outlook setup

# Test connection
npm run outlook test

# Send email
npm run outlook send send -t [e-mail] -s "Test" -b "Hello"

# Read emails
npm run outlook read list --folder inbox --top 10

# Create calendar event
npm run outlook calendar create -s "Meeting" --start "2026-02-01 10:00" --end "2026-02-01 11:00"

# Search contacts
npm run outlook contacts search -q "John"

Workflow 1: Send Emails

Send emails with attachments and formatting.

Basic Email

# Simple email
npm run outlook send send \
  -t [e-mail] \
  -s "Project Update" \
  -b "The project is on track."

# HTML email
npm run outlook send send \
  -t [e-mail] \
  -s "Report" \
  -b "<h1>Q1 Results</h1><p>Revenue: $1M</p>" \
  --html

# With CC and BCC
npm run outlook send send \
  -t [e-mail] \
  --cc [e-mail] \
  --bcc [e-mail] \
  -s "Status Update" \
  -b "Project status attached."

# From file
npm run outlook send send \
  -t [e-mail] \
  -s "Documentation" \
  --file email-body.txt

With Attachments

# Single attachment
npm run outlook send send \
  -t [e-mail] \
  -s "Report" \
  -b "See attached report." \
  --attach report.pdf

# Multiple attachments
npm run outlook send send \
  -t [e-mail] \
  -s "Files" \
  -b "See attachments." \
  --attach "doc1.pdf,doc2.xlsx,presentation.pptx"

Template Emails

# Create template (welcome-email.hbs)
cat > templates/welcome.hbs << 'EOF'
<h1>Welcome {{name}}!</h1>
<p>Thank you for joining {{company}}.</p>
<p>Your account details:</p>
<ul>
  <li>Username: {{username}}</li>
  <li>Email: {{email}}</li>
</ul>
EOF

# Create data file
cat > data.json << 'EOF'
{
  "name": "John Doe",
  "company": "Acme Corp",
  "username": "jdoe",
  "email": "[e-mail]"
}
EOF

# Send template email
npm run outlook send template \
  -t [e-mail] \
  --template templates/welcome.hbs \
  --data data.json \
  -s "Welcome to {{company}}"

Bulk Emails

# Create CSV file
cat > recipients.csv << 'EOF'
email,name,subject,body
[e-mail],John,Hello John,Welcome to the team
[e-mail],Jane,Hello Jane,Welcome to the team
EOF

# Send bulk
npm run outlook send bulk \
  --csv recipients.csv \
  --delay 2000

# Bulk with template
npm run outlook send bulk \
  --csv recipients.csv \
  --template templates/welcome.hbs \
  --attach onboarding.pdf

TypeScript API

import { OutlookClient } from './scripts/outlook-client.js';

const client = new OutlookClient();

// Send email
await client.sendEmail({
  to: '[e-mail]',
  subject: 'Test',
  body: 'Hello!',
  attachments: ['file.pdf'],
  isHtml: false,
});

// Send to multiple recipients
await client.sendEmail({
  to: ['[e-mail]', '[e-mail]'],
  cc: ['[e-mail]'],
  subject: 'Team Update',
  body: '<h1>Update</h1>',
  isHtml: true,
});

Workflow 2: Read and Search Emails

Read mailbox content with filtering and search.

List Emails

# Inbox (default)
npm run outlook read list

# Specific folder
npm run outlook read list --folder sent
npm run outlook read list --folder drafts

# Filter by sender
npm run outlook read list --from [e-mail]

# Filter by subject
npm run outlook read list --subject "invoice"

# Unread only
npm run outlook read list --unread

# With attachments only
npm run outlook read list --attachments

# Limit results
npm run outlook read list --top 20

# JSON output
npm run outlook read list --format json -o emails.json

View Email Details

# Show email
npm run outlook read show -i MESSAGE_ID

# Download attachments
npm run outlook read show \
  -i MESSAGE_ID \
  --save-attachments ./downloads/

Manage Emails

# Mark as read
npm run outlook read mark -i MESSAGE_ID

# Mark as unread
npm run outlook read mark -i MESSAGE_ID --unread

# Delete email
npm run outlook read delete -i MESSAGE_ID --confirm

# Move to folder
npm run outlook read move -i MESSAGE_ID --to FOLDER_ID

TypeScript API

// Search emails
const emails = await client.readEmails({
  folder: 'inbox',
  from: '[e-mail]',
  subject: 'urgent',
  isRead: false,
  hasAttachments: true,
  top: 10,
});

// Get specific email
const email = await client.getEmail(messageId);

// Download attachment
await client.downloadAttachment(
  messageId,
  attachmentId,
  './downloads/file.pdf'
);

// Mark as read
await client.markAsRead(messageId, true);

// Delete email
await client.deleteEmail(messageId);

Workflow 3: Calendar Management

Create and manage calendar events with Teams meetings.

Create Events

# Basic event
npm run outlook calendar create \
  -s "Team Meeting" \
  --start "2026-02-01 10:00" \
  --end "2026-02-01 11:00"

# With location
npm run outlook calendar create \
  -s "Client Meeting" \
  --start "2026-02-01 14:00" \
  --end "2026-02-01 15:00" \
  -l "Conference Room A"

# With attendees
npm run outlook calendar create \
  -s "Project Review" \
  --start "2026-02-01 09:00" \
  --end "2026-02-01 10:00" \
  --attendees "[e-mail],[e-mail]"

# Teams online meeting
npm run outlook calendar create \
  -s "Virtual Standup" \
  --start "2026-02-01 09:00" \
  --end "2026-02-01 09:30" \
  --online

List Events

# Next 7 days (default)
npm run outlook calendar list

# Specific date range
npm run outlook calendar list \
  --start 2026-02-01 \
  --end 2026-02-28

# Custom days ahead
npm run outlook calendar list --days 14

Manage Events

# View details
npm run outlook calendar show -i EVENT_ID

# Update event
npm run outlook calendar update \
  -i EVENT_ID \
  -s "Updated Title" \
  -l "New Location"

# Delete event
npm run outlook calendar delete -i EVENT_ID --confirm

TypeScript API

// Create event
const event = await client.createEvent({
  subject: 'Team Meeting',
  start: new Date('2026-02-01T10:00:00'),
  end: new Date('2026-02-01T11:00:00'),
  location: 'Room A',
  attendees: ['[e-mail]'],
  isOnline: true,
});

// List events
const events = await client.listEvents(
  new Date('2026-02-01'),
  new Date('2026-02-28')
);

// Update event
await client.updateEvent(eventId, {
  subject: 'New Title',
  location: 'New Location',
});

// Delete event
await client.deleteEvent(eventId);

Workflow 4: Contact Management

Search and manage contacts.

Search Contacts

# Search by name or email
npm run outlook contacts search -q "John"

# JSON output
npm run outlook contacts search -q "example.com" --format json

Create Contacts

# Basic contact
npm run outlook contacts create \
  -n "John Doe" \
  -e [e-mail]

# Full details
npm run outlook contacts create \
  -n "Jane Smith" \
  -e [e-mail] \
  -p "[phone]" \
  -j "Senior Manager" \
  -c "Acme Corp"

Manage Contacts

# View details
npm run outlook contacts show -i CONTACT_ID

# Delete contact
npm run outlook contacts delete -i CONTACT_ID --confirm

TypeScript API

// Search
const contacts = await client.searchContacts('John');

// Create
const contact = await client.createContact({
  displayName: 'John Doe',
  emailAddress: '[e-mail]',
  phoneNumber: '[phone]',
  jobTitle: 'Developer',
  company: 'Acme',
});

// Delete
await client.deleteContact(contactId);

Workflow 5: Folder Management

Organize emails with folders.

List Folders

npm run outlook folders list

Create Folders

# Root folder
npm run outlook folders create -n "Projects"

# Subfolder
npm run outlook folders create \
  -n "2026 Projects" \
  --parent PARENT_FOLDER_ID

Delete Folders

npm run outlook folders delete -i FOLDER_ID --confirm

TypeScript API

// List folders
const folders = await client.listFolders();

// Create folder
const folder = await client.createFolder('Projects');

// Create subfolder
const subfolder = await client.createFolder(
  '2026',
  parentFolderId
);

// Delete folder
await client.deleteFolder(folderId);

Advanced Usage

Environment Configuration

Priority: .env.local > .env > ~/.vscode/.env

# ~/.vscode/.env (global)
AZURE_TENANT_ID=your-tenant-id
AZURE_CLIENT_ID=your-client-id
AZURE_CLIENT_SECRET=your-client-secret

Authentication Types

App-only (Service/Daemon):

# Requires client secret
AZURE_CLIENT_SECRET=your-secret

User delegation (Interactive):

# Omit client secret
# Uses device code flow

Error Handling

try {
  await client.sendEmail(options);
} catch (error) {
  if (error.message.includes('credentials')) {
    console.error('Setup required. Run: npm run outlook setup');
  } else if (error.message.includes('permissions')) {
    console.error('Missing API permissions');
  } else {
    console.error('Error:', error);
  }
}

Integration

With ailey-tools-tag-n-rag

Index email content:

# Save emails to file
npm run outlook read list --format json -o emails.json

# Index in RAG
npm run rag tag -i emails.json -t "email,work" -c "Email Archive"

CI/CD Email Notifications

- name: Send build notification
  run: |
    cd .github/skills/ailey-com-outlook
    npm run outlook send send \
      -t [e-mail] \
      -s "Build ${{ github.run_number }} complete" \
      -b "Status: ${{ job.status }}"

Troubleshooting

Connection Failures

Automatic Help:

npm run outlook test
# Shows setup instructions if connection fails

Manual Setup:

npm run outlook setup
# Displays step-by-step Azure AD configuration

Permission Errors

Required Microsoft Graph permissions:

• Mail.Read - Read emails
• Mail.ReadWrite - Manage emails
• Mail.Send - Send emails
• Calendars.ReadWrite - Manage calendar
• Contacts.ReadWrite - Manage contacts

Common Issues

Issue: credentials not found

Solution:

# Check environment variables
echo $AZURE_TENANT_ID
echo $AZURE_CLIENT_ID

# Add to ~/.vscode/.env
vim ~/.vscode/.env

Issue: Rate limit exceeded

Solution: Add delays between bulk operations:

npm run outlook send bulk --csv file.csv --delay 2000

Best Practices

1. API Limits: Respect Microsoft Graph rate limits (use delays for bulk)
2. Templates: Use Handlebars for personalized emails
3. Attachments: Keep under 4 MB per attachment
4. Security: Store credentials in environment files, not code
5. Error Handling: Always check connection before bulk operations

References

• Microsoft Graph API - Complete API reference
• Email Templates - Template examples
• Permissions Guide - Required permissions

---

version: 1.0.0 updated: 2026-01-31 reviewed: 2026-01-31 score: 4.6