Microsoft 365

One Microsoft connection gives Pozy a person's Outlook mail, Outlook Calendar, OneDrive and Outlook contacts. It works for Microsoft 365 work or school logins and for personal Outlook.com or Hotmail logins alike. Each account stands for one mailbox, and you pick the areas it covers when you connect. The calls are shared with Google mailboxes: see Email, Calendar and Files.

#What you can do

Each connection adds openid, profile, email, offline_access and User.Read as well: they identify the mailbox and let Pozy keep access over time.

#Connect an account

curl "https://api.pozy.ai/v1/connect/microsoft?profileId=6710c3a9e4b0d2f1a8c95e21&scopes=email,calendar&redirect_url=https://app.example.com/connected" \
  -H "Authorization: Bearer $POZY_API_KEY"

const res = await fetch("https://api.pozy.ai/v1/connect/microsoft?profileId=6710c3a9e4b0d2f1a8c95e21&scopes=email,calendar&redirect_url=https:%2F%2Fapp.example.com%2Fconnected", {
  headers: { Authorization: `Bearer ${process.env.POZY_API_KEY}` },
});
const data = await res.json();
if (!res.ok) throw new Error(data.error);

import os, requests

resp = requests.get(
    "https://api.pozy.ai/v1/connect/microsoft",
    headers={"Authorization": f"Bearer {os.environ['POZY_API_KEY']}"},
    params={
        "profileId": "6710c3a9e4b0d2f1a8c95e21",
        "scopes": "email,calendar",
        "redirect_url": "https://app.example.com/connected",
    },
)

The user signs in, approves the permissions behind the areas, and returns to your redirect_url with connected=microsoft, profileId, accountId and username. Pozy reads the granted areas from the token Microsoft returns.

To add areas later, connect the same account again with the longer list and reconnectAccountId. The account id stays the same. loginHint preselects the mailbox in Microsoft's account picker. Areas only add up; to drop one, disconnect and connect again.

#Admin consent

Many work and school tenants let only an administrator approve apps that read mail, calendars, files or contacts. Users then see "Need admin approval" while connecting, or later calls return 412 admin_consent_required with a ready-made link in details.adminConsentUrl (valid for one hour). Personal Outlook.com accounts never need this.

Request a fresh link for an account in that organization and send it to an administrator (Global Administrator, Cloud Application Administrator or Application Administrator):

curl "https://api.pozy.ai/v1/connect/microsoft/admin-consent?accountId=6710c50ce4b0d2f1a8c95e82&redirectUrl=https://app.example.com/admin-done" \
  -H "Authorization: Bearer $POZY_API_KEY"

const res = await fetch("https://api.pozy.ai/v1/connect/microsoft/admin-consent?accountId=6710c50ce4b0d2f1a8c95e82&redirectUrl=https:%2F%2Fapp.example.com%2Fadmin-done", {
  headers: { Authorization: `Bearer ${process.env.POZY_API_KEY}` },
});
const data = await res.json();
if (!res.ok) throw new Error(data.error);
console.log(data.data.adminConsentUrl);

resp = requests.get(
    "https://api.pozy.ai/v1/connect/microsoft/admin-consent",
    headers={"Authorization": f"Bearer {os.environ['POZY_API_KEY']}"},
    params={"accountId": "6710c50ce4b0d2f1a8c95e82", "redirectUrl": "https://app.example.com/admin-done"},
)
print(resp.json()["data"]["adminConsentUrl"])

The administrator signs in, reviews the permissions and approves them for the whole tenant. Microsoft sends them to redirectUrl with adminConsent=granted and tenant, or adminConsent=denied and error. Calls that returned 412 then work without a reconnect. An administrator can also approve while connecting their own mailbox by ticking "Consent on behalf of your organization".

Approval is per organization and covers all four areas. Each user still chooses what their own connection grants. An administrator can withdraw it in Microsoft Entra under Enterprise applications, after which accounts in that tenant fail until it is approved again.

#Outlook limits

Each send response includes the X-Pozy-Send-Limit, X-Pozy-Send-Remaining and X-Pozy-Send-Reset headers. For repeating events Outlook takes a single RRULE, with no EXDATE or RDATE, and it stores just one reminder per event. Upload conversion with convertTo and picker sessions belong to Google; on Microsoft they answer 400.

#Push notifications

Pozy creates Microsoft Graph subscriptions for the granted areas and renews them before they expire (about three days for mail and calendar, about 29 days for OneDrive). Subscribe your own webhook to the events you need:

If the push subscription is down, mail received in that time produces no webhooks; catch up with GET /v1/email/messages. The subscription's state is the push field of GET /v1/accounts/{accountId}/health.

#Errors

#Endpoints