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.


Create service account under current project

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


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.

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.

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.

See Also

Using EAGetMail POP3 & IMAP4 .NET Component
User Authentication and SSL Connection
Enable TLS 1.2 on Windows XP/2003/2008/7/2008 R2
Using Gmail IMAP4 OAUTH
Using Office365 EWS OAUTH
Using Office365 EWS OAUTH in Background Service
Using Hotmail IMAP4 OAUTH
Digital Signature and E-mail Encryption/Decryption
Unique Identifier (UIDL) in POP3 and IMAP4 protocol
Parse Bounced Email (delivery-report)
Work with winmail.dat (TNEF Parser)
EAGetMail Namespace References
EAGetMail POP3 & IMAP4 Component Samples

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