Home / Docs / Microsoft 365

Microsoft 365

Microsoft 365 Email Setup

Connect OpenCaddis to your Microsoft 365 account to read, search, and send email through agents. This uses the device code OAuth flow — no client secrets needed.

Step 1: Azure App Registration

  1. Go to the Azure Portal → Microsoft Entra ID → App registrations → New registration
  2. Name: OpenCaddis (or any name you prefer)
  3. Supported account types: Select "Accounts in any organizational directory and personal Microsoft accounts"
  4. Redirect URI: Leave blank (device code flow does not require one)
  5. Click Register
  6. After creation, copy the Application (client) ID from the Overview page

Add API Permissions

Go to API permissions → Add a permission → Microsoft Graph → Delegated permissions. Add:

Permission Type Purpose
Mail.ReadDelegatedRead emails
Mail.ReadWriteDelegatedSend emails and manage drafts
User.ReadDelegatedRead user profile (display name, email)
offline_accessDelegatedMaintain access via refresh tokens

Step 2: Configuration

Add your Application (client) ID to opencaddis.json:

opencaddis.json 
{
  "Microsoft365": {
    "ClientId": "YOUR-APPLICATION-CLIENT-ID-HERE"
  }
}

Then add the Microsoft365Email plugin to any agent:

opencaddis.json — Agent with Email 
{
  "Handle": "Email Assistant",
  "AgentType": "assistant",
  "Models": ["default"],
  "SystemPrompt": "You help manage email. Summarize messages and draft replies.",
  "Plugins": ["Microsoft365Email", "Memory"]
}

Step 3: Authentication

OpenCaddis uses the device code flow — a browser-based sign-in that doesn't require client secrets.

  1. Open OpenCaddis and switch to an agent with the Microsoft365Email plugin
  2. The agent will display a device code and a verification URL
  3. Visit the URL in your browser, enter the code, and sign in with your Microsoft account
  4. Once authenticated, tokens are stored encrypted locally
  5. Tokens auto-refresh 5 minutes before expiry — no need to re-authenticate
First-Time Setup

You only need to complete the device code flow once. After that, OpenCaddis will automatically refresh your access token using the stored refresh token.

Security

  • Tokens encrypted at rest — stored using ASP.NET Data Protection in the .keys directory
  • No client secrets — device code flow means no secrets in configuration files
  • Delegated permissions only — the app acts as the signed-in user, never with app-level access
  • Local storage only — tokens never leave your machine
Documentation