VB6/ASP - Retrieve email using Microsoft OAuth 2.0 (Modern Authentication) + IMAP4 protocol from Hotmail/Outlook account

You can retrieve email using traditional user/password IMAP4 authentication from personal Hotmail/Outlook account.

However Microsoft will disable traditional user authentication in the future, switching to Microsoft OAuth (Modern Authentication) is strongly recommended now.

Installation

Before you can use the following sample codes, you should download the EAGetMail Installer and install it on your machine at first. Full sample projects are included in this installer.

Add reference

To use EAGetMail POP3 & IMAP4 ActiveX Object in your project, the first step is Add reference of EAGetMail to your project. Please go to menu -> Project -> References -> and select EAGetMailObj ActiveX Object, click OK, the reference will be added to your project, and you can start to use it to retrieve email and parse email in your project.

add reference in VB6

Add reference in VBA (EXCEL/Access/Outlook)

Open VBA IDE by press Alt+F11, Please select menu -> Tools -> References -> and select EASendMailObj ActiveX Object, click OK, the reference will be added to current VBA project, and you can start to use it to retrieve email and parse email in your VBA project.

To better demonstrate how to retrieve email and parse email, let’s create a VB 6.0 Standard EXE project at first, then add a CommandButton on the Form, double-click this button. It is like this

VB 6.0 standard project

Create your application in Azure Portal

To use Microsoft/Office365/Live OAuth (Modern Authentication) in your application, you must create a application in Azure Portal.

  • Sign in to the Azure portal using either a work or school account or a personal Microsoft account.
  • If your account gives you access to more than one tenant, select your account in the top right corner, and set your portal session to the Azure AD tenant that you want.
  • In the left-hand navigation pane, select the Azure Active Directory service, and then select App registrations -> New registration.
azure portal new app registration

Single tenant and multitenant in account type

When the register an application page appears, enter a meaningful application name and select the account type.

Select which accounts you would like your application to support.

  • If your application only supports the users in your directory or organization, please select Single tenant type;
  • If your application needs to support all users in Office 365 and Microsoft personal account (hotmail.com, outlook.com), please select Multitenant type, and you must verify publisher.

Because we want to support all Office 365 and LIVE SDK (hotmail, outlook personal account), so select Accounts in any organizational directory and personal Microsoft accounts.

Important

If you don’t verify publisher for multitenant application, your application will not request access token successfully.

API permission

Now we need to add permission to the application:

  • Click API Permission ->
  • Add a permission -> Microsoft Graph -> Delegated Permission -> User.Read, email, offline_access, openid, profile, SMTP.Send, IMAP.AccessAsUser.All, POP.AccessAsUser.All.
azure application SMTP/POP/IMAP api permission

EWS API permission

With the above permissions, your application can support SMTP, POP and IMAP service. If your application needs to support EWS protocol either, add EWS permission like this:

  • Click API Permission ->
  • Add a permission -> APIs in my organization uses -> Office 365 Exchange Online -> Delegated Permission -> Check EWS.AccessAsUser.All
azure APIs in my organization uses

Here is permissions list:

azure application api permission list

Authentication and redirect uri

Because the example code is based on desktop application, so add Redirect Uri like this:

  • Click "Authentication" -> Add a platform -> Mobile and desktop applications -> Redirect Uri, please check or add the following URI.

    https://login.microsoftonline.com/common/oauth2/nativeclient
    https://login.live.com/oauth20_desktop.srf
    http://127.0.0.1
    

    Note

    • https://login.live.com/oauth20_desktop.srf is used for Live SDK, http://127.0.0.1 is used for local Http Listener.
  • If your application needs to support Microsoft personal account, set both "Live SDK Support" and "Treat application as a public client" to "Yes".

azure application Authentication Overview

Client Id and client secrets

Now we need to create a client secret for the application, click Certificates and secrets -> client secrets and add a new client secret.

azure application api permission

After client secret is created, store the client secret value to somewhere.

Important

Please store client secret value by yourself, because it is hidden when you view it at next time.

Branding and verify publisher

Now we click Branding, you can edit your company logo, URL and application name. If your application supports multitenant (access user in all Office 365 and Microsoft personal account), you must complete the publisher verification.

It is not difficult, you can have a look at publisher verification. After publisher verification is completed, your branding is like this:

azure application Authentication Overview

Important

You must complete the publisher verification for multitenant application, otherwise, your application will not request access token correctly.

Client id and tenant

Now you can click Overview to find your client id and tenant.

azure application client id and tenant
  • If your application is single tenant, use the tenant value in tokenUri and authUri instead of common.
  • If your application is multitenant, use common as tenant.

Above client id and client secret support both "Office365 + SMTP/POP/IMAP/EWS" and "Live (hotmail, outlook personal account) + SMTP/POP/IMAP",

Use client id and client secret to request access token

You can use client id and client secret to get the user email address and access token like this:

  • Your application uses a web browser/browser control to open Oauth Url;
  • User inputs user and password in web authentication page, and then the Oauth server returns access token back to your application;
  • Your application uses access token to access resource on the server.
  • You can find full example codes in EAGetMail Installation Path\Samples_{Programming language/Developer Tool} project.

Access token expiration and refresh token

You don’t have to open browser to request access token every time. By default, access token expiration time is 3600 seconds, you can use the access token repeatedly before it is expired. After it is expired, you can use refresh token to refresh access token directly without opening browser. You can find full sample project in EAGetMail installation path to learn how to refresh token.

Important

You should create your client id and client secret, do not use the client id from example codes in production environment, it is used for test purpose. If you got "This app isn't verified" information, please click "Advanced" -> Go to ... for test.

VB6 - Retrieve email using Microsoft OAuth + Hotmail/Outlook/Live IMAP4 server

Here is a console application which demonstrates how to use Microsoft OAuth to do user authentication and retrieve email using IMAP4 protocol.

Note

This sample cannot handle the event of Web Browser is closed by user manually before authentication is completed. You can refer to the better sample project which uses Web Browser Control in EAGetMail installation path.

Option Explicit

Const MailServerPop3 = 0
Const MailServerImap4 = 1
Const MailServerEWS = 2
Const MailServerDAV = 3

Const MailServerAuthLogin = 0
Const MailServerAuthCRAM5 = 1
Const MailServerAuthNTLM = 2
Const MailServerAuthXOAUTH2 = 3

Const GetMailInfos_All = 1
Const GetMailInfos_NewOnly = 2
Const GetMailInfos_ReadOnly = 4
Const GetMailInfos_SeqRange = 8
Const GetMailInfos_UIDRange = 16
Const GetMailInfos_PR_ENTRYID = 32
Const GetMailInfos_DateRange = 64
Const GetMailInfos_OrderByDateTime = 128

Const CRYPT_MACHINE_KEYSET = 32
Const CRYPT_USER_KEYSET = 4096


' client configuration
' You should create your client id and client secret,
' do not use the following client id in production environment, it is used for test purpose only.
Const clientID = "eccbabb2-3377-4265-85c1-ea2fb515f075"
Const clientSecret = "QaR_RR:-5WqTY[nni9pdBr9xVybqrAu4"
Const scope = "wl.offline_access%20wl.signin%20wl.imap%20wl.emails%20email%20openid"
Const authUri = "https://login.microsoftonline.com/common/oauth2/v2.0/authorize"
Const tokenUri = "https://login.microsoftonline.com/common/oauth2/v2.0/token"

Public Sub DoOauthAndRetrieveEmail()

    Dim httpListener As New EAGetMailObjLib.httpListener

    ' Creates a redirect URI using an available port on the loopback address.
    If Not httpListener.Create("127.0.0.1", 0) Then
        Debug.Print "Failed to listen on " & httpListener.GetLastError()
        Exit Sub
    End If

    Dim szUri
    szUri = "http://127.0.0.1:" & httpListener.ListenPort

    Debug.Print "listen on " & szUri

    ' Creates the OAuth 2.0 authorization request.
    Dim authorizationRequest
    authorizationRequest = authUri
    authorizationRequest = authorizationRequest & "?response_type=code&scope="
    authorizationRequest = authorizationRequest & scope
    authorizationRequest = authorizationRequest & "&redirect_uri="
    authorizationRequest = authorizationRequest & szUri
    authorizationRequest = authorizationRequest & "&client_id="
    authorizationRequest = authorizationRequest & clientID
    authorizationRequest = authorizationRequest & "&prompt=login"

    Debug.Print "open " & authorizationRequest
    ' Opens request in the browser.
    Dim browserUi As New EAGetMailObjLib.browserUi
    browserUi.OpenUrl authorizationRequest

    ' Waits for the OAuth authorization response.
    Do While True
        If Not httpListener.GetRequestUrl(100) Then
            Debug.Print "Failed to wait:"
            Debug.Print httpListener.GetLastError()
            Exit Do
        End If

        If httpListener.RequestUrl <> "" Then
            Exit Do
        End If

        DoEvents
    Loop

    ' Send response and stop http listener.
    httpListener.SendResponse "200", "text/html; charset=utf-8", "<html><head></head><body>Please return to the app and close current window.</body></html>"
    httpListener.Close

    Dim requestUri
    requestUri = httpListener.RequestUrl
    Debug.Print "RequestUri: " & requestUri

    Dim errorCode
    ' Checks for errors.
    errorCode = ParseParameter(requestUri, "error=")
    If errorCode <> "" Then
        Debug.Print "OAuth authorization error: " & errorCode
        Exit Sub
    End If

    ' Check authorization code
    Dim code
    code = ParseParameter(requestUri, "code=")
    If code = "" Then
        Debug.Print "Malformed authorization response: " & requestUri
        Exit Sub
    End If

    Debug.Print "Authorization code: " & code

    Dim responseText
    responseText = RequestAccessToken(code, szUri)
    Debug.Print responseText

    Dim parser As New EAGetMailObjLib.OAuthResponseParser
    parser.Load responseText

    Dim user, accessToken

    user = parser.EmailInIdToken
    accessToken = parser.accessToken

    If accessToken = "" Then
        Debug.Print "Failed to request access token, return!"
        Exit Sub
    End If

    Debug.Print "User: " & user
    Debug.Print "AccessToken: " & accessToken

    RetrieveEmailWithXOAUTH2 user, accessToken
End Sub


' path?parameter1=value1&parameter2=value2#anchor;
Private Function ParseParameter(ByVal uri As String, ByVal key As String) As String

    ParseParameter = ""

    If uri = "" Or key = "" Then
        Exit Function
    End If

    Dim pos As Integer
    pos = InStr(1, uri, "?")
    If pos <= 0 Then
        Exit Function
    End If

    uri = Mid(uri, pos + 1)
    Dim i, parameters, uriParameter
    parameters = Split(uri, "&")

    For i = LBound(parameters) To UBound(parameters)
        uriParameter = parameters(i)
        If InStr(1, uriParameter, key, vbTextCompare) = 1 Then
            Dim value
            value = Mid(uriParameter, Len(key) + 1)

            pos = InStr(1, value, "#")
            If pos > 0 Then
                value = Mid(value, 1, pos - 1)
            End If

            ParseParameter = value
            Exit Function
        End If
    Next


End Function

Private Function RequestAccessToken(ByVal code As String, ByVal redirectUri As String) As String

    Debug.Print "Exchanging code for tokens..."
    RequestAccessToken = ""

    Dim responseText
    responseText = ""

    Dim httpRequest
    Set httpRequest = CreateObject("MSXML2.ServerXMLHTTP.6.0")

    Dim tokenRequestBody
    tokenRequestBody = "code="
    tokenRequestBody = tokenRequestBody & code
    tokenRequestBody = tokenRequestBody & "&redirect_uri="
    tokenRequestBody = tokenRequestBody & redirectUri
    tokenRequestBody = tokenRequestBody & "&client_id="
    tokenRequestBody = tokenRequestBody & clientID
    tokenRequestBody = tokenRequestBody & "&grant_type=authorization_code"

    ' If you request access token in web application, you must add client secret in token request data
    ' tokenRequestBody = "code="
    ' tokenRequestBody = tokenRequestBody & code
    ' tokenRequestBody = tokenRequestBody & "&redirect_uri="
    ' tokenRequestBody = tokenRequestBody & redirectUri
    ' tokenRequestBody = tokenRequestBody & "&client_id="
    ' tokenRequestBody = tokenRequestBody & clientID
    ' tokenRequestBody = tokenRequestBody & "&client_secret="
    ' tokenRequestBody = tokenRequestBody & clientSecret
    ' tokenRequestBody = tokenRequestBody & "&grant_type=authorization_code"

    httpRequest.setOption 2, 13056
    httpRequest.Open "POST", tokenUri, True
    httpRequest.setRequestHeader "Content-Type", "application/x-www-form-urlencoded"
    httpRequest.Send tokenRequestBody

    Do While httpRequest.ReadyState <> 4
        DoEvents
        httpRequest.waitForResponse (1)
    Loop

    Dim Status
    Status = httpRequest.Status
    responseText = httpRequest.responseText

    RequestAccessToken = responseText

    If Status < 200 Or Status >= 300 Then
        Debug.Print "Failed to refresh access token from server."
    End If

End Function

Private Sub RetrieveEmailWithXOAUTH2(ByVal userEmail As String, ByVal accessToken As String)
    Dim curpath As String
    Dim mailbox As String
    Dim oTools As New EAGetMailObjLib.Tools

    ' Create a folder named "inbox" under current directory
    ' to save the email retrieved.
    curpath = App.Path
    mailbox = curpath & "\inbox"
    oTools.CreateFolder mailbox

    Dim oServer As New EAGetMailObjLib.MailServer
    ' Hotmail/Outlook/Live IMAP4 Server address
    oServer.Server = "imap-mail.outlook.com"
    ' Use OAUTH 2.0
    oServer.AuthType = MailServerAuthXOAUTH2
    oServer.user = userEmail
    ' Use access token as password
    oServer.Password = accessToken
    oServer.Protocol = MailServerImap4

    ' Enable SSL/TLS connection
    oServer.SSLConnection = True
    ' Set IMAP SSL Port
    oServer.Port = 993


On Error GoTo ErrorHandle:
    Dim oClient As New EAGetMailObjLib.MailClient
    oClient.LicenseCode = "TryIt"

    Debug.Print "Connecting " & oServer.Server & "..."
    oClient.Connect oServer
    Debug.Print "Connected"

    ' Get new email only, if you want to get all emails, please remove this line
    oClient.GetMailInfosParam.GetMailInfosOptions = GetMailInfos_NewOnly

    Dim infos As EAGetMailObjLib.MailInfoCollection
    Set infos = oClient.GetMailInfoList()
    Debug.Print infos.Count & " emails"

    Dim i As Long
    For i = 0 To infos.Count - 1
        Dim info As EAGetMailObjLib.MailInfo
        Set info = infos.Item(i)

        Debug.Print "Index: " & info.Index & "; Size: " & info.Size & _
        "; UIDL: " & info.UIDL

        ' Receive email from IMAP4 server
        Dim oMail As EAGetMailObjLib.Mail
        Set oMail = oClient.GetMail(info)

        Debug.Print "From: " & oMail.From.Address & _
            vbCrLf & "Subject: " & oMail.Subject

        Dim fileName As String
        ' Generate a random file name by current local datetime,
        ' You can use your method to generate the filename if you do not like it
        fileName = mailbox & "\" & oTools.GenFileName(i) & ".eml"

        ' Save email to local disk
        oMail.SaveAs fileName, True

        ' Mark email as read to prevent retrieving this email again.
        oClient.MarkAsRead info, True

        ' If you want to delete current email, please use Delete method instead of MarkAsRead
        ' oClient.Delete info
    Next

    ' Quit and expunge emails marked as deleted from IMAP4 server.
    oClient.Quit
    Exit Sub

ErrorHandle:
    Debug.Print Err.Description
End Sub

VBScript/ASP - Retrieve email Using Microsoft OAuth + Hotmail/Outlook Live IMAP4 server in ASP

If you use Microsoft OAuth in ASP application, you should use a ASP page to get authorization code instead of HttpListener. You need to add your ASP page path to Authentication -> add a platform -> web -> Redirect URIs in your Azure application.

azure application web redirect uri
' If you request access token in web application, you must add client secret in token request data
tokenRequestBody = "code="
tokenRequestBody = tokenRequestBody & code
tokenRequestBody = tokenRequestBody & "&redirect_uri="
tokenRequestBody = tokenRequestBody & redirectUri
tokenRequestBody = tokenRequestBody & "&client_id="
tokenRequestBody = tokenRequestBody & clientID
tokenRequestBody = tokenRequestBody & "&client_secret="
tokenRequestBody = tokenRequestBody & clientSecret
tokenRequestBody = tokenRequestBody & "&grant_type=authorization_code"
' Please add http://localhost:54098/oauth/token.asp to Authorized redirect URIs in your Google/MS Azure project.
Dim code
code = Request.QueryString("code")

TLS 1.2 protocol

TLS is the successor of SSL, more and more SMTP servers require TLS 1.2 encryption now.

If your operating system is Windows XP/Vista/Windows 7/Windows 2003/2008/2008 R2/2012/2012 R2, you need to enable TLS 1.2 protocol in your operating system like this:

Enable TLS 1.2 on Windows XP/Vista/7/10/Windows 2008/2008 R2/2012

Appendix

Comments

If you have any comments or questions about above example codes, please click here to add your comments.