Skip to content

Docs/Connectors

Outlook

Email in one Microsoft 365 or Outlook mailbox as message records and conversation episodes. Attachment contents are never read.

The outlook connector reads one Microsoft 365 mailbox through Microsoft Graph: who wrote to whom, when, the subject and the body text, and how each conversation went. The mailbox owner authorizes it themself.

Connector name outlook
Products Records, episodes
Credentials An app in Microsoft Entra ID and a refresh token from the mailbox owner
Permissions Delegated Mail.Read and offline_access
Status Preview: tested against Microsoft's documented responses, not yet on a live account

What it reads

Object Contents
email_message Conversation and message ids, sent time, sender, to and cc addresses, subject, body as plain text, folder (inbox, sentitems, archive or other), attachment count and file types, reply and forward flags, position in the conversation
email_participant One row per sender and recipient of each message: role, name and address

The body is the part of each message that is new, without the quoted history. Bodies longer than maxBodyLength characters are cut.

Episodes. One per conversation: each message in order, as sent, replied or forwarded, by its sender.

Each participant's name and address is learned by the scrubber, so a name in a body or a signature is replaced too, and the run stops before upload if one survives.

What it never reads

  • Attachment contents. Only the count and file types are sent; file names are not.
  • Drafts, and messages in an excluded folder. By default: Junk Email, Deleted Items and Drafts, found in any mailbox language.
  • Names of folders you created. They are sent as other.

Setup

  1. In Microsoft Entra ID, register an app with the delegated Mail.Read and offline_access permissions and create a client secret.
  2. Have the mailbox owner sign in once with those permissions and keep the refresh token.
  3. Connect:
bash
datayield connect outlook -o clientId=<client id> -o clientSecret=env:MS_CLIENT_SECRET -o refreshToken=env:OUTLOOK_REFRESH_TOKEN

Add one source per mailbox. Microsoft replaces the refresh token from time to time; the SDK saves the new one in ~/.datayield/credentials.

Options

Option Required Meaning
clientId, clientSecret, refreshToken yes, or accessToken The app and the owner's refresh token. Stored as secrets.
tenantId no Directory (tenant) id. Default common.
accessToken instead of the above A current access token, for a one-off run
excludeFolders no Folder names never read. Replaces the default list.
includeFolders no Read only these folders
excludeDomains no Skip a message when anyone on it has an address at one of these domains
excludePersonalDomains no Also skip messages with anyone at gmail.com, outlook.com and similar. Default false.
maxBodyLength no Longest body sent, in characters. Default 20000.

New records on each run

Each run asks Graph for messages received since the last successful run. When Graph asks the SDK to slow down, it waits as long as Graph says.