The tables below show which OAuth scopes the account owner must grant to call each Methods API endpoint or receive each realtime event. Find the methods and events your application uses, then combine their required scopes into one list.

There are two stages to requesting these permissions. First, declare the scopes when you register your OAuth application with Google or Microsoft. This defines the permissions your application is allowed to ask account owners for. Add those scopes to the Provider OAuth settings in Unipile. Then, when an owner connects their account, Unipile requests the scopes from that owner for consent. You can request the configured scopes or a smaller set for an individual account using Create Auth Link or Start Auth Intent. Only scopes granted for that account enable the corresponding methods and events.

The basic identity scopes are always requested: openid and email for Google, and User.Read for Microsoft. They let Unipile identify the account and obtain its email address. You can connect an account with only these basic scopes, but no email or calendar methods or realtime events will work.

The Email and Calendar products shown for the account in the Dashboard are determined automatically from the scopes granted at connection. A product can appear even if some of its methods or events are unavailable: each one still needs the scopes listed below. Google accepts a partial set of the scopes requested; Microsoft currently rejects the connection if fewer scopes are granted than requested. To change an existing account's permissions, reconnect it.

Google scopes in the tables omit the https://www.googleapis.com/auth/ prefix; use the full URL in your OAuth configuration. Microsoft names are delegated Microsoft Graph permissions. or means any one of the listed scopes is sufficient; and means both are required.

Emails API

¹ If reply_to_message_id is supplied, Unipile reads the original Gmail message. Add gmail.metadata, gmail.readonly, or gmail.modify to the sending/draft scope. Retaining existing attachments while updating a draft requires gmail.readonly or gmail.modify. Without an explicit from, Unipile uses the connected account's email if it cannot read the Gmail profile.

² Unipile creates or reads a draft before sending through Microsoft Graph; Mail.Send alone is insufficient. For Outlook Modify an Email or Update a Draft, requests that use categories also read the category list (MailboxSettings.Read or MailboxSettings.ReadWrite), and creating a new category requires MailboxSettings.ReadWrite.

---

Calendar API

³ Creating a Google calendar with background_color makes a second calendarList.update call. The calendar scope covers both calls; without a color, calendar.calendars is sufficient.

Realtime events

These are the event types emitted by the Google and Outlook realtime services. Select their scopes if your application needs the corresponding webhooks. The scopes below follow Unipile's current realtime checks, which can be stricter than the provider API: a read-only Google Calendar scope, for example, can list events through the Methods API but does not enable calendar event polling.

⁴ Google realtime first calls calendarList.list to discover calendars, then events.list to poll them. calendar.events alone passes the event permission check but cannot complete discovery. The broad calendar scope covers discovery, but the current realtime check still requires calendar.events explicitly for event notifications.

For scope definitions and provider restrictions, see Google Gmail scopes, Google Calendar scopes, Google People connections, and Microsoft Graph permissions.