Using Gmail/GSuite IMAP OAUTH with Service Account

The Gmail/GSuite IMAP and SMTP servers have been extended to support authorization via the industry-standard OAuth 2.0 protocol. Using OAUTH protocol, user can do authentication by Gmail Web OAuth instead of inputting user and password directly in application.

You can click here to learn more detail about "OAUTH/XOAUTH2 with Gmail IMAP Server".

Google Service Account

Normal OAUTH requires user input user/password for authentication. Obviously, it is not suitable for background service. In this case, you should use google service account to access G Suite email service without user interaction. Service account only works for G Suite user, it doesn't work for personal Gmail account.

Create your project in Google Developers Console

To use "G Suite Service Account OAUTH" in your application, you should create a project in Google Developers Console at first.

Important Notice: You can use any google user to create service account, it doesn't require service account owner is a user in G Suite. But G Suite administrator must authorize service account in G Suite Admin Console to access user mailbox.

Open Google Developer Console, create a new project by https://console.developers.google.com/projectcreate.
After you created the project, select it from projects list as current project.

Create service account under current project

Click "Credentials" -> "Manage service accounts"
Click "CREATE SERVICE ACCOUNT"
Input a name for your service account, click "CREATE"
In "Service account permissions", select "Project" -> "Owner" as role
In "Grant users access to this service account", keep everything default and click "DONE"

After service account is created, you should enable "Domain-wide delegation" and create service key pair to access G Suite user mailbox.

Enable "Domain-wide delegation" and create service key

Go back to your service account, click "Edit" -> "SHOW DOMAIN-WIDE DELEGATION", check "Enable G Suite Domain-wide Delegation", input a name for product oauth consent, click "Save".
Go back to your service account again, click "Create Key", you can select "p12" or "json" key type, both can work well, then you will get a file which contains private key, save the file to local disk.

Now you have created service account with key pair successfully. You can use created private key in your codes to request "access token" impersonating a user in G Suite.
To access user data in G Suite, you must get authorization from G Suite administrator. You should go to service accounts list, click "View Client ID" like this:
Then record your "Client ID" and service account email address, forward it to G Suite administrator for authorization.

Authorize service account by G Suite administrator

To use service account to access user mailbox in G Suite, G Suite Administrator should authorize specified service account at first.

G Suite Administrator should open admin.google.com, go to Admin Console, click "Security";
Click "Advanced settings" -> "Manage API client access";
Input service account "Client ID" in Client Name, and input "https://mail.google.com/,email,profile" in One or More API Scopes, click "Authorize".

After G Suite administrator authorized service account, you can use it to access any users mailbox in G Suite domain.

Use service account to send email impersonating user in G Suite Domain

The following examples demonstrate how to send email with service account + G Suite OAUTH

Example

[C# - Use service account to retrieve email impersonating user in G Suite Domain]
// You can install Google.Apis.Auth.OAuth2 by NuGet
// Install-Package Google.Apis.Auth
using System;
using System.Globalization;
using System.Collections.Generic;
using System.Text;
using System.Threading;
using System.Threading.Tasks;
using System.Security.Cryptography.X509Certificates;
using System.Net;
using System.IO;
using Google.Apis.Auth.OAuth2;
using EAGetMail;

class TestClass
{
    // Generate an unqiue email file name based on date time
    static string _generateFileName(int sequence)
    {
        DateTime currentDateTime = DateTime.Now;
        return string.Format("{0}-{1:000}-{2:000}.eml",
            currentDateTime.ToString("yyyyMMddHHmmss", new CultureInfo("en-US")),
            currentDateTime.Millisecond,
            sequence);
    }

    public void ReceiveMailByOauth()
    {
        try
        {
            // service account email address
            const string serviceAccount = "xxxxxx@xxxxx.iam.gserviceaccount.com";

            // import service account key p12 certificate.
            var certificate = new X509Certificate2("D:\\MyData\\myoauth-77dec4d192ec.p12",
                "notasecret", X509KeyStorageFlags.Exportable);

            // G Suite user email address
            var gsuiteUser = "user@gsuitdomain.com";

            var serviceAccountCredentialInitializer = new ServiceAccountCredential.Initializer(serviceAccount)
            {
                User = gsuiteUser,
                Scopes = new[] { "https://mail.google.com/"}

            }.FromCertificate(certificate);

            // if service account key is in json format, copy the private key from json file: 
            // "private_key": "-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----\n"
            // and import it like this:
            // string privateKey = "-----BEGIN PRIVATE KEY-----\nMIIEv...revdd\n-----END PRIVATE KEY-----\n";

            // var serviceAccountCredentialInitializer = new ServiceAccountCredential.Initializer(serviceAccount)
            //{
            //    User = gsuiteUser,
            //    Scopes = new[] { "https://mail.google.com/" }
            // }.FromPrivateKey(privateKey);

            // request access token
            var credential = new ServiceAccountCredential(serviceAccountCredentialInitializer);
            if (!credential.RequestAccessTokenAsync(CancellationToken.None).Result)
                throw new InvalidOperationException("Access token failed.");

                
            // Create a folder named "inbox" under current directory
            // to save the email retrieved.
            string localInbox = string.Format("{0}\\inbox", Directory.GetCurrentDirectory());
            // If the folder is not existed, create it.
            if (!Directory.Exists(localInbox))
            {
                Directory.CreateDirectory(localInbox);
            }

            // use SSL IMAP + XOAUTH2
            MailServer oServer = new MailServer("imap.gmail.com", gsuiteUser, credential.Token.AccessToken, true,
                ServerAuthType.AuthXOAUTH2, ServerProtocol.Imap4);
            
            oServer.Port = 993;

            Console.WriteLine("Connecting server ...");

            MailClient oClient = new MailClient("TryIt");
            oClient.Connect(oServer);

            Console.WriteLine("Retreiving email list ...");
            MailInfo[] infos = oClient.GetMailInfos();
            Console.WriteLine("Total {0} email(s)", infos.Length);

            for (int i = 0; i < infos.Length; i++)
            {
                Console.WriteLine("Checking {0}/{1} ...", i + 1, infos.Length);
                MailInfo info = infos[i];

                // Generate an unqiue email file name based on date time.
                string fileName = _generateFileName(i + 1);
                string fullPath = string.Format("{0}\\{1}", localInbox, fileName);

                Console.WriteLine("Downloading {0}/{1} ...", i + 1, infos.Length);
                Mail oMail = oClient.GetMail(info);

                // Save mail to local file
                oMail.SaveAs(fullPath, true);

                // Mark the email as deleted on server.
                Console.WriteLine("Deleting ... {0}/{1}", i + 1, infos.Length);
                oClient.Delete(info);
            }

            Console.WriteLine("Disconnecting ...");

            // Delete method just mark the email as deleted, 
            // Quit method expunge the emails from server permanently.
            oClient.Quit();

            Console.WriteLine("Completed!");
        }
        catch (Exception ep)
        {
            Console.WriteLine("Error: {0}", ep.Message);
        }
    }
}


[VB.NET - Use service account to retrieve email impersonating user in G Suite Domain]
' You can install Google.Apis.Auth.OAuth2 by NuGet
' Install-Package Google.Apis.Auth
Imports System
Imports System.Globalization
Imports System.Collections.Generic
Imports System.Text
Imports System.Threading
Imports System.Threading.Tasks
Imports System.Security.Cryptography.X509Certificates
Imports System.Net
Imports Google.Apis.Auth.OAuth2
Imports EAGetMail

Public Class TestClass
    ' Generate an unqiue email file name based on date time.
    Shared Function _generateFileName(ByVal sequence As Integer) As String
        Dim currentDateTime As DateTime = DateTime.Now
        Return String.Format("{0}-{1:000}-{2:000}.eml",
                            currentDateTime.ToString("yyyyMMddHHmmss", New CultureInfo("en-US")),
                            currentDateTime.Millisecond,
                            sequence)
    End Function
    
    Public Sub ReceiveMailByOauth()

        Try
            ' service account email address
            Const serviceAccount As String = "xxxxxx@xxxxx.iam.gserviceaccount.com"

            ' import service account key p12 certificate.
            Dim certificate = New X509Certificate2("D:\MyData\myoauth-77dec4d192ec.p12", "notasecret", X509KeyStorageFlags.Exportable)

            ' G Suite user email address
            Dim gsuiteUser = "user@gsuitdomain.com"

            Dim serviceAccountCredentialInitializer = New ServiceAccountCredential.Initializer(serviceAccount) With {
                .User = gsuiteUser,
                .Scopes = {"https://mail.google.com/"}
            }.FromCertificate(certificate)

            ' if service account key is in json format, copy the private key from json file: 
            ' "private_key": "-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----\n"
            ' and import it like this:

            ' Dim privateKey As String = "-----BEGIN PRIVATE KEY-----" & vbLf & "MIIEv...revdd" & vbLf & "-----END PRIVATE KEY-----" & vbLf
            ' Dim serviceAccountCredentialInitializer = New ServiceAccountCredential.Initializer(serviceAccount) With {
            '    .User = gsuiteUser,
            '    .Scopes = {"https://mail.google.com/"}
            ' }.FromPrivateKey(privateKey)

            ' request access token
            Dim credential = New ServiceAccountCredential(serviceAccountCredentialInitializer)
            If Not credential.RequestAccessTokenAsync(CancellationToken.None).Result Then 
                Throw New InvalidOperationException("Access token failed.")
            End If
            
            ' Create a folder named "inbox" under current directory
            ' to save the email retrieved.
            Dim localInbox As String = String.Format("{0}\inbox", Directory.GetCurrentDirectory())

            ' If the folder is not existed, create it.
            If Not Directory.Exists(localInbox) Then
                Directory.CreateDirectory(localInbox)
            End If

            ' use SSL IMAP + XOAUTH2
            Dim oServer As New MailServer("imap.gmail.com", gsuiteUser, credential.Token.AccessToken, True,
                        ServerAuthType.AuthXOAUTH2, ServerProtocol.Imap4)

            oServer.Port = 993

            Console.WriteLine("Connecting server ...")
            Dim oClient As New MailClient("TryIt")
            oClient.Connect(oServer)

            Console.WriteLine("Retrieving email list ...")
            Dim infos() As MailInfo = oClient.GetMailInfos()

            Console.WriteLine("Total {0} email(s)", infos.Length)

            For i As Integer = 0 To infos.Length - 1
                Console.WriteLine("Checking {0}/{1}", i + 1, infos.Length)
                Dim info As MailInfo = infos(i)

                ' Generate an unqiue email file name based on date time.
                Dim fileName As String = _generateFileName(i + 1)
                Dim fullPath As String = String.Format("{0}\{1}", localInbox, fileName)

                Console.WriteLine("Downloading {0}/{1}", i + 1, infos.Length)
                Dim oMail As Mail = oClient.GetMail(info)

                ' Save email to local disk
                oMail.SaveAs(fullPath, True)

                ' Mark email as deleted on server.
                Console.WriteLine("Deleting ... {0}/{1}", i + 1, infos.Length)
                oClient.Delete(info)
            Next

            Console.WriteLine("Disconnecting ...")
            ' Delete method just mark the email as deleted, 
            ' Quit method expunge the emails from server permanently.
            oClient.Quit()

            Console.WriteLine("Completed!")
        Catch ep As Exception
            Console.WriteLine("Error: {0}", ep.Message)
        End Try

    End Sub

End Class

Remarks

You don't have to request access token every time, once you get an access token, it is valid within 3600 seconds.

If you don't want to use OAUTH 2.0, Gmail also supports traditional IMAP authentication, but you need to enable Allowing less secure apps or Sign in using App Passwords.

Online Tutorials

C# - Retrieve Email using Google/Gmail OAuth 2.0 Authentication + IMAP Protocol
C# -Retrieve Email using Gmail/G Suite OAuth 2.0 + IMAP4 Protocol in Background Service (Service Account)
C# -Retrieve Email using Microsoft OAuth 2.0 (Modern Authentication) + IMAP4 Protocol from Hotmail/Outlook Account
C# -Retrieve Email using Microsoft OAuth 2.0 (Modern Authentication) + EWS/IMAP4 Protocol from Office 365 Account
C# -Retrieve Email using Microsoft OAuth 2.0 (Modern Authentication) + EWS Protocol from Office 365 in Background Service

VB - Retrieve Email using Google/Gmail OAuth 2.0 Authentication + IMAP Protocol
VB -Retrieve Email using Gmail/G Suite OAuth 2.0 + IMAP4 Protocol in Background Service (Service Account)
VB -Retrieve Email using Microsoft OAuth 2.0 (Modern Authentication) + IMAP4 Protocol from Hotmail/Outlook Account
VB -Retrieve Email using Microsoft OAuth 2.0 (Modern Authentication) + EWS/IMAP4 Protocol from Office 365 Account
VB -Retrieve Email using Microsoft OAuth 2.0 (Modern Authentication) + EWS Protocol from Office 365 in Background Service

C++/CLR - Retrieve Email using Google/Gmail OAuth 2.0 Authentication + IMAP Protocol
C++/CLR -Retrieve Email using Gmail/G Suite OAuth 2.0 + IMAP4 Protocol in Background Service (Service Account)
C++/CLR -Retrieve Email using Microsoft OAuth 2.0 (Modern Authentication) + IMAP4 Protocol from Hotmail/Outlook Account
C++/CLR -Retrieve Email using Microsoft OAuth 2.0 (Modern Authentication) + EWS/IMAP4 Protocol from Office 365 Account
C++/CLR -Retrieve Email using Microsoft OAuth 2.0 (Modern Authentication) + EWS Protocol from Office 365 in Background Service