TOutlookMail Guide: Migrating from Legacy OLE to Microsoft 365 Graph API

Your Questions Answered

What is client_id?

No, it is NOT the user's email address. The client_id is a unique Application (client) ID — a GUID like a1b2c3d4-e5f6-7890-abcd-ef1234567890 — that you get when you register your application in Azure Active Directory (Microsoft Entra ID).

Think of it as your application's license plate number with Microsoft. Every app that wants to talk to Microsoft 365 must be registered, and Microsoft gives it this unique ID.

What is client_secret?

No, it is NOT the user's network password. The client_secret is a secret key that Microsoft generates for your registered application — a random string like ABC~defGHI.jklMNO_pqrSTU123. It acts as your application's password to prove to Microsoft that API requests are really coming from your app.

[!CAUTION]
The client_secret should be treated like a master password. Never hard-code it in source files that could be shared. Store it securely (e.g., encrypted in a config file or database).

What is redirect_uri?

This is the callback URL where Microsoft sends the authorization code after the user logs in. The TOutlookMail class spins up a tiny local HTTP server (via THttpServer in [oauth.prg](file:///c:/fwteam/source/classes/oauth.prg)) to listen on this URL and capture the code automatically. http://localhost:5500/ is the default.

How to Get Your client_id and client_secret

Your agency's IT administrator (or someone with access to the organization's Azure/Microsoft 365 admin portal) needs to do this once:

1. Go to Azure Portal → App Registrations
2. Click "New registration"
3. Fill in:
   • Name: e.g., "SC Leave Request App"
   • Supported account types: "Accounts in this organizational directory only"
   • Redirect URI: Select Web, enter http://localhost:5500/

[!IMPORTANT]
You must also grant API Permissions for Mail.Send under Microsoft Graph (Delegated permissions). An admin must click "Grant admin consent" for the organization.

How the Authentication Flow Works

</s>
sequenceDiagram
    participant App as Your Leave App
    participant Browser as WebView2 Browser
    participant MS as Microsoft Login
    participant LocalHTTP as Local HTTP Server (5500)

<i>    </i>App-&gt;&gt;LocalHTTP: Start listening on port 5500
<i>    </i>App-&gt;&gt;Browser: Open Microsoft login page
<i>    </i>Browser-&gt;&gt;MS: User logs in &amp; grants permission
<i>    </i>MS-&gt;&gt;LocalHTTP: Redirect with authorization code
<i>    </i>LocalHTTP-&gt;&gt;App: Return authorization code
<i>    </i>App-&gt;&gt;MS: Exchange code for access_token + refresh_token
<i>    </i>MS-&gt;&gt;App: Tokens returned
<i>    </i>App-&gt;&gt;App: Save refresh_token to outlookmail.json
<i>    </i>Note over App: Future launches use saved refresh_token&lt;br/&gt;No user interaction needed!
<e>

// One-time setup at app startup (or in your main module)
static oOutlookMail, hStore

function InitOutlook365()

   local cConfigFile := hb_dirBase() + "outlookmail.json"
   
   hStore := readStore( cConfigFile )
   
   oOutlookMail := TOutlookMail():new()
   
   oOutlookMail:setConfig( {;
      "client_id"     => "paste_your_client_id_here",;
      "client_secret" => "paste_your_client_secret_here",;
      "redirect_uri"  => "http://localhost:5500/";
   } )
   
   if !empty( hStore[ "token" ] )
      oOutlookMail:setToken( hStore[ "token" ] )
   endif
   
   // Check if we need to authenticate (first time only)
   if !oOutlookMail:isAuth()
      local cToken := oOutlookMail:auth()  // Opens browser for user login
      if !empty( cToken )
         hStore[ "token" ] := cToken
         saveStore( cConfigFile, hStore )
      else
         MsgStop( "Microsoft 365 authentication failed!" )
         return .f.
      endif
   endif

return .t.


// Drop-in replacement for your legacy silent email function
function SendOutlook365Mail( cTo, cCC, cSubject, cBody, cAttachment )

   local lSent := .f.

   // Make sure we're connected
   if hb_isNil( oOutlookMail ) .or. !oOutlookMail:isAuth()
      if !InitOutlook365()
         return .f.
      endif
   endif

   // Send the email - this is completely silent!
   // Parameters: aTo, cSubject, cMessage, lHTML, aAttachment, aBCC, aCC
   lSent := oOutlookMail:send( ;
      cTo,         ;   // To recipient(s) - string or array
      cSubject,    ;   // Subject line
      cBody,       ;   // Body content (HTML supported)
      .t.,         ;   // .t. = HTML body, .f. = plain text
      cAttachment, ;   // Attachment path(s) - string or array
      nil,         ;   // BCC (not used here)
      cCC          ;   // CC recipients
   )

   if !lSent
      MsgInfo( "Failed to send email via Outlook 365" )
   endif

return lSent

// OLD LEGACY CODE:
oOutLook  := TOleAuto():New("Outlook.Application")
oMailItem := oOutLook:Invoke("CreateItem", 0)
oMailitem:to := cTo
oMailitem:CC := cCC
oMailItem:Subject := cSubject
oMailItem:Body := cBody
oMailItem:Attachments:Add("c:\dbtmp\"+cPdfName+".pdf")
oMailItem:Send()

// NEW OUTLOOK 365 CODE:
SendOutlook365Mail( ;
   cTo,                                ;  // Employee's supervisor email
   cCC,                                ;  // CC recipients
   cSubject,                           ;  // "Leave Request from John Doe"
   cBody,                              ;  // HTML body with link to app
   "c:\dbtmp\" + cPdfName + ".pdf"     ;  // PDF attachment
)

hPost[ "saveToSentItems" ] := .t.