How to execute Gmail API request using Service Account - C# .NET 6

Where and How to Use Service Account?

A service account is a special kind of account used by an application, rather than a person.

You can use a service account to access data or perform actions by the robot account itself, or to access data on behalf of Google Workspace or Cloud Identity users.

In this post, I will review how to execute Gmail API requests using Service Account

see the full sample code on GitHub

Prerequisites

1. A Google Cloud Platform project
   With the Admin SDK API enabled service account with domain-wide delegation.
2. A Google Workspace domain.
   With an active account and granted administrator privileges.
3. Visual Studio 2013 or later

Step 1: Set up the Google Cloud Platform project

• Create a Google Cloud project
  A Google Cloud project is required to use Google Workspace APIs and build Google Workspace add-ons or apps. If you don't already have a Google Cloud project, refer to: How to Create a Google Cloud project
• Enable Google Workspace APIs
  Before using Google APIs, you need to enable them in a Google Cloud project. To Enable Google Workspace APIs refer to How to Enable Google Workspace APIs
• Create a Service Account with a domain-wide delegation
  To create a service account refer to How to create a service account? In the Domain Wide delegation pane, select Manage Domain Wide Delegation.
• Download Service Account private key (p12 format)
  Download p12 file containing the private key for your Service Account.

Step 2: Set up the Google Workspace

• Enable API access in the Google Workspace domain with
  To enable API access in the Google Workspace domain, refer to how to enable API access
• Delegating domain-wide authority to the service account
  To call APIs on behalf of users in a Google Workspace organization, your service account needs to be granted a domain-wide delegation of authority in the Google Workspace Admin console by a super administrator account.
  To delegate domain-wide authority in the Google Workspace domain, refer to How to Delegate domain-wide authority to the service account.

Step 3: Prepare Visual Studio project

• Create a new Visual C# ASP.NET Core WebAPI (.NET 6.0) project in Visual Studio.
• Open the NuGet Package Manager Console, select the package source nuget.org, and run the following commands:
  Install-Package Google.Apis.Auth
  Install-Package Google.Apis.Gmail.v1

Step 4: Add code 

See the full c# code sample of "How to Use Service Account" on my GitHub

Add code to provide the certificate

using System.Security.Cryptography.X509Certificates;
namespace Gapis.SA.Core.Services;
public interface ICertificateProvider : IDisposable {
X509Certificate2 Certificate { get; }
}
public class CertificateProvider : ICertificateProvider, IDisposable {
public X509Certificate2 Certificate { get; }
public CertificateProvider(string fileName) {
this.Certificate = new X509Certificate2(
fileName,
"notasecret",
X509KeyStorageFlags.MachineKeySet | X509KeyStorageFlags.Exportable);
}
...

Add code to initiate service account

using Google.Apis.Auth.OAuth2;

using Google.Apis.Gmail.v1;
using Google.Apis.Services;
namespace Gapis.SA.Core.Services;
public class GoogleServiceProvider : IGoogleServiceProvider, IDisposable {
private readonly ICertificateProvider? _certificateProvider;
public string ServiceAccountId { get; }
public GoogleServiceProvider(ICertificateProvider? certificateProvider, string serviceAccountId) {
this._certificateProvider = certificateProvider;
this.ServiceAccountId = serviceAccountId;

Add code to user Gmail Client with the Service Account

using Google.Apis.Gmail.v1;namespace Gapis.SA.Core.Services;
public interface IGmailClientService : IDisposable {
Task<IList<Google.Apis.Gmail.v1.Data.Thread>> ListThreadsAsync(string userId);
}
public class GmailClientService : IGmailClientService, IDisposable {
private readonly IGoogleServiceProvider _provider;
public GmailClientService(IGoogleServiceProvider provider) {
this._provider = provider;
}
public void Dispose() {
if (this._provider != null) {
_provider.Dispose();
...

Initiate middleware service

using Gapis.SA.Core.Services;

var builder = WebApplication.CreateBuilder(args);
// The full path; name of a certificate file
builder.Services.AddSingleton<IGoogleServiceProvider>((provider) => {
var certificte = provider.GetService<ICertificateProvider>();
return new GoogleServiceProvider(certificate, serviceAccountId);
});
builder.Services.AddTransient<IGmailClientService, GmailClientService>();

Bundle all together to execute the request

public GmailController(ILogger<GmailController> logger, IGmailClientService gmailClient) {
_logger = logger;
_gmailClient = gmailClient;
}}

See full c# sample and code at GitHub

Advanced Filter and Search Support

Go beyond the use of regular searches, which are limited in scope. Use Gmail Reader to leverage the power of advanced search operators (or special commands and parameters) to dig deeper and narrow your searches when hunting for information.

You can use words or symbols called search operators to filter your Gmail search results. You can also combine operators to filter your results even more.

How to use a search operator

1. Login to Gmail Reader

Once installed the app are accessible through the App Launcher

2. In the search box, type the search operator.

What you can search by	Search operator & example
Specify the sender	`from:` Example: `from:amy`
Specify a recipient	`to:` Example: `to:david`
Specify a recipient who received a copy	`cc:` `bcc:` Example: `cc:david`
Words in the subject line	`subject:` Example: `subject:dinner`
Messages that match multiple terms	`OR` or `{ }` Example: `from:amy OR from:david` Example: `{from:amy from:david}`
Remove messages from your results	`-` Example: `dinner -movie`
Find messages with words near each other. Use the number to say how many words apart the words can be Add quotes to find messages in which the word you put first stays first.	`AROUND` Example: `holiday AROUND 10 vacation` Example: `"secret AROUND 25 birthday"`
Messages that have a certain label	`label:` Example: `label:friends`
Messages that have an attachment	`has:attachment` Example: `has:attachment`
Messages that have a Google Drive, Docs, Sheets, or Slides attachment or link	`has:drive` `has:document` `has:spreadsheet` `has:presentation` Example: `has:drive`
Messages that have a YouTube video	`has:youtube` Example: `has:youtube`
Messages from a mailing list	`list:` Example: `list:info@example.com`
Attachments with a certain name or file type	`filename:` Example: `filename:pdf` Example: `filename:homework.txt`
Search for an exact word or phrase	`" "` Example: `"dinner and movie tonight"`
Group multiple search terms together	`( )` Example: `subject:(dinner movie)`
Messages in any folder, including Spam and Trash	`in:anywhere` Example: `in:anywhere movie`
Messages in any folder, including Spam and Trash	`is:important` `label:important` Example: `is:important`
Starred, snoozed, unread, or read messages	`is:starred` `is:snoozed` `is:unread` `is:read` Example: `is:read is:starred`
Messages that include an icon of a certain color	`has:yellow-star` `has:blue-info` Example: `has:purple-star`
Recipients in the cc or bcc field	`cc:` `bcc:` Example: `cc:david` Note: You can't find messages that you received on bcc.
Search for messages sent during a certain time period	`after:` `before:` `older:` `newer:` Example: `after:2021/04/16` Example: `after:04/16/2021` Example: `before:2021/04/18` Example: `before:04/18/2021`
Search for messages older or newer than a time period using d (day), m (month), and y (year)	`older_than:` `newer_than:` Example: `newer_than:2d`
Chat messages	`is:chat` Example: `is:chat movie`
Search by email for delivered messages	`deliveredto:` Example: `deliveredto:username@gmail.com`
Messages in a certain category	`category:primary` `category:social` `category:promotions` `category:updates` `category:forums` `category:reservations` `category:purchases` Example: `category:updates`
Messages larger than a certain size in bytes	`larger:` `smaller:` Example: `larger:10M`
Results that match a word exactly	`+` Example: `+unicorn`
Messages with a certain message-id header	`Rfc822msgid:` Example: `rfc822msgid:200503292@example.com`
Messages that have or don't have a label	`has:userlabels` `has:nouserlabels` Example: `has:nouserlabels` Note: Labels are only added to a message, and not an entire conversation.

Note: When using numbers as part of your query, a space or a dash (-) will separate a number while a dot (.) will be a decimal. For example, 01.2047-100 is considered 2 numbers: 01.2047 and 100.