Connect an account
Connecting a Microsoft 365 account is a one-time OAuth flow done through the DutiesBook dashboard. Once connected, the account is available as a channel in the external API.
Connection steps
Section titled “Connection steps”Open channels settings
In the DutiesBook dashboard, navigate to Settings → Channels and click Add Channel.
Select Microsoft 365
Choose Microsoft 365 / Outlook from the channel type list.
Sign in with Microsoft
You are redirected to the Microsoft sign-in page. Enter your Microsoft 365 credentials and grant the requested mail permissions.
Channel created
DutiesBook exchanges the authorization code for access and refresh tokens, creates the channel, and begins listening for new emails via a Microsoft Graph webhook subscription.
Automatic webhook setup
DutiesBook automatically creates a Microsoft Graph change notification subscription for your inbox. The subscription is renewed automatically before it expires — no manual action required.
OAuth endpoints
Section titled “OAuth endpoints”These endpoints are called internally by the DutiesBook dashboard during the connection flow. They are not part of the external API and do not require external API credentials.
Initiate OAuth
Section titled “Initiate OAuth”/api/channels/ms365/auth Generates the Microsoft OAuth authorization URL and redirects the browser to the Microsoft consent screen.
OAuth callback
Section titled “OAuth callback”/api/channels/ms365/callback Microsoft redirects to this URL after the user grants consent. DutiesBook exchanges the authorization code for tokens, fetches the account profile from Microsoft Graph, and creates the channel record.
After connecting
Section titled “After connecting”The connected account appears immediately in your channel list as a microsoft365 channel. Use the GET /channels endpoint to retrieve the channel UUID needed for sending messages.
Example channel object
Section titled “Example channel object”{ "uuid": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "name": "Support Inbox", "type": "microsoft365", "status": "connected", "displayName": "Support Inbox", "microsoftAccountType": "work", "createdAt": "2024-01-01T00:00:00.000Z", "updatedAt": "2024-01-01T00:00:00.000Z"}Disconnecting an account
Section titled “Disconnecting an account”To disconnect, go to Settings → Channels in the DutiesBook dashboard, open the channel, and click Disconnect. This revokes the Microsoft Graph webhook subscription and removes the stored tokens.
Active conversations
Disconnecting a channel does not delete its conversation history. Existing conversations remain in DutiesBook but new emails will no longer be received.
Errors
Section titled “Errors”BIZ_001 422 The Microsoft 365 channel exists but is not currently connected. Reconnect it from the Channels settings page.
RES_001 404 The specified channel was not found or you don't have access to it.