Gmail-API-Helper

Gmail API helper solution in .NET.

The Gmail API is used to interact with users' Gmail inboxes and settings, supports several popular programming languages. This solution is the implementation of the same providing certain useful extension methods in .NET to retrieve/send/manipulate email messages and manage labels. The solution uses 'Gmail Search Query' to retrieve/manipulate required email messages.

Download

The package is available and can be downloaded using nuget.org package manager.

• Package Name - GmailHelper.

Features

1. Retrieve email message/messages based on query search.

2. Retrieve latest email message body based on query search.

3. Download message/messages attachments based on query search.

4. Send email messages (text/plain, text/html).

5. Send email messages with attachments (text/plain, text/html).

6. Trash/Untrash email message/messages based on query search.

7. Spam/Unspam email message/messages based on query search.

8. Mark email message/messages read/unread based on query search.

9. Modify email message/messages labels based on query search.

10. Retrieve latest email message labels based on query search.

11. Create/update/delete/list Gmail user labels.

    NOTE: 1. Gmail query search operators information can be found here. For examples checkout solution tests.
        2. You can also use Gmail 'Search mail' search criteria option to create search query string.
       
        3. Delete scope requires fully verified app, use move to trash instead.
        4. For sending email with attachments, Gmail standard attachment size limits and file prohibition rules apply.

.NET Supported Versions

Gmail API solution is built on .NetStandard 2.0

Configuration

Reference: Authorizing Your App with Gmail

Detailed Steps:

1. Create a Gmail account/use an existing Gmail account and login to Gmail API Console

   

2. Under 'API & Services' create a new project and provide

   • Project name
   • Organisation, leave as is if none created.
   

3. Select the created project and go to 'Library' under 'API & Services'.

   

4. Search 'Gmail API' and enable the API for the logged in user account.

   

5. In the created project, open 'OAuth consent screen' under 'API & Services' and create a new app with User Type - 'External' or none selected.

   

   In 'OAuth consent screen' provide

   • Under 'App Information'
     • App Name
     • User Support Email
   • Under 'Developer Contact Information'
     • Email Addresses (can be same as 'User Support Email' entered above)
   

   In 'Scopes' search & select the 'Gmail API' scope enabled previously.

   • Gmail API https://mail.google.com/ scope
   

   Can leave the rest as is and save.

   

   On created app under 'Publishing Status' click

   • PUBLISH APP
     
     
   

   NOTE: Some added restricted/sensitive scopes may require app verification.

6. Under 'API & Services' go to 'Credentials' and create new credentials of type 'OAuth client ID'.

   

7. Provide below details

   • Application type as 'Desktop app'
   • Name
   

8. Download the json and save the file as 'credentials.json'. This needs to be added to the solution to generate OAuth token.

   

9. Include the 'credentials.json' in the solution project and invoke GmailHelper.GetGmailService() function below to generate OAuth token.

   GmailHelper.GetGmailService(<Created Application Name>, <'token.json' path for OAuth to be saved>)
   

10. Sign-In to the login prompt presented with user account used to create the app.

    

    NOTE: 'Google hasn't verified this app' may be prompted if the app is yet to be verified. Go to 'Advanced' and continue.

11. Select the Gmail API access as added to the app scope 'Read, compose, send and permanently delete all your email from Gmail' and continue.

    

12. Once you see 'Received verification code. You may now close this window.', you can close the browser window and save the contents of 'token.json' to reuse until credentials are changed or refreshed. The token path parameter in GmailHelper.GetGmailService() can be used to save and reuse the generated OAuth token again and again.

    NOTE: Keep contents of 'token.json' & 'credentials.json' safe to avoid any misuse. Checkout solution tests for more understanding on usage.

13. For concurrent usage create a lock object for the used extension methods in a non-static class.
    Examples:

public class Gmail {
  private static readonly object _lock = new object();

  public static Message GetMessage() {
    var service = GmailHelper.GetGmailService(applicationName: "GmailAPIHelper");
    Message message = null;
    lock(_lock) {
      message = GmailHelper.GetMessage(service, query: "[from:[email protected]][subject:'READ EMAIL']in:inbox is:read", markRead: true);
    }
    return message;
  }
}

public class Gmail {
  private static readonly object _lock = new object();

  public static Message GetMessage() {
    Message message = null;
    lock(_lock) {
      message = GmailHelper.GetGmailService(applicationName: "GmailAPIHelper")
        .GetMessage(query: "[from:[email protected]][subject:'READ EMAIL']in:inbox is:read", markRead: true);
    }
    return message;
  }
}