Microsoft 365 Integration

Access Microsoft 365 data through the Microsoft Graph API. This Skill provides capabilities to read emails, search messages, and retrieve user profile information.

Prerequisites

Before using this Skill, you must:

1. Install Node.js dependencies:

cd scripts && npm install && npm run build

2. Set up Azure AD application and configure environment variables (see SETUP.md for detailed instructions)

Required Environment Variables

Set these environment variables before using the Skill:

export MS365_TENANT_ID="your-tenant-id"
export MS365_CLIENT_ID="your-client-id"
export MS365_CLIENT_SECRET="your-client-secret"
export MS365_TARGET_USER="user@example.com"

Instructions

Getting User Profile Information

To retrieve user profile information:

node scripts/dist/user-info.js

This returns a JSON object with:

• Display name
• Email address
• User principal name
• Proxy addresses
• Job title
• Department
• Office location
• Phone numbers

Reading Emails

To retrieve recent emails:

node scripts/dist/email.js --top 20

Available options:

• --top <number>: Number of messages to retrieve (default: 20, max: 999)
• --search <query>: Search query using KQL syntax
• --filter <odata>: OData filter expression
• --folder <name>: Specific mail folder (e.g., “Inbox”, “Sent Items”, “Drafts”)

Examples:

Get 50 most recent emails:

node scripts/dist/email.js --top 50

Search for emails about “budget”:

node scripts/dist/email.js --search "subject:budget"

Get unread emails:

node scripts/dist/email.js --filter "isRead eq false" --top 10

Get emails from specific folder:

node scripts/dist/email.js --folder "Inbox" --top 30

Search for emails from specific sender:

node scripts/dist/email.js --search "from:john@example.com"

Email Data Structure

Each email message includes:

• id: Message ID
• subject: Email subject line
• from: Sender information (name and email address)
• receivedDateTime: When the email was received (ISO 8601 format)
• bodyPreview: Preview text of the email body
• body: Full email body (HTML or plain text)
• hasAttachments: Boolean indicating if email has attachments
• isRead: Boolean indicating if email has been read
• importance: Message importance (normal, low, high)

Search Query Syntax

When using --search, you can use Keyword Query Language (KQL):

• subject:keyword – Search in subject
• from:email@example.com – Search by sender
• to:email@example.com – Search by recipient
• body:keyword – Search in email body
• hasattachments:true – Only emails with attachments
• received:today – Emails received today
• received>=2024-01-01 – Emails received on or after date

Combine multiple criteria:

node scripts/dist/email.js --search "from:manager@example.com subject:report received:thisweek"

OData Filter Syntax

When using --filter, you can use OData expressions:

• isRead eq false – Unread messages
• hasAttachments eq true – Messages with attachments
• importance eq 'high' – High importance messages
• receivedDateTime ge 2024-01-01T00:00:00Z – Messages received after date

Combine filters with and/or:

node scripts/dist/email.js --filter "isRead eq false and hasAttachments eq true"

Best Practices

1. Limit results: Use --top to limit the number of messages retrieved to improve performance
2. Use specific searches: Narrow down results with search queries or filters to find relevant emails faster
3. Check environment variables: Ensure all required environment variables are set before running commands
4. Handle large mailboxes: For mailboxes with thousands of emails, use filters or search to avoid timeouts

Troubleshooting

“Missing required environment variables” error:

• Verify all four MS365_* environment variables are set
• Check for typos in variable names
• Ensure variables are exported in your current shell session

“Error fetching emails” or authentication errors:

• Verify Azure AD application has correct API permissions
• Ensure client secret is valid and not expired
• Check that the target user exists in your tenant
• See SETUP.md for permission requirements

Empty results:

• Verify the target user has emails in their mailbox
• Check folder name spelling if using --folder
• Try without filters/search to ensure basic connectivity works

Security Notes

• Client secrets should be treated as passwords – never commit them to version control
• Consider using Azure Key Vault or similar secure storage for credentials in production
• The service account needs appropriate permissions – follow principle of least privilege
• Regularly rotate client secrets according to your organization’s security policy

Additional Resources

For detailed setup instructions including Azure AD configuration, see SETUP.md.