Skip to main content
@frogbotai/piece-microsoft-outlook works with Microsoft 365 mail, calendars and contacts through Microsoft Graph. One linked Microsoft account covers mail and calendar, so a rep connects once.

Connect Outlook

Each person links their own Microsoft account through an OAuth connection:
Or read one company mailbox, such as sales@acme.com, with the app’s own secret and no signed-in person. See Read a company mailbox.
See factory options for the shared options.

Register the Entra app

  1. In the Microsoft Entra admin center, open App registrations → New registration. For sign-in from any organization, choose a multi-tenant account type, and include personal accounts if you need them.
  2. Add a Web redirect URI: the instance’s OAuth callback, https://your-app.example.com/api/connections/microsoft-outlook/callback (use your instance slug).
  3. Under Certificates & secrets, create a client secret. Use the application ID as clientId and the secret value as clientSecret.
  4. Under API permissions → Microsoft Graph → Delegated, add the scopes you request. Users consent when they link their account.

Clouds and tenants

createMicrosoftOutlook signs in at the commercial cloud and the common tenant. For US Government (GCC High), or to limit sign-in to one tenant, define your own factory:
The cloud picks the sign-in host (login.microsoftonline.com or .us) and the Graph origin (graph.microsoft.com or .us). Every request, including customApiCall and list cursors, must stay on that Graph origin. @frogbotai/piece-microsoft-teams uses the same settings.

Read a company mailbox

App-only access signs in with client credentials, as the app rather than a person. FrogBot reuses its token until 5 minutes before it expires.
  1. In the same Entra app, under API permissions → Microsoft Graph → Application, add Mail.ReadWrite, Mail.Send, Calendars.ReadWrite and Contacts.Read, then select Grant admin consent. Only an admin can grant these.
  2. Application permissions reach every mailbox in the tenant. Limit the app to the mailboxes it needs with an Exchange Online ApplicationAccessPolicy, for example:
  3. Set auth.tenantId to your directory tenant ID or domain; common, organizations and consumers are refused.

Actions

Upstream’s approval-by-email action isn’t included: ask a person with the question tool instead.

Page through mail, events and contacts

listMailFolders, listEmails, listEvents and listContacts return one page at a time, for imports:
Each takes limit (1–100, default 50) and cursor, the previous page’s pagination.nextCursor, which is null on the last page. listEmails lists newest first with full bodies, recipients and conversation ids, optionally receivedAfter a time. listEvents needs start and end and lists each occurrence of a recurring event. Graph errors keep Graph’s code, message and status. When Graph throttles a request, FrogBot waits for its Retry-After and retries up to 3 times.

Triggers

All three are polling triggers that check every 5 minutes. The first poll only records the current time, so mail already in the mailbox isn’t emitted and no files are saved. A poll has no signed-in person, so mount it on an instance with its own factory auth, such as a company mailbox; the instance in your connection entry throws missing without a signed-in person. Watching each rep’s own inbox isn’t supported yet.