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

Limit results: Use --top to limit the number of messages retrieved to improve performance
Use specific searches: Narrow down results with search queries or filters to find relevant emails faster
Check environment variables: Ensure all required environment variables are set before running commands
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.

ms365

Microsoft 365 Integration

Prerequisites

Required Environment Variables