Skip to content
DutiesBook API
Open app

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.

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.

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.

POST /api/channels/ms365/auth

Generates the Microsoft OAuth authorization URL and redirects the browser to the Microsoft consent screen.

GET /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.

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.

{
"uuid": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"name": "Support Inbox",
"type": "microsoft365",
"status": "connected",
"email": "[email protected]",
"displayName": "Support Inbox",
"microsoftAccountType": "work",
"createdAt": "2024-01-01T00:00:00.000Z",
"updatedAt": "2024-01-01T00:00:00.000Z"
}

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.

BIZ_001 422
CHANNEL_NOT_CONNECTED

The Microsoft 365 channel exists but is not currently connected. Reconnect it from the Channels settings page.

RES_001 404
CHANNEL_NOT_FOUND

The specified channel was not found or you don't have access to it.