Help the legacy email application that does not support OAUTH to send and retrieve email from Gmail/Google Workspace by EA Oauth Service - Tutorial¶

How EA Oauth Service works?¶

• Install "EA Oauth Service" on your machine.
• Create a local user in "EA Oauth Service Manager", and add a mapped Gmail or Google Workspace user access token.
• Change the email server address to localhost, and use local user and password in your application to login local SMTP/POP/IMAP services.
• After "EA Oauth Service" accepts the connection from local user, it connects Gmail server by the associated access token in background.
• Finally, "EA Oauth Service" transfers data between the email application and Gmail server under SSL/TLS encryption.
• The access token is refreshed by "EA Oauth Service" automatically.

You just need to change the server address, user and password in the email application, then the application can connect Gmail/Google Workspace without changing other things.

Install EA Oauth Service¶

You can download EA Oauth Service Installer and install it on your machine.

Double click the installer file and the installation will be executed automatically. The installer requires .NET framework 4.5 or later version to be installed. If no corresponding .NET framework is detected in your operating system, Setup will be aborted.

After the installation is completed, click “EA Oauth Service Manager” from Windows Start menu -> All Programs -> “EA Oauth Service” to begin the setup.

Check local SMTP/POP/IMAP services¶

After EA Oauth Service is installed, it provides SMTP/POP/IMAP services on the local machine. You can open EA Oauth Service Manager -> Services to check the service status.

By default, the following inbound ports is used:

• SMTP Service: 25, 465
• POP Service: 110, 995
• IMAP Service: 143, 993

Create local user in Oauth Service Manager¶

Now you need to create a local user in EA Oauth Service Manager -> Users:

• Input your Gmail/Google Workspace email address as local user name.
• Set a local password, this password is not your Gmail/Google Workspace password, it is used to connect local SMTP/POP/IMAP service.
• Select permission (SMTP, POP/IMAP).

Now you need to add a mapped Gmail/Google Workspace email account access token. There are two options:

Connect Gmail by user login¶

With this option, you need to create a project and OAUTH client in Google Developer Console. This option can work with both Gmail personal account and Google Workspace account.

Please click the following link to learn how to create the project and OAUTH client in Google Developer Console:

Create project and OAUTH client in Google Developer Console

After you input the created client id, client secret, then click Save,

Then you will be asked to login your Gmail/Google Workspace account by web browser.

Please have the following option checked, by default it is not checked due to Google security policy.

After the access token is retrieved successfully, you can see the token creation time and expiration time.

Note

It requires you re-login the Gmail/Google Workspace account before the refresh token is expired (about every 3 months).

Connect Gmail service account (service mode)¶

With this option, you need to create a project and service account in Google Developer Console.

This option only works with Google Workspace account, personal Gmail acount is not supported.

Please click the following link to learn how to create the project and service account in Google Developer Console:

Create project and service account in Google Developer Console

After you input the service account (you can import the json file by clicking Service Account), private key id, private key and the mappded Gmail/Google Workspace email address, then click Save, a new access token will be retrieved automatically.

Note

You don’t have to re-login the Google Workspace account until the client secret is expired. The maximum lifetime of client secret value is 24 months.

Change server setting in the email application¶

After you create the local user and get the associated access token, the next step is changing your server settings in the application.

Use the following server address and port in the email application:

Here is the example setting in Outlook:

Then use the local user and local password (not your Gmail/Google Workspace password) for user authentication in the email application.

After the application connects local SMTP/POP/IMAP service successfully provided by EA Oauth Service, the service will connect Gmail server by associated access token, and transfer data back to the application under SSL/TLS encryption.

Now the email application can send and retrieve email from Gmail/Google Workspace even it doesn’t support OAUTH.

Example code for C# application¶

Here is an example code for sending email using System.NET.Mail with OAUTH service:

using System;
using System.Net.Mail;

public static void SendEmail()
{
    var mailMessage = new MailMessage();

    // local user
    string office365OrGmailAddress = "test@o365orgmail.com";

    mailMessage.From = new MailAddress(office365OrGmailAddress);
    mailMessage.To.Add(new MailAddress("support@emailarchitect.net"));

    mailMessage.Subject = "Test from Oauth Service";
    mailMessage.IsBodyHtml = false;
    mailMessage.Body = "This is a test";

    var basicCredential = new System.Net.NetworkCredential(office365OrGmailAddress, "local password");

    var smtp = new SmtpClient("localhost");
    smtp.Port = 25;
    smtp.DeliveryFormat = SmtpDeliveryFormat.International;
    smtp.EnableSsl = true;
    smtp.DeliveryMethod = SmtpDeliveryMethod.Network;

    smtp.UseDefaultCredentials = false;
    smtp.Credentials = basicCredential;

    smtp.Send(mailMessage);
}

Allow unauthenticated user to send email¶

By default, EA Oauth Service requires user authentication to send email. If your legacy application doesn’t support user authentication, you can allow unauthenticated user to send email by changing the setting in EA Oauth Service Manager -> Users -> User setting -> Allow unauthenticated user to send email. You need to use the user’s email address as the email sender, then the matched token or credential is used automatically.

Accept remote connections from other machine¶

The legacy email application also can access the SMTP/POP/IMAP service from a remote machine.

• Add access rule in Windows Firewall to allow inbound 25, 465, 110, 143, 993, 995 port;
• Change listening address from localhost to * ;
• Ignore the SSL certificate error in your application.

EA Oauth Service installed a self-signed certificate for SSL/TLS connection, the certificate is issued to localhost. If the application accesses the service from a remote machine, a certificate error will be reported.

You can use other SSL certificate by selecting certificate from EA Oauth Service Manager -> SMTP/POP/IMAP service -> Ssl Certificate.

Troubleshooting¶

Authentication is failed¶

If you get error about “Authentication”:

• Check if the local password is set to the email application correctly;
• Go to EA Oauth Service Manager -> Users -> Check if there is any token error.

If there is token error, edit this user and try to:

• Re-login your Gmail account to retrieve new access token.
• Check if the client secret value is expired, and create a new secret value in Azure Portal to replace current one.

Restart-Service "EAOauthSvc"

Free Email Support¶

Not enough? Please contact our technical support team.

Support@EmailArchitect.NET

Remarks

We usually reply emails within 24hours. The reason for getting no response is likely that your SMTP server bounced our reply. In this case, please try to use another email address to contact us. Your Gmail, Hotmail or Office 365 email account is recommended.